Argyle Link

Learn how to integrate Argyle into your Web, iOS, Android, or React Native application.

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, React Native, and JavaScript. You can display Argyle Link in any part of your application.

The information that users enter in Argyle Link is encrypted. Argyle securely handles the complexity of multi-factor authentication and access control, providing a smooth 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

You can customize Argyle Link with configuration options and callbacks. This allows you to tailor how Link works within your application. There is only one mandatory argument for invoking Argyle Link—the linkKey. You can find your linkKey in the Argyle Console.

By default, anytime Argyle Link is initialized, it opens as a new session for a new user. To ensure users retain their previous state in Argyle Link, you must use the userToken parameter in your application.

A configuration example is displayed below. Copy and paste the example configuration into an html file, replace YOUR_LINK_KEY with your own linkKey (found in the API keys section of the Argyle Console), and give it a try.

See the full list of all configuration parameters at the bottom of this page.

Closing Link programmatically

Normally Link is closed by the user, but it can also be closed by calling the close method of the Link instance returned by Argyle.create

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.

You can find the full list of all available callbacks in the configuration parameters section under Callbacks.

Android integration

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

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

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

Important: 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. You can do this by adding this line to your proguard-rules.pro:-keep class com.argyle. { *; }

Our target configuration is currently set to the following:

  • minSdkVersion = 23
  • Kotlin = 1.4.32

1. Adding the SDK dependency

2. Creating the SDK configuration

3. Starting the flow

Closing Link programmatically

Normally, Link is closed by the user but it can also be closed by calling Argyle.instance.close()

iOS integration

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

  • iOS 12.0+
  • Xcode 13.0+
  • 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', '4.x.x'

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" == 4.x.x

2. Update Info.plist

To give users a seamless multi-factor authentication verification experience, Argyle Link SDK supports direct opening of an email client. For this to work you must define the list of supported clients for LSApplicationQueriesSchemes property in your Info.plist file.

3. Configuring and starting the flow

Closing Link programmatically

Normally, Link is closed by the user but it can also be closed by calling Argyle.shared.close()

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+

Requirements for Android:

Important: 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. You can do this by adding this line to your proguard-rules.pro:-keep class com.argyle. { *; }

In case of runtime issues related to okhttp3 library, note that Link SDK currently has a dependency of okhttp3:4.9.2 but in case some of your dependencies use an older version (okhttp3:3.x.x) they may need updating to a version that also uses okhttp3:4.x.x . Alternatively, you may try forcing the version of the dependency as follows:

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

Closing Link programmatically

Normally, Link is closed by the user but it can also be closed by calling ArgyleSdk.close()

Upgrade to the latest version of the Link SDK

The Argyle team regularly upgrades the Link SDKs with various benefits, including new features, bug fixes, and performance improvements. Refer to the Upgrade guide for detailed instructions for each SDK.

Configuration parameters

For visual examples of all customizable UI elements, refer to the Link customization guide.

General

linkKey
string uuid
required

Your Link 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.

UI Elements

You can customize Argyle Link using the Link Customizer tool or by editing Link config parameters programmatically. See Customizing Argyle Link to learn more about each of these options.

Pay Distribution

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 distribution, please refer to the Pay Distribution Guide.

payDistributionUpdateFlow
bool
optional

If payDistributionUpdateFlow is set to true and the payDistributionConfig parameter is provided, the pay distribution update flow will be initiated right after an account gets connected.

If this is set to true but the payDistributionConfig is not set, Link will not initialize properly.

Defaults to false.

payDistributionItemsOnly
bool
optional

When set to true, only Link items that support pay distribution will be shown. For more information on changing pay distribution, please refer to the Pay Distribution 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.

payDistributionAutoTrigger
bool

If set to true, the deep linked returning users are taken directly to the Pay distribution screen, if a pay distribution configuration is provided.

Default value is false.

Callbacks

onPayDistributionSuccess
func
optional

A callback function invoked after a successful pay distribution update flow.

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

onPayDistributionError
func
optional

A callback function invoked after an error occurs during the pay distribution update flow.

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

onCantFindLinkItemClicked
func
optional

An optional callback triggered after the Can't find your employer? button is clicked.

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.

If the callback is not defined, then the user will go through the forms Questionnaire flow described here.

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 linkItemId.

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 Link item, it is safe to close Argyle Link at this point.

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

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 linkItemId.

onAccountRemoved
func
optional

A callback function invoked when a user removes an account.

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

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.

onError
func
optional

A callback function invoked when Link encounters an internal problem that breaks the flow for the user.

The function will be passed the type of the error that occurred.

Possible values: INVALID_LINK_ITEMS, INVALID_PD_CONFIG, INVALID_LINK_KEY, INVALID_USER_TOKEN, GENERIC

For more details and troubleshooting, see Link Errors.

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 linkItemId.

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 initializing Link and generating a new one if needed.

onUIEvent
func
optional

The onUIEvent is invoked when specific UI events are activated on Link. These events are passed with a data object containing linkItem, accountId, userID, and deepLink.

Also, some events have specific properties. Please, refer to Link Analytics to know all the event-specific properties and the screen where they are activated.

onExitIntroClicked
conditionally required
func

This callback is associated to the secondary button on the Intro screen. Upon receiving this event, you can initiate a backup flow for your users.