stub
  • Introduction
  • API basics
  • Setting up API access
  • API Documentation
    • Authentication Tokens
    • Push data
    • Pull data
  • SDK Documentation
    • Embedded accounting
    • Custom Styling
    • Reference
Powered by GitBook
On this page
  • JavaScript SDK
  • Get started
  • 1. Add the base CSS stylesheet
  • 2. Add the JavaScript SDK
  • 3. Add a <div> for each widget
  • 4. Get an authentication token
  • 5. Initialise the SDK
  • Date range
  • Authentication
  1. SDK Documentation

Embedded accounting

Use our JavaScript SDK to embed stub into your own web application

PreviousPull dataNextCustom Styling

Last updated 2 months ago

JavaScript SDK

  1. Show dashboard widgets for cashflow, income, expenses, or profit, of a stub business.

  1. Initiate linking of bank accounts for a stub business. Once bank accounts are linked users can sync their bank transactions and categorise their transactions using the dashboard widgets in 1.

  2. Access basic information about a stub business. This can be useful for functionality in your product. For example, you can show a call to action to link bank accounts to users of a business with no linked bank accounts.

Get started

1. Add the base CSS stylesheet

Add the following code just before the end of the <head> tag of your web page.

For the latest SDK use:

<link href="https://cdn.stub.africa/stub-widgets/latest/stub-widgets.css" rel="stylesheet" />

You can also use specify the latest version, so that you don't receive any breaking changes:

<link href="https://cdn.stub.africa/stub-widgets/v1.456/stub-widgets.css" rel="stylesheet" />

This will include the base layout styles for the stub widgets. It ensures that they render correctly when the JavaScript SDK adds them to the DOM.

2. Add the JavaScript SDK

Add the following code just before the end of the <body> tag of your web page.

For the latest version use:

<script type="text/javascript" src="https://cdn.stub.africa/stub-widgets/latest/stub-widgets.js"></script>

You can also use specify the latest version, so that you don't receive any breaking changes:

<script type="text/javascript" src="https://cdn.stub.africa/stub-widgets/v1.456/stub-widgets.js"></script>

This will load the stub SDK, and attach it to the window, so that you can reference and initialise it from anywhere (in step 4).

3. Add a <div> for each widget

Add a <div> element to your DOM for each widget that you want to present to your users. Each <div> must have an ID corresponding to the respective widget that you want it to render. 

<div id="stub-cashflow"></div>
<div id="stub-income"></div>
<div id="stub-expenses"></div>
<div id="stub-profit"></div>
<div id="stub-modal"></div>

These elements will display as block elements wherever you put them in your DOM. In this way you can position and size them as you like.

4. Get an authentication token

To make requests via the widget you will need to request an authentication token through your backend and then pass it to the widget.

5. Initialise the SDK

Once the SDK has loaded, you can initialise the stub widgets from anywhere in your application using the following:

// Get a reference to the SDK
const stub = window.stub

// Initialise the SDK
const options = {
    appId: '<your app ID>',
    businessId: '<stub business ID>',
    token: '<authentication token>',
    renderImmediately: true,
}

stub.init(options)

These are the required props to initialise stub. If you do not include them you will see an error in the console.

If renderImmediately is false or omitted then you will need to call stub.render() when you are ready to render the widgets.

You may want to use the stub test environment while you're setting things up, or to integrate with your different environments.

window.stub.init({
    ...
    test: true
})

The SDK will default to showing data for the current month, but you can initialise it with a different month and year if you would like to specify that: 

window.stub.init({
    ...
    month: 3,
    year: 2023
})

Date range

stub shows data on the widgets for a specified month and year. It caches much of this data, so updating this is low cost and the widget will render it right away.

You can specify the date range at any point in your application lifecycle using the set() function. 

// Call the set() function with the options you would like to update
window.stub.set({
    month: 1, // Must be a number from 0 - 11 (Jan - Dec)
    year: 1999 // Must be a number from 1971 - 2099
})

Authentication

stub uses the token that you provide it with to authenticate API calls. That means that if the token expires, an API call may fail and your user will see an error message.

To ensure that the stub SDK always has the most up-to-date token, use the set() function to specify a new one whenever it expires and changes. 

window.stub.set({
    token: '<new token>'
})

It's up to you to ensure that the widgets are only presented to authenticated users. Generally, you should only initialise the stub SDK once your user has been authenticated.

that shows a vanilla implementation of the JavaScript SDK. You need to add your App ID, Business ID, and Token to the index.html file.

Learn how to generate authentication tokens here:

For a full list of initialisation options see the

Here's a demo project
Authentication Tokens
documentation below.