@getsensibill/web-sdk
v0.8.8
Published
This guide serves as a quickstart and general overview of how to integrate with the Sensibill Web SDK.
Downloads
55
Maintainers
Keywords
Readme
Sensibill Web SDK Integrator Guide
This guide serves as a quickstart and general overview of how to integrate with the Sensibill Web SDK.
# Using npm
npm i @getsensibill/web-sdk
# Using yarn
yarn add @getsensibill/web-sdk
Import where you need it
import { SensibillSDK } from '@getsensibill/web-sdk';
Initialization
An initialization object which will be used to build the iframe url. The object should include the following properties:
| Name | Required? | type | Use |
| ------------- | --------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| id
| false
| string
| Every instance requires a unique ID. If you'd like, you can provide the ID yourself. |
| clientID
| true
| string
| Your unique client ID. |
| environment
| true
| string
| One of 'fastlane' 'staging' 'sandbox' 'production'. |
| locale
| false
| string
| The locale you would like to load the UI in. You can change this later. |
| source
| false
| string
| The source platform loading the web-ui app. Defaults to web-sdk. One of 'web-sdk' 'mobile-sdk' 'tecton-web-sdk' 'tecton-mobile-sdk'. |
| disableNav
| false
| boolean
| Disable the breadcrumb navigation bar when true. Defaults to false. |
Locale Breakdown
Available options:
- 'en', 'en_AU', 'en_CA', 'en_GB'
- 'es', 'es_ES', 'es_US'
- 'fr', 'fr_CA'
Notes on the non-country locales:
- 'en' locale is equal to 'en_US' and is the default locale if no match can be made based on the client’s locale.
- 'es' locale is equal to 'es_US'
- 'fr' locale is equal to 'fr_CA'
Opening a Sensibill iframe
Opening an iframe to Sensibill can be done with as little code as the following:
const instance = await SensibillSDK.create(
// Provide a reference to the element you want to contain the iframe
document.getElementById('your-element'),
// Provide an initialization object which contains your client id
{ clientID: 'your-client-id', environment: 'a-valid-environment-value' },
// Provide a configuration object which contains your access token at a minimum
{ authentication: { accessToken: 'a-valid-access-token' } },
);
While this will open and work fine, occasionally you may need to provide a new access token. You can provide one on demand with the following code:
function refreshAuthentication() {
// Do what you need to get your new token. This can be synchronous, or asynchronous. The iframe will wait.
const myNewToken = getNewToken();
// Once you have it, set the new token on the instance
instance.setToken(myNewToken);
}
// Run the refreshAuthentication function whenever the instance asks for a new token
instance.registerListener(refreshAuthentication, 'getNewToken');
Runtime Branding Configuration
You can inject your brand's font and colors when you initialize the Sensibill instance.
To configure all of the branding properties, include a brand
block when opening the Sensibill iframe:
const instance = await SensibillSDK.create(
// Provide a reference to the element you want to contain the iframe
document.getElementById('your-element'),
// Provide an initialization object which contains your client id
{ clientID: 'your-client-id', environment: 'a-valid-environment-value' },
// Provide a configuration object which contains your access token and branding overrides
{
brand: {
fonts: {
families: {
primary: {
name: 'Sarabun',
link: 'https://fonts.googleapis.com/css2?family=Sarabun&display=swap',
},
},
},
colors: {
primary: '#186DB3',
primaryVariant: '#21384D',
onPrimary: '#EEEEEE',
secondary: '#F8897F',
onSecondary: '#FEFEFE',
background: '#FBFBFB',
onBackground: '#4F5056',
surface: 'lightgray',
onSurface: '#000000',
surfaceVariant: '#E2F9FF',
onSurfaceFocus: '#0990D5',
error: '#FF0000',
onError: '#FFFFFF',
},
},
authentication: { accessToken: 'a-valid-access-token' },
},
);
Font
Under fonts
, supply a Google font name and link, taken from the value of the href in the font's page.
For example, to load Sarabun
:
- Navigate to the Sarabun font page
- For the name, use the font name:
Sarabun
- To find the link, look for the
<link>
section in the right-hand panel and copy the value of thehref
. It should start withhttps://fonts.googleapis.com
The app currently uses just one font.
getLinkedTransactions
Function to get transactions that match the external account transaction id's provided as input
SensibillSDK.getLinkedTransactions(
// array of external transaction id's
['123', '456'],
// Provide a valid environment value - default is beta-prod
'a-valid-environment-value',
// Provide your access token
'a-valid-access-token',
);
//output example
{
"123": {
"id": "abc999",
"date": "2021-08-12",
"merchant": "Test",
"total": 15
},
// no match found returns null for id value
"456": null
}
getMatchingTransactions
Function to get transactions that potentially match given input
interface ExternalAccountTransaction {
id: string;
amount: number;
currencyCode: string;
date?: string;
postedDate?: string;
}
// one of date or postedDate must be included
SensibillSDK.getMatchingTransactions(
// array of external ExternalAccountTransaction
[
{
id: 'acb999',
amount: 15,
currencyCode: 'CAD',
date: '2021-09-08',
},
{
id: 'xyz999',
amount: 10,
currencyCode: 'CAD',
date: '2021-09-08',
}
],
// Provide a valid environment value - default is beta-prod
'a-valid-environment-value',
// Provide your access token
'a-valid-access-token',
);
//output example
{
"abc999": {
"id": "abc999",
"date": "2021-08-12",
"merchant": "Test",
"total": 15
},
// no match found returns null for id value
"xyz999": null
}
// if multiple matches are found, the value will be an array of objects
SDK Errors
The Sensibill Web SDK has custom error types to help clients integrate with the SDK.
The goal of these errors is to catch SDK errors and provide developer documentation to help clients integrate with the SDK. These errors are not meant to help users on the clients sites.
Missing Client Error
WEB_SDK_ERROR_MISSING_CLIENT
This error is a critical error that would occur if the client is attempting to initialize an instance without providing their client ID.
This should just help catch a sloppy integration and avoid back and forth with Sensibill.
Missing Target Error
WEB_SDK_ERROR_MISSING_TARGET
Clients must provide an HTML element to mount the iframe in. If they do not, they are presented with this error.
This should help diagnose errors where a client is integrating the SPA dynamically.
Target in use Error
WEB_SDK_ERROR_TARGET_IN_USE
When an iframe is initialized it is placed in the provided target element. It becomes the sole child in that element.
This is an intentional decision to prevent errors from iframes sharing targets.
This error is provided to help inform clients who may be attempting to reuse a target. It may also help discover instances where the same instance is being initialized multiple times.