All Products
Link
API
Pay Distribution
Console
Changelog

Argyle Link

Overview

Argyle Link is a front-end UI element that allows users to grant your application access to their work accounts. It can be integrated natively on iOS, Android, ReactNative, and JavaScript and can be displayed on any part of your application. The information entered into Argyle Link by users is encrypted and Argyle securely handles the complexity of multi-factor authentication and access control, which provides a smooth user experience for your users.

Within the Argyle API, the companies or payroll platforms which hold a user's work account, are referred to as Link items.

Configuration

Argyle Link provides multiple configuration options and callbacks that will customize how this UI element will function within your application. The only argument that is mandatory when invoking Argyle Link is the pluginKey, which can be found in the Argyle Console. By default, anytime Argyle Link is initialized, it will be treated as a new session for a new user. To ensure your users retain their previous state in Argyle Link when it is re-initialized for them, your application must use the userToken parameter. To close Link programmatically, call the close method of the Link instance returned by Argyle.create.

pluginKey
string uuid
required

Your plugin key, which can be found in the API keys section of the Argyle Console.

apiHost
string
optional

The API host that Argyle Link should use. Defaults to production API.

userToken
string uuid
optional

By default, anytime Argyle Link is initialized, Argyle will treat this as a new session for a new user. To ensure your users retain their previous state in Argyle Link when it is re-initialized for them, your application must use the userToken parameter.

linkItems
array of strings
optional

Use this parameter to limit the number of Link items that your users can connect to. Provide an array of Link item IDs you want Argyle Link to display in the company selection screen. The order in which you list the IDs will define the order in which they are displayed in the UI.

Defaults to [], which shows all available Link items.

If you provide a single Link item ID, the company selection screen will be skipped and the user will be navigated directly to the Link item login screen.

dataPartners
array of strings
optional

Deprecated in favor of linkItems .

Use this parameter to limit the number of Link items that your users can connect to. Provide an array of Link item IDs you want Argyle Link to display in the company selection screen. The order in which you list the IDs will define the order in which they are displayed in the UI.

Defaults to [], which shows all available data partners.

If you provide a single Link item ID, the company selection screen will be skipped and the user will be navigated directly to the Link item login screen.

companyName
string
optional

Your company or app name to display in the UI of Argyle Link (e.g. "your account is now successfully connected to companyName").

The default value is your company name as entered in the Company Settings section of the Argyle Console.

showIntroScreen
bool
optional

Toggles the visibility of the intro screen.

The default value is false.

introTitle
string
optional

A value to override the default title of the intro screen.

The default title is: "Let's link the companies where you make money to [YourCompanyName]"

introSubtitle
string
optional

A value to override the default subtitle of the intro screen.

The default subtitle is: "Enhance your credibility and enable a customized experience by providing [YourCompanyName] with transparency into your work data."

showPlatformsToggle
bool
optional

Toggles the visibility of the platforms toggle.

The default value is true.

exitButtonTitle
string
optional

A value to override the default title of the exit button shown in the success screen.

addIncomeSourceLinkVisible
boolean
optional

Toggles the visibility of the "Add income source" button.

The default value is true.

addIncomeSourceLinkTitle
string
optional

A value to override the default title for the "Add income source" button.

addIncomeSourceExitButtonTitle
string
optional

A value to override the default title of the exit button in "Add income source" form.

payDistributionConfig
string
optional

Argyle Link will initiate a pay distribution change process if a pay distribution configuration is provided. Pay distribution configuration describes the desired outcome of that change. For more information on changing pay distributions, please refer to the Argyle Update guide.

payDistributionItemsOnly
bool
optional

Forces Link to show only Link items that support pay distribution. For more information on changing pay distributions, please refer to the Argyle Update guide.

If a payDistributionConfig is provided, then only the Link items that match the parameters in the config will be shown. For example, if the payDistributionConfig allows only amount allocations and a Link item supports percent allocations only, then that Link item will not be shown.

If no payDistributionConfig is provided then all Link items that have some pay distribution support (amount and/or percent) will be shown.

The default value is false.

onAddIncomeSourceLinkClicked
func
optional

An optional callback triggered after the "Don't see your company?" button is pressed. Link will close by default if this callback is defined and triggered on iOS, Android and ReactNative SDKs. You can use the close method of the Argyle instance to close the Link Javascript SDK.

The callback function will receive an object containing a search query that was entered by the user.

onAccountCreated
func
optional

A callback function invoked immediately after a user clicks connect and a new account is created. The callback will be invoked before authenticating the account with the Link item.

The function will be passed an object containing accountId, userId, and dataPartnerId.

onAccountConnected
func
optional

A callback function invoked every time a new account is successfully authenticated with a Link item, including any multi-factor authentication requests. If your linkItems list contains only one data partner, it is safe to close Argyle Link at this point.

