Skip to main content

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

info

Interested in a Vue.js component? Let us know at api-support@agaveapi.com!

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 or prod.

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, or hris.

Allows you to limit the Source Systems displayed in the selection screen to a single category (e.g. "construction").

Basic Examples

This is the minimal configuration you must pass to the openLink function:
window.AgaveLink.openLink({
linkToken: linkToken,
onSuccess: (publicToken) => {
// Send publicToken to your server
}
});

Advanced Examples

This will change the "Select Your Company" screen after the customer has successfully authenticated with Procore. In this example, you can force Agave Link to only display a single Procore company in the list.
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.