Link Component
Overview
Using Agave Link is simple: you only need to install an initialization script and open the component with Source System that you would like to make available to your Users.
Installation
Javascript
Include the Agave Link initialize script on each page of your site. This script must always be loaded directly from https://app.agaveapi.com/init.js, rather than included in a bundle or hosted by you.
<script src="https://app.agaveapi.com/init.js"></script>
React Component
npm install @agave-api/react-agave-link
Example React app: react-agave-link-example
Vue.js Component
Interested in a Vue.js component? Let us know at api-support@agaveapi.com!
openLink
Options
After installing the script, you can open Agave Link by invoking AgaveLink.openLink(options)
.
The options
object has the following structure:
interface OpenLinkConfig {
linkToken: string;
onSuccess: (publicToken: string) => void;
onExit?: (error?: string) => void;
showSandboxSourceSystems?: boolean;
showProductionSourceSystems?: boolean;
sourceSystem?: string[]|string;
sourceSystemEnvironment?: string;
sourceSystemOptions?: Object;
category?: string;
}
linkToken
Required.
This is the link token you get after calling /link/token
(see Quickstart).
onSuccess
Required.
A callback function for when a User
has successfully linked their account. This callback takes one argument: publicToken
.
onExit
Optional.
A callback function that is called when either a User
closes the Link popup, or when an uncaught exception is returned (in which case, an error
string parameter is included).
showSandboxSourceSystems
Optional. Default:
false
.
A boolean value that, when set to true, displays sandbox Source Systems. You should only use this during development.
Note that not all Source Systems support sandbox environments. See Sandbox Environments for more information and a list of source systems that support sandbox environments.
showProductionSourceSystems
Optional. Default:
true
.
A boolean value that, when set to false, hides production Source Systems. You should only use this during development.
sourceSystem
Optional. Default:
null
. Possible values:procore
,plangrid
,service-titan
,quick-books-online
, or other Source Systems returned from the/link/source-systems
endpoint or an array of one or more of the aformentioned values.
Allows you to open Agave Link directly into one or more Source Systems instead of displaying a full selection screen.
sourceSystemEnvironment
Optional. Default:
prod
. Possible values:sandbox
orprod
.
This parameter is only taken into account when the sourceSystem
parameter is present. It is useful during development, if you want to directly open a Source Systemin a sandbox environment.
Note that not all Source Systems support sandbox environments. See Sandbox Environments for more information and a list of source systems that support sandbox environments.
sourceSystemOptions
Optional. Default:
null
. Possible values: A JSON object.
Using this option, you can pass additional options to Agave Link.
Currently, the only option is passing the company_id
for Procore (see example).
category
Optional. Default:
null
. Possible values:accounting
,construction
,field-service
, orhris
.
Allows you to limit the Source Systems displayed in the selection screen to a single category (e.g. "construction").
iframeId
Optional.
If you want to provide us with an <iframe>
element that's already on your page, you can pass its identifier here.
theme
Optional. Default:
light
. Possible values:light
,dark
.
Allows you to pick light or dark theme when you embed the Link component in your own <iframe>
.
Basic Examples
- Minimal Options
- Show Sandbox Source Systems
- Specific Source System
- Multiple Source Systems
- Specific Source System (Sandbox)
- Specific Category
openLink
function:window.AgaveLink.openLink({
linkToken: linkToken,
onSuccess: (publicToken) => {
// Send publicToken to your server
}
});
window.AgaveLink.openLink({
linkToken: linkToken,
onSuccess: (publicToken) => {
// Send publicToken to your server
},
showSandboxSourceSystems: true
});
window.AgaveLink.openLink({
linkToken: linkToken,
onSuccess: (publicToken) => {
// Send publicToken to your server
},
sourceSystem: 'service-titan'
});
window.AgaveLink.openLink({
linkToken: linkToken,
onSuccess: (publicToken) => {
// Send publicToken to your server
},
sourceSystem: ['service-titan', 'procore']
});
window.AgaveLink.openLink({
linkToken: linkToken,
onSuccess: (publicToken) => {
// Send publicToken to your server
},
sourceSystem: 'service-titan',
sourceSystemEnvironment: 'sandbox'
});
window.AgaveLink.openLink({
linkToken: linkToken,
onSuccess: (publicToken) => {
// Send publicToken to your server
},
category: 'accounting'
});
Advanced Examples
- Source System Options
window.AgaveLink.openLink({
linkToken: linkToken,
onSuccess: (publicToken) => {
// Send publicToken to your server
},
sourceSystem: 'procore',
sourceSystemOptions: {
procore: {
company_id: 31936
}
}
});
Troubleshooting
Certain browsers (e.g. Safari) block thrid-party cookies by default. Agave Link uses cookies to protect against CSRF/XSRF and will not work correctly in these browsers.
Agave Link automatically detects this situation and presents your users with instructions to fix the issue.