Truv Bridge is a drop-in module that your users will use to connect their accounts to Truv and allow you to access their data via Truv's API. The bridge will handle employer search, credentials, multi-factor authentication, and error handling.

We recommend starting with Quickstart to understand how Truv Bridge can be implemented in your code.

Bridge flow

Below you can see an overview of tokens and data exchange between your application, Truv Bridge, your backend and Truv API.

1. Request a bridge_token token from your backend
2. On your backend server request bridge token from the Truv's API
3. Initialize Truv Bridge in your application by passing the bridge_token to TruvBridge.init
4. A user starts connecting their account and a public_token is generated. Bridge hands off the public_token client-side via the onSuccess/onEvent callback.
5. Webhook events start to be delivered once connection status changes.
6. Exchange a temporary public_token for a permanent access_token.
7. Make an API request to Truv to get the data.

Integrating Bridge

Once you get the API keys and learn the basics of the Truv API, it's time to integrate with Bridge , which will handle credential validation, multi-factor authentication, and error handling for each integration that we support. Integrating with Bridge involves 3 steps.

Use a script tag to load the bridge.js library from the Truv servers (example below).
Make a call to a backend API endpoint to retrieve a bridge_token from Truv's backend.
Initialize Bridge with TruvBridge.init, passing the bridge_token received as a parameter.

Bridge SDK

Truv Bridge can be embedded in mobile or web apps using one of our SDKs. Alternatively use pure Javascript code:

<html>
<head>
    <!-- Step 1 - add the Bridge library to your app with a script tag -->
    <script src="https://cdn.truv.com/bridge.js"></script>
</head>
<body>
<script>
  // Step 2 - Call your back end to retrieve a bridge_token from truv
  const bridgeToken = <%= Value returned by API call to acquire bridge_token %>

  // Step 3 - Initialize Bridge
  const bridge = TruvBridge.init({
        bridgeToken: bridgeToken.bridge_token,
        onLoad:function(){
          // Optional, called when Bridge loads
          console.log('Bridge loaded')
        },
        onSuccess:function(public_token, metadata){
          console.log('success handler')
          // Send the public_token to your server to exchange for an access_token
          // and retrieve payroll data.
          // The metadata object contains info about the Link.
          console.log("token: ", public_token)
          console.log("metadata: ", metadata)
        },
        onEvent: function(event_type, payload) {
          // all events fire this function. event_type indicates what the event is,
          // payload has additional information depending on the event.
          console.log('event: ', event_type)
          console.log('payload: ', payload)
        },
        onClose:function(){
          // Optional, called when Bridge is closed by the user.
          console.log('Bridge closed')
        }
    })
</script>
<!-- Normal page content -->
<!-- Step 4 - Create a button or action that calls bridge.open() to Bridge -->
<button type="button" id="button" onclick="bridge.open()">
  Connect
</button>
</body>
</html>

Authentication

Truv Bridge is only meant to be used in authorized environments, so to ensure it is indeed your application requesting to initialize Bridge we have you request a token from a secure setting (your back end) with your Client ID and Access key. By passing the resulting bridge_token into TruvBridge.init your application is the one trying to initialize, thereby creating a secure front end environment for your users.

Parameters

Property	Description	Required
bridgeToken	The bridge_token value returned by the Create Bridge Token API endpoint.	required

Callbacks

Callback	Description	Required
onLoad	A function that is called when Bridge has finished loading.	optional
onEvent	A function that is called when an event occurs with Bridge. See events.	optional
onSuccess	A function that is called when a user has successfully connected to a payroll provider and closed Bridge. The function should expect two arguments, the public_token and a metadata object.	required
onClose	A function that is called when Bridge closes.	optional

Closing Bridge

To close the Bridge programmatically (the default behavior is to wait for the user to close it) call close method of the Bridge instance returned by init function.

// call close method of the bridge instance
bridge.close();