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 options are passing company_id or require_cross_company_access 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").

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​

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.