The function will be passed an object containing accountId, userId, and dataPartnerId.

onAccountUpdated
func
optional

A callback function invoked when a user updates their account credentials.

The function will be passed an object containing accountId, userId, and dataPartnerId.

onAccountRemoved
func
optional

A callback function invoked when a user removes an account.

The function will be passed an object containing accountId, userId, and dataPartnerId.

onUserCreated
func
optional

A callback function invoked when a new user is created. The function will be passed an object containing userId and userToken. The user object is created on the first attempt of a new user to connect an account.

onAccountError
func
optional

A callback function invoked every time an account fails to authenticate with a Link item.

The function will be passed an object containing accountId, userId, and dataPartnerId.

onClose
func
optional

A callback function invoked immediately after the user closes Link.

onTokenExpired
func
optional

A callback function invoked when the userToken expires.

The function will be passed another function as a parameter, which you should call with your new userToken as an argument.

Instead of using this callback, we advise checking the validity of the current token before initialising Link and generating a new one if needed.

closeOnOutsideClick
bool
optional

Toggles the closing of Link when a user clicks outside the bounds of the UI element provided by Argyle. This flag works only on the web implementation of Argyle Link (and not on the mobile SDKs).

The default value is true.

showCloseButton
bool
optional

Toggles the visibility of the close button. This flag works only on the web implementation of Argyle Link (and not on the mobile SDKs).

The default value is true.

A configuration example is displayed below. Feel free to copy-paste it into an html file, replace your_plugin_key with your own plugin_key (found in the API keys section of the Argyle Console), and give it a try.

Advanced configuration tips

Omitting the search screen

In the Link configuration, if you provide a single linkItems ID, the company selection screen will be skipped and the user will be navigated directly to the data partner login screen.

User tokens

User tokens are temporary access keys that let you start Argyle Link for an existing user. They are JWT tokens that contain an expiry date you can use to determine if you need to create a new user token. Newly issued tokens expire in 30 days. You can always decode the token to find out the exact expiration date (check exp field).

You can create user tokens using the /user-tokens endpoint.

Make sure that you request user tokens on your server-side and your client_id and client_secret are never exposed on the front-end.

Callbacks

Whenever a new account is created, the onAccountCreated callback is invoked with the accountId and userId parameters. You should store those IDs on your database and use them to retrieve the user's employment data from the Argyle API.

The onAccountUpdated callback is invoked when a user updates their credentials for an existing account.

When Argyle Link is initialized for a new user (i.e. userToken was not specified), a new user is created just before the user tries to connect their first account. This is when the onUserCreated callback is invoked with an object containing a userId and a userToken.

You should save the user ID on your database to be able to reference the user's accounts and request their user tokens from the API.

Android integration

Android Link SDK provides a way to integrate Argyle Link into your Android app.

The SDK supports API level 21 and above (distribution stats).

Note: We recommend you lock your app to portrait orientation.

When using tools like Proguard to obfuscate your code, make sure to exclude Android Link SDK package (com.argyle.*) from the process, it may cause unexpected runtime issues otherwise.

Our configuration is currently set to the following:

  • minSdkVersion = 21
  • compileSdkVersion = 28
  • targetSdkVersion = 28
  • Android Support Library = 28.0.0
  • Kotlin = 1.3+

1. Adding the SDK dependency

2. Creating the SDK configuration

3. Starting the flow

iOS integration

Argyle iOS SDK provides a way to integrate Argyle Link into your iOS app. Requirements:

  • iOS 11.0+
  • Xcode 11.6+
  • Swift 5+

Note: We recommend you to lock your app to portrait orientation.

1. Adding the SDK dependency

CocoaPods

CocoaPods is a dependency manager for Cocoa projects. For usage and installation instructions, visit their website. To integrate Argyle into your Xcode project using CocoaPods, specify it in your Podfile:

pod 'Argyle'

Use pod install and pod update commands to install/update pods afterward.

Carthage

Carthage is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks. To integrate Argyle into your Xcode project using Carthage, specify it in your Cartfile:

github "argyle-systems/argyle-plugin-ios" == 1.x.x

2. Configuring and starting the flow

React Native integration

React Native SDK provides a way to integrate Argyle Link into your React Native app.

Requirements for iOS:

  • The minimum deployment target needs to be at least 11.0
  • Required react-native version 0.60.x+

1. Adding the SDK dependency

$ npm install @argyleio/argyle-plugin-react-native --save or $ yarn add @argyleio/argyle-plugin-react-native

Update the Argyle pod with:

$ cd ios

$ pod install

$ pod update

in case not the most recent version of Argyle pod was installed.

2. Configuring and starting the flow