@twilltac/compliance-sdk

SDK for embedding the Twilltac Compliance Plugin into your application. The plugin provides compliance functionality within an iframe, with secure communication between your host application and the plugin.

Installation

npm install @twilltac/compliance-sdk

Quick Start

import { createCompliancePlugin } from '@twilltac/compliance-sdk';

const container = document.getElementById('compliance-container');

const plugin = await createCompliancePlugin({
    containerElement: container,
    data: {
        workspace: 'YOUR_WORKSPACE_KEY',
        customerReference: 'YOUR_CUSTOMER_REFERENCE',
        authToken: 'YOUR_AUTH_TOKEN'
    }
}).catch((error) => {
    console.error('The plugin failed to load', error);
});

API Reference

createCompliancePlugin(options)

Creates and initialises the compliance plugin within a container element.

Parameters:

| Name | Type | Description | | -------------------------------- | ------------- | ------------------------------------------------- | | options.containerElement | HTMLElement | The DOM element where the plugin will be rendered | | options.data.workspace | string | Your Twilltac workspace identifier | | options.data.customerReference | string | Reference identifier for the customer | | options.data.authToken | string | Authentication token for the plugin session |

Returns: Promise<CompliancePlugin>

The promise resolves when the plugin has successfully initialised. If initialisation fails, the promise rejects with error details.

Events

You can subscribe to events via the plugin instance returned after successful initialisation.

plugin.on(event, handler)

Example:

const plugin = await createCompliancePlugin({ ... });

plugin.on('session:expired', () => {
    // Handle session expiry - e.g. refresh token and reinitialise
});

Available events:

| Event | Data | Description | | ----- | ---- | ----------- | | session:expired | void | Emits when the session has expired. This would typically trigger your auth flow followed by re-initialising the plugin. | | started | void | Emits when the user starts the journey and IDD document is generated. | | section:started | SectionStartedEvent | Emits when the user starts a section. | | section:completed | SectionEndedEvent | Emits when the user starts a completes the question set and selects their recommendations. |

Type Definitions

interface SectionStartedEvent {
    readonly name: string;
    readonly reference: string;
}

interface SectionEndedEvent {
    readonly name: string;
    readonly reference: string;
    readonly recommendations: {
        readonly externalReference: string;
        readonly price: number | null;
        readonly regulated: boolean;
        readonly title: string;
        readonly description: string;
    }[];
}

Framework Examples

Angular + RxJS

import { Component, ElementRef, input, viewChild } from '@angular/core';
import { takeUntilDestroyed, toObservable } from '@angular/core/rxjs-interop';
import { createCompliancePlugin, CompliancePlugin } from '@twilltac/compliance-sdk';
import { from, switchMap } from 'rxjs';

@Component({
    selector: 'app-compliance',
    template: `<div #container style="width: 100%; height: 600px;"></div>`
})
export class ComplianceComponent {
    readonly workspace = input.required<string>();
    readonly customerReference = input.required<string>();
    readonly authToken = input.required<string>();

    private readonly _container = viewChild.required<ElementRef<HTMLDivElement>>('container');

    private _plugin: CompliancePlugin | null = null;

    constructor() {
        toObservable(this._container)
            .pipe(
                switchMap((container) =>
                    from(
                        createCompliancePlugin({
                            containerElement: container.nativeElement,
                            data: {
                                workspace: this.workspace(),
                                customerReference: this.customerReference(),
                                authToken: this.authToken()
                            }
                        })
                    )
                ),
                takeUntilDestroyed()
            )
            .subscribe({
                next: (plugin) => {
                    this._plugin = plugin;
                },
                error: (error) => {
                    console.error('Failed to initialise compliance plugin:', error);
                }
            });
    }
}

Angular + Promises

import { Component, ElementRef, afterNextRender, input, viewChild } from '@angular/core';
import { createCompliancePlugin, CompliancePlugin } from '@twilltac/compliance-sdk';

@Component({
    selector: 'app-compliance',
    template: `<div #container style="width: 100%; height: 600px;"></div>`
})
export class ComplianceComponent {
    readonly workspace = input.required<string>();
    readonly customerReference = input.required<string>();
    readonly authToken = input.required<string>();

    private readonly _container = viewChild.required<ElementRef<HTMLDivElement>>('container');

    private _plugin: CompliancePlugin | null = null;

    constructor() {
        afterNextRender(() => {
            void this._initialisePlugin();
        });
    }

    private async _initialisePlugin(): Promise<void> {
        try {
            this._plugin = await createCompliancePlugin({
                containerElement: this._container().nativeElement,
                data: {
                    workspace: this.workspace(),
                    customerReference: this.customerReference(),
                    authToken: this.authToken()
                }
            });
        } catch (error) {
            console.error('Failed to initialise compliance plugin:', error);
        }
    }
}

React

import { useEffect, useRef } from 'react';
import { createCompliancePlugin, CompliancePlugin } from '@twilltac/compliance-sdk';

interface ComplianceWidgetProps {
    workspace: string;
    customerReference: string;
    authToken: string;
}

function ComplianceWidget({ workspace, customerReference, authToken }: ComplianceWidgetProps) {
    const containerRef = useRef<HTMLDivElement>(null);
    const pluginRef = useRef<CompliancePlugin | null>(null);

    useEffect(() => {
        if (!containerRef.current) return;

        createCompliancePlugin({
            containerElement: containerRef.current,
            data: { workspace, customerReference, authToken }
        })
            .then((plugin) => {
                pluginRef.current = plugin;
            })
            .catch(console.error);
    }, [workspace, customerReference, authToken]);

    return <div ref={containerRef} style={{ width: '100%', height: '600px' }} />;
}

Browser Support

The SDK requires a modern browser with support for:

• ES2020+

Support

For integration support, contact your Twilltac account representative.