Decide Widget SDK

The Decide Widget SDK allows you to easily integrate identity verification and spooling flows into your web application.

Installation

npm install @indicina1/decide-sdk

CDN / Script Tag

If you prefer not to use a package manager, you can include the SDK directly via a script tag. Using this method, the SDK as exposed as a global DecideWidget object.

<script src="https://uploads.indicina.co/public/decide/prod/spool/sdk/widget.min.js"></script>

<!-- Popup Mode -->
<script>
  const controller = DecideWidget.popup({
    widgetUrl: "https://your-decide-app.com/widgets/application/...",
    customerIdentifier: "customer-123",
  });

  controller.open();
</script>

<!-- Inline Mode -->
<div id="widget-container"></div>
<script>
  DecideWidget.renderInline({
    widgetUrl: "https://your-decide-app.com/widgets/application/...",
    containerId: "widget-container", // Must match the ID above
    customerIdentifier: "customer-123",
  });
</script>

Usage

Popup Mode

import { DecideWidget } from "@indicina1/decide-sdk";

const controller = DecideWidget.popup({
  widgetUrl: "https://your-decide-app.com/widgets/application/...",
  customerIdentifier: "customer-123",
  onLoad: () => {
    console.log("Widget loaded");
  },
  onMessage: (message) => {
    console.log("Message from widget:", message);
  },
  onClose: () => {
    console.log("Widget closed");
  },
  onError: (error) => {
    console.error("Widget error:", error);
  },
});

controller.open();

Inline Mode

import { DecideWidget } from "@indicina1/decide-sdk";

DecideWidget.renderInline({
  widgetUrl: "https://your-decide-app.com/widgets/application/...",
  containerId: "widget-container",
  customerIdentifier: "customer-123",
  onLoad: () => {
    console.log("Inline widget loaded");
  },
});

Configuration

The popup and renderInline methods accept a configuration object with the following properties:

| Property | Type | Required | Description | |----------|------|----------|-------------| | widgetUrl | string | Yes | The full URL of the Decide widget application you want to load. | | customerIdentifier | string | No | A unique identifier for the customer (e.g., email or UUID). Used to pre-fill or link sessions. | | containerId | string | Yes (Inline only) | The ID of the HTML element where the widget should be rendered. | | workflowConfiguration | object | No | Optional settings to override workflow behavior. See below. | | metadata | object | No | Additional JSON data to pass to the widget session. | | autoOpen | boolean | No | If true, the popup opens immediately upon initialization. Defaults to false. | | onLoad | () => void | No | Callback fired when the widget iframe finishes loading. | | onClose | () => void | No | Callback fired when the user closes the popup or gets a close event. | | onMessage | (data: any) => void | No | Callback for receiving custom messages/events from the widget. | | onError | (error: any) => void | No | Callback fired if the widget encounters an initialization error. |

Workflow Configuration

You can pass an optional workflowConfiguration object to customize specific behaviors:

workflowConfiguration: {
  revalidateNin: true,      // Force NIN revalidation
  revalidateBvn: false,     // Skip BVN revalidation
  mbsValidityPeriod: 30,    // Days MBS data remains valid
  bvnAccountValidity: 30,   // Days BVN account data remains valid
  theme: "outside"          // Theme preference ('inside' or 'outside')
}

Setup & Development

1. Building

Build the SDK and Demo application for specific environments:

• Local Build: npm run build
• Sandbox Build: npm run build:sandbox
• Production Build: npm run build:prod

The build output is isolated:

• dist/sdk/: SDK library files.
• dist/demo/: Standalone demo application.

2. Testing the Demo

To preview the demo application locally:

npm run start

This serves dist/demo at http://localhost:4173.

Local NPM Testing

Before publishing to the real NPM registry, you can test the package locally using these methods:

Method A: Using npm pack (Recommended)

1. Build the SDK:

   npm run build:sdk

2. Generate Tarball:

   npm pack

   This creates a file like decide-sdk-0.0.0.tgz in your root folder.
3. Install in another project:

   npm install /path/to/decide-sdk-0.0.0.tgz

Method B: Using npm link

1. Link the SDK:

   npm link

2. Use in another project:

   cd /path/to/your-app
   npm link @indicina1/decide-sdk

License

MIT