Implement the Bridge Module
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();
Updated 14 days ago