Deep linking

Connect users to a specific Link item through Deep linking.

With a deep link user flow, you can choose to present your users with a single Link item and omit certain screens from the usual Link flow.

Users are only presented with the ability to log in, reconnect, or disconnect the specific Link item that you have preselected.

Deep linking is a great solution if you want to build your own menus, search experience, or controls around connected accounts.

Starbox deep link coverStarbox deep link cover

🚧

Before implementing Deep link, you must set up user tokens first. A new user ID is created when a user tries to log in to Link for the first time. Keep the Argyle user ID mapped to your User ID to avoid creating duplicate users. Duplicate accounts can inflate usage, billing, and analytics data. Read Returning user experience before implementing Deep link.

Create a deep link map

You can create a deep link map in one of two ways:

Configure deep link in Console

If you only need to deep link a select number of users, or many of your users would be directed to the same Link item, configuring this feature on Console is the right option for you. You must create a unique customization for each Link item you wish to link to in the Link Customizer tool.

📘

If you need to set up deep linking for a large number of Link items, Argyle recommends using the programmatic approach.

Follow these steps to configure deep linking for each Link item you need:

  1. Log in to Console and open the Link Customizer.
  2. Create a new customization or select an existing customization to edit.
  3. Go to the Deep link settings under Set available Link items and select Link item login.
  4. Find and select the Link item to deep link users to.
  5. Save the customization ID and insert the ID in your Link configuration.

This is what the Deep link configuration screen looks like:

Deep link customizerDeep link customizer

To direct your users to log in to a deep linked Link item, send them an invite specifying the correct customization ID from Console:

Send invite via Customizer with deep linkSend invite via Customizer with deep link

Configure deep link programmatically

If you need to configure deep linking to multiple different Link items, Argyle recommends following the programmatic approach.

Initialize Link with a Link item id in the linkItems parameter:

<!DOCTYPE html>
<html>

<head>
    <meta charset="utf-8" />
</head>

<body>
    <script src="https://plugin.argyle.com/argyle.web.v3.js"></script>
    <script type="text/javascript">
        const argyle = Argyle.create({
        linkKey: 'YOUR_LINK_KEY', // insert your Link key here. It can be found in the Argyle Console.
        apiHost: 'https://api-sandbox.argyle.com/v1', // sandbox environment is used in this example. Change to production environment before launching.
        linkItems: ['starbox'] // insert Link item ID here
      })
      argyle.open()
    </script>
</body>

</html>
_ = Argyle.shared
    .loginWith(
        linkKey: "YOUR_LINK_KEY", // insert your link key here. It can be found in the Argyle Console.
        apiHost: "https://api-sandbox.argyle.com/v1") // sandbox environment is used in this example. Change to production environment before launching.
    .linkItems(["starbox"]) // insert Link item ID here
    .resultListener(self)

let argyle = Argyle.shared.controller
argyle.modalPresentationStyle = .fullScreen
self.present(argyle, animated: true, completion: nil)
val config = ArgyleConfig.Builder()
    .loginWith(
        "YOUR_LINK_KEY", // insert your Link key here. It can be found in the Argyle Console.
        "https://api-sandbox.argyle.com/v1", // sandbox environment is used in this example. Change to production environment before launching. 
        "")
    .linkItems(arrayOf("starbox")) // insert Link item ID here
    .setCallbackListener(object : Argyle.ArgyleResultListener {
        // callbacks
    })
    .build()

Argyle.instance.init(config)
Argyle.instance.startSDK(this)
import ArgyleSdk from '@argyleio/argyle-plugin-react-native'

ArgyleSdk.loginWith(
    "YOUR_LINK_KEY", // insert your Link key here. It can be found in the Argyle Console.
    "https://api-sandbox.argyle.com/v1", // sandbox environment is used in this example. Change to production environment before launching. 
    "")
ArgyleSdk.linkItems(["starbox"]) // insert Link item ID here
ArgyleSdk.start()

linkItems array of strings optional

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

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


Deep linking new users to log in

You can deep link new users to the Login screen and omit the Intro and Search screens in a few scenarios:

  • You know the exact Link item the user wants to connect. This could mean that you have already determined the user’s employer in your software, so you can send them to the respective Link item directly as described in VOIE Scoping.
  • You can choose to support only a limited number of Link items, presenting a specific list of companies in your software to guide your user directly to the Login screen for one of those companies.

For first-time users who want to connect a payroll account, invoke Argyle Link with your customization ID. This generates a Login screen for that user’s employer or payroll provider.

As the user progresses through the account connection flow, any webhooks you have configured keep you informed on their progress. When a user connects their payroll account successfully, they see a success screen and a button that you can use to exit and direct them to additional flows as needed.

Deep link to log inDeep link to log in

If the user is unable to connect their employer or payroll account as expected, you can allow them to exit back to the main application. There you can direct them to a secondary option to verify their income with the document upload flow.

Starbox deep link coverStarbox deep link cover

