Configuration
The widget is configured through an options object passed to the constructor, or through a JSON data-config attribute on the mount element. When both are present, data-config values win.
let widget = new window.Sitata.claims(el, {
orgId: "<YOUR ORG ID>",
token: "<YOUR PUBLIC TOKEN>",
isB2B: true
});
widget.run();
Options
| Property | Type | Default | Description |
|---|---|---|---|
| orgId | String | โ | Required. Your organization's identifier. The widget will not load without it. |
| token | String | โ | Required. Your organization's public authentication token. Sent as Authorization: PUB <token>. |
| apiBase | String | https://www.sitata.com/api/v2 | Override the REST API base URL. |
| isB2B | Boolean | false | Whitelabel mode. When true, your branding is used and a "Powered by Sitata" footer is shown. When false, Sitata branding is used. |
| companyName | String | "Sitata" | Company name shown in the header and on the login screen. |
| logoUrl | String | โ | URL of your logo, shown in the header and login screen (whitelabel mode). |
| primaryColor | String | #1E88E5 | Primary theme color (hex). |
| accentColor | String | #FF8F00 | Accent/secondary theme color (hex). |
| hideHeader | Boolean | false | Hide the widget's header bar so it nests inside your own page chrome. A simple inline "Back" control is used instead. |
| lang | String | auto | Force the UI language (two-letter code, e.g. es). Otherwise a ?lang= URL parameter, then the browser language, then English is used. |
| widgetToken | String | โ | A short-lived token you mint server-side for the signed-in customer (see Pre-Authenticating A Customer). When valid, the widget skips the PIN login. Takes precedence over userToken. |
| onSessionExpired | Function | โ | Constructor option only (functions can't go in data-config). Called when the customer's widget session expires; return a freshly minted widgetToken (or a Promise of one) to continue without a reload. See Session Expiry. |
| userToken | String | โ | Deprecated โ use widgetToken. The customer's permanent authentication token. Still supported, but it never expires, so anyone who reads it from your page can use it indefinitely. The widget logs a console warning when it is used. |
| subscriptionId | String | โ | Deep-link: on load, start a new claim under this subscription (policy), skipping the list and policy-selection step. |
| claimId | String | โ | Deep-link: on load, open this specific existing claim's detail view. |
| socketUrl | String | wss://sockets.sitata.com/socket/websocket | WebSocket endpoint used for live support chat. |
| httpBase | String | https://www.sitata.com | Base host used by supporting API helpers. |
info
There is no separate currency option โ a claim's currency is taken from the policy (subscription) it belongs to.
Example
<div id="claims-app"></div>
<script>
window.document.addEventListener("sitata:claimsReady", function () {
var el = document.getElementById("claims-app");
var widget = new window.Sitata.claims(el, {
orgId: "0774f78c-56ff-47d8-989e-b050d72a2c7f",
token: "f7ed4b59-2981-499b-b33a-b09255cb950f",
isB2B: true,
companyName: "Air Advisor",
logoUrl: "https://airadvisor.com/logo.png",
primaryColor: "#f05800",
accentColor: "#f000e8",
hideHeader: true,
// minted on your server for this page render โ see below
widgetToken: "<%= widget_token %>",
subscriptionId: "THE_SUBSCRIPTION_ID"
});
widget.run();
});
</script>
<script async src="https://www.sitata.com/widgets/claims.js"></script>
Pre-Authenticating A Customer
When the customer is already signed in to your portal, you can sign them in to the widget too, so they never see the PIN screen. Do this with a short-lived widget token minted by your server:
- Mint on your server. Call
POST /api/v2/users/{user_id}/widget_tokenwith your organization's private token. Never do this from the browser โ your private token must stay on your server. - Render it into the page as the
widgetTokenoption (constructor ordata-config). - The widget exchanges it for a session and signs the customer in. Only that session is stored in the browser.
// Your server (Node.js shown) โ runs on every page render
const res = await fetch(`https://www.sitata.com/api/v2/users/${customer.sitataUserId}/widget_token`, {
method: "POST",
headers: {
Authorization: `TKN ${process.env.SITATA_PRIVATE_TOKEN}`,
"Content-Type": "application/json",
},
});
const { widget_token } = await res.json();
// pass widget_token to your page template as `widgetToken`
| Lifetime | Notes | |
|---|---|---|
| Widget token | 5 minutes | Single use. Mint a new one every time you render the widget โ a reloaded page that reuses an old token falls back to the PIN screen. |
| Widget session | 12 hours | Created by the widget from the token. Expires on its own; it is never your customer's permanent credential. |
You can mint for a customer who is a traveller at your organization (for example, they bought a policy through you) and has no other role. Optionally pass subscription_id to bind the token to one of their policies.
If the token can't be used (expired, already used, or not valid), the widget clears any stored session and shows the PIN login, so the customer can still sign in.
Session Expiry
When a widget session expires โ or the API rejects it โ the widget signs the customer out of the widget, shows the PIN login, and then:
- fires
sitata:claimsSessionExpiredondocument, with the widget instance atevent.detail.widget, and - calls your
onSessionExpired(widget)callback, if you provided one.
To keep the customer signed in, fetch a fresh token from your server and either return it from onSessionExpired or pass it to widget.setWidgetToken(token):
var widget = new window.Sitata.claims(el, {
orgId: "<YOUR ORG ID>",
token: "<YOUR PUBLIC TOKEN>",
widgetToken: "<TOKEN MINTED FOR THIS RENDER>",
onSessionExpired: async function () {
// your own endpoint, which mints a widget token server-side
var res = await fetch("/my-portal/sitata-widget-token", { credentials: "include" });
if (!res.ok) return null; // customer is no longer signed in to your portal: show PIN login
return (await res.json()).widgetToken;
}
});
widget.run();
If you configure the widget through data-config, listen for the event instead:
document.addEventListener("sitata:claimsSessionExpired", async function (event) {
var token = await getFreshWidgetTokenFromMyServer();
if (token) event.detail.widget.setWidgetToken(token);
});
Signing Out
When the customer signs out of your portal, sign them out of the widget as well โ otherwise the widget session stays in the browser until it expires, which matters on shared devices:
await widget.logout();
logout() revokes the widget session on Sitata's side, clears everything the widget stored in the browser, and returns the widget to the login screen.
Migrating From userToken
userToken keeps working, but it places your customer's permanent API token in your page. Switch to widgetToken:
- Add the server-side mint call above.
- Replace
userToken: "..."withwidgetToken: "<minted token>". - Add
widget.logout()to your sign-out flow and, optionally,onSessionExpired.
Methods
| Method | Description |
|---|---|
run() | Authenticates your organization and the customer, then mounts the widget. Returns a Promise of the widget. |
setWidgetToken(token) | Signs a customer in with a freshly minted widget token, without reloading. Resolves true on success; on failure the widget shows the PIN login and resolves false. |
logout() | Signs the customer out of the widget: revokes the widget session, clears stored credentials and live chat, and shows the login screen. |
Deep-Linking A Customer To A Claim
The widget scopes claims to a customer's subscriptions (policies). To send a specific customer straight to the right place, combine:
orgId+tokenโ identify your organization.widgetTokenโ pre-authenticate the customer so they skip login (see Pre-Authenticating A Customer).- Either
subscriptionId(start a claim under that policy) orclaimId(open an existing claim).
As a fallback, if the page's own URL path ends with a claim's UUID, the widget will detect it and open that claim. An explicit claimId takes precedence over the URL.
Events
The widget exposes these lifecycle events:
| Event | Description |
|---|---|
| sitata:claimsReady | Fired on document once the widget bundle has loaded and is ready to be instantiated. Initialize the widget inside a listener for this event. |
| sitata:claimsSessionExpired | Fired on document when the customer's widget session expires or is rejected. event.detail.widget is the widget instance; call setWidgetToken() on it to sign the customer back in. See Session Expiry. |
warning
Apart from these, the widget does not emit domain callbacks such as "claim submitted" or "status changed" to the host page โ its state stays inside the widget. If you need your portal to react to claim progress, drive it from the server-side claim webhooks (events 600โ607) instead.
Styling
Theming is driven by the primaryColor and accentColor options. The widget renders as a responsive, full-width application and inherits your page's font, so in most cases setting your brand colors, logoUrl, and hideHeader is all that is needed. The widget currently renders in a light theme.
Environments
The loader and widget bundle are served from Sitata's own domain:
| Environment | Loader script |
|---|---|
| Production | https://www.sitata.com/widgets/claims.js |
| Staging | https://staging.sitata.com/widgets/claims.staging.js |
Point apiBase (and, if used, socketUrl) at the matching environment.