Coast Widget SDK
Embed Coast in your web application.
Getting Started
npm install @coastpay/embedded-widget-sdk
Load the SDK and initialize:
import { loadCoast } from '@coastpay/embedded-widget-sdk';
const coast = await loadCoast();
const widget = coast.initialize({
container: 'coast-container', // element id or HTMLElement
embedToken,
onReady: () => {
// the embedded app has finished loading and is ready to be used
console.log('Coast widget is ready');
},
onError: (error) => {
console.error('Coast widget error:', error);
},
});
API
coast.initialize(options)
Mounts the widget iframe into the container element and returns a CoastWidget instance.
Single-instance limit: Only one widget may be active at a time. Calling
initialize()while a widget already exists automatically destroys the previous one.
| Option | Type | Required | Description |
|---|---|---|---|
container | string | HTMLElement | Yes | Element id or a direct HTMLElement reference |
embedToken | string | Yes | Opaque session token from your backend's Embed Token API call |
onReady | () => void | No | Called when the embedded app has finished loading and is ready to be used |
onError | (error: Error) => void | No | Called on initialization failure or if the embedded app fails to load within 30 seconds |
onLogin | () => void | No | Called once the user is authenticated in the embedded app. Fires for restored sessions too and may fire more than once for the same user — make your handler idempotent. Client-side notification only — confirm server-side before recording state |
onLogout | () => void | No | Called when the user logs out from within the embedded app (e.g. session expiry) |
widget.logout()
Notifies the embedded app that the host user has logged out. Call this when your own session ends.
widget.destroy()
Removes the iframe and cleans up all event listeners.