Deep linking returning users

For returning users, in addition to providing a Link item ID in linkItems, you also need to provide the userToken associated with that user.

See these Link initialization examples to understand how to provide the userToken:

<!DOCTYPE html>
<html>

<head>
    <meta charset="utf-8" />
</head>

<body>
    <script src="https://plugin.argyle.com/argyle.web.v3.js"></script>
    <script type="text/javascript">
        const argyle = Argyle.create({
        linkKey: 'YOUR_LINK_KEY', // insert your Link key here. It can be found in the Argyle Console.
        apiHost: 'https://api-sandbox.argyle.com/v1', // sandbox environment is used in this example. Change to production environment before launching.
        linkItems: ['starbox'], // insert Link item ID here
        userToken: 'USER_TOKEN' // insert the user token here
      argyle.open()
    </script>
</body>

</html>
_ = Argyle.shared
    .loginWith(
        linkKey: "YOUR_LINK_KEY",  // insert your Link key here. It can be found in the Argyle Console.
        apiHost: "https://api-sandbox.argyle.com/v1") // sandbox environment is used in this example. Change to production environment before launching.
    .linkItems(["starbox"]) // insert Link item ID here
    .resultListener(self)

let argyle = Argyle.shared.updateToken("USER_TOKEN").controller // insert the old or new user token here
argyle.modalPresentationStyle = .fullScreen
self.present(argyle, animated: true, completion: nil)
val config = ArgyleConfig.Builder()
    .loginWith(
        "YOUR_LINK_KEY", // insert your Link key here. It can be found in the Argyle Console.
        "https://api-sandbox.argyle.com/v1", // sandbox environment is used in this example. Change to production environment before launching.
        "USER_TOKEN") // insert the old or new user token here
    .linkItems(arrayOf("starbox")) // insert Link item ID here
    .setCallbackListener(object : Argyle.ArgyleResultListener {
        // callbacks
    })
    .build()

Argyle.instance.init(config)
Argyle.instance.startSDK(this)
import ArgyleSdk from '@argyleio/argyle-plugin-react-native'

ArgyleSdk.loginWith(
    "YOUR_LINK_KEY", // insert your Link key here. It can be found in the Argyle Console.
    "https://api-sandbox.argyle.com/v1", // sandbox environment is used in this example. Change to production environment before launching.
    "USER_TOKEN") // insert the old or new user token here
ArgyleSdk.linkItems(["starbox"]) // insert Link item ID here
ArgyleSdk.start()

Updating a pay allocation

You may also want to deep link users to switch their direct deposit, allowing them to configure their direct deposit from within your application.

To set up deep linking to direct deposit:

  1. Query the /link-items endpoint to confirm if the Link item supports direct deposit switching. If features.pay_distribution_update.supported is true, the Link item can be used in this flow. Also check if the Link item supports percent or amount allocations.
  2. Initialize Argyle Link for DDS to that Link item.
  3. If you have implemented user tokens and the user has connected an account already, you can send the user directly to the Direct deposit opened screen using the payDistributionAutoTrigger Link configuration parameter.

Deep link update pay allocationDeep link update pay allocation

Uploading documents

You can choose to deep link your users directly to an option that enables them to upload W-2s, 1099s, and paystubs. See our document upload guide for more information.

Deep linking from a menu in your application

You can deep link users to Link items directly from a menu in your application. This solution is ideal if you are targeting a specific set of Link items, but want your users to be able to choose among them. Deep link each menu selection to a Link item for an integrated and seamless user experience.

Deep link from a menu in your applicationDeep link from a menu in your application

Link each menu item to the corresponding customization ID or Argyle Link item ID to deep link to a specific Link item. When the user selects that menu item, they can log in to the Link item.

Customize your menu to show when accounts are connected or errors occur. You can query the /accounts endpoint to check the connection.status to show this information in your application:

Deep link account connection statusDeep link account connection status

Learn more about account connection status in the API reference.

Deep linking from a notification

If you need your user to re-authenticate so that you can regain access to their data, you can send them push notifications in your application, an email, or a text message to redirect them to connect.

Specify the linkItems and the userToken to enable the user to resume their session:

Deep link from a notificationDeep link from a notification

Revoking access

You will want to implement a flow for disconnecting and removing accounts that suits your business needs and compliance standards. You can do this at the account level. See our data structure References page to learn more about how Argyle structures data.

From your application, the user should be able to select an option to remove a single or multiple accounts. Once they have selected this option, your software can deep link them to a Link screen where they can confirm they would like to remove their data:

Deep link revoking accessDeep link revoking access

Allow users to find a different employer when deep linking

You can enable your users to find a different employer even when you're deep linking them to a specific employer. Use Link Customizer in the Console to toggle the display of the Find more employers button for the Login screen.

Allow users to find a different employers while deep linkingAllow users to find a different employers while deep linking

Learn more

Consult these resources to learn more about Argyle’s features:


What’s Next