@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: {
        workspaceReference: 'YOUR_WORKSPACE_REFERENCE',
        flow: 'journey',
        customerReference: 'YOUR_CUSTOMER_REFERENCE',
        offerReference: 'YOUR_OFFER_REFERENCE',
        authToken: 'YOUR_AUTH_TOKEN',
        sizing: 'content'
    }
}).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 | Required | Description | | --------------------------------- | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------- | | options.containerElement | HTMLElement | Yes | The DOM element where the plugin will be rendered | | options.data.customerReference | string | Yes | Reference identifier for the customer | | options.data.offerReference | string | Yes | Reference identifier for the compliance customer offer | | options.data.workspaceReference | string | One of | Your Twilltac workspace reference. One of workspaceReference or workspaceSubdomain must be provided | | options.data.workspaceSubdomain | string | One of | Your Twilltac workspace subdomain. One of workspaceReference or workspaceSubdomain must be provided | | options.data.authToken | string | Yes | Authentication token for the plugin session | | options.data.flow | string | Yes | The plugin flow to load. One of journey or handover | | options.data.sizing | string | No | 'content' (default) — plugin element grows to fit content. 'container' — plugin fills its container height |

Returns: Promise<CompliancePlugin>

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

plugin.destroy()

Cleans up all event listeners and internal resources held by the plugin instance. Call this before re-initialising the plugin to prevent listeners from accumulating across multiple initialisations.

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

// Later, when re-initialising or unmounting:
plugin.destroy();

Events

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

plugin.on(event, handler)

Subscribe to a specific event.

plugin.on(handler)

Subscribe to all events. The handler receives the event name as the first argument and the event data as the second.

plugin.on((event, data) => {
    console.log(`Event: ${event}`, data);
});

Example:

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

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

Available events:

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

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 '@anlar/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 workspaceReference = input.required<string>();
    readonly flow = input.required<string>();
    readonly customerReference = input.required<string>();
    readonly offerReference = input.required<string>();
    readonly authToken = input.required<string>();
    readonly sizing = input<'content' | 'container'>('content');

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

    private _plugin: CompliancePlugin | null = null;

    constructor() {
        toObservable(this._container)
            .pipe(
                switchMap((container) => {
                    this._plugin?.destroy();
                    this._plugin = null;

                    return from(
                        createCompliancePlugin({
                            containerElement: container.nativeElement,
                            data: {
                                workspaceReference: this.workspaceReference(),
                                flow: this.flow(),
                                customerReference: this.customerReference(),
                                offerReference: this.offerReference(),
                                authToken: this.authToken(),
                                sizing: this.sizing()
                            }
                        })
                    );
                }),
                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 workspaceReference = input.required<string>();
    readonly flow = input.required<string>();
    readonly customerReference = input.required<string>();
    readonly offerReference = input.required<string>();
    readonly authToken = input.required<string>();
    readonly sizing = input<'content' | 'container'>('content');

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

    private _plugin: CompliancePlugin | null = null;

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

    private async _initialisePlugin(): Promise<void> {
        this._plugin?.destroy();
        this._plugin = null;

        try {
            this._plugin = await createCompliancePlugin({
                containerElement: this._container().nativeElement,
                data: {
                    workspaceReference: this.workspaceReference(),
                    flow: this.flow(),
                    customerReference: this.customerReference(),
                    offerReference: this.offerReference(),
                    authToken: this.authToken(),
                    sizing: this.sizing()
                }
            });
        } 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 {
    workspaceReference: string;
    flow: 'journey' | 'handover';
    customerReference: string;
    offerReference: string;
    authToken: string;
    sizing?: 'content' | 'container';
}

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

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

        pluginRef.current?.destroy();
        pluginRef.current = null;

        createCompliancePlugin({
            containerElement: containerRef.current,
            data: { workspaceReference, flow, customerReference, offerReference, authToken, sizing }
        })
            .then((plugin) => {
                pluginRef.current = plugin;
            })
            .catch(console.error);

        return () => {
            pluginRef.current?.destroy();
            pluginRef.current = null;
        };
    }, [workspaceReference, flow, customerReference, offerReference, 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.