@getsensibill/web-sdk

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:

1. Navigate to the Sarabun font page
2. For the name, use the font name: Sarabun
3. To find the link, look for the <link> section in the right-hand panel and copy the value of the href. It should start with https://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.