Embedding & auth

Embedding a widget is two steps: load the runtime once, then drop in a tag with a verified identity. There are two ways to prove identity — Access Key Embed when you have a backend, and Attribute Auth for HTML-only pages. Both verify the participant before a widget renders.

Load the runtime

The runtime is a single script that registers every fynxt-* custom element. Load it once per page — loading it more than once is a no-op. It has no dependencies and works from a plain <script> tag, a bundler import, or a CMS embed.

<script src="https://fynxt-incentive-program-widgets-sdk.s3.ap-south-1.amazonaws.com/fynxt-widgets-v1.js"></script>

Load it once. A single runtime instance is what lets multiple widgets share a cache, de-duplicate requests and share one real-time connection (see Shared runtime & data). Do not load the script per widget or inside an iframe per widget — that defeats data sharing.

Access Key Embed recommended

Use Access Key Embed whenever you have a backend. Your server exchanges your secret access key for a short-lived JWT — the embed-token — and you inject that token into the widget. The access key never reaches the browser, and the token carries a server-verified participant identity.

Your backend calls POST /api/widgets/embed-token with your access key and the participant you are rendering for.
FYNXT returns a signed, short-lived JWT (default TTL 15 minutes).
Your page renders the widget with that JWT in the embed-token attribute.
The runtime refreshes the token before it expires via a callback you provide (token-refresh).

embed-token

string (JWT)

required

Short-lived token minted by your backend from your access key. Identifies the participant and authorises the widget's data reads. Never put your raw access key in the browser.

token-refresh

function

optional

A callback (set in JS) the runtime invokes shortly before the current token expires. Return a fresh embed-token so long-lived dashboards never drop their session.

Where to get an access key. Access keys are issued per brand from the FYNXT Incentive admin console. Treat them like a password — store them server-side only. Contact FYNXT to provision an access key.

Attribute Auth no backend

When you only have an HTML container — a CMS page, a landing page, an email-gated portal with no server you can run code on — use Attribute Auth. You pass the participant's identity directly as data-* attributes. This is a browser-visible fallback: prefer a stable opaque ID over email where you can.

data-participant-id

string

required

The participant's stable FYNXT ID. Preferred over email — it does not change and is not PII.

data-partner-id

string

optional

The partner / IB the widget is scoped to, for network and referral widgets.

program-id

string

required

The incentive program whose data the widget should display.

Attribute Auth is browser-visible. Anyone can read or change a data-participant-id in the DOM, so Attribute Auth is only suitable for non-sensitive, read-only displays (public leaderboards, marketing badges). For participant financial data, use Access Key Embed.

Choosing an approach

	Access Key Embed	Attribute Auth
Needs a backend	Yes	No
Identity	Server-verified JWT	Browser-visible attribute
Secrets in browser	None	None (but identity is visible)
Good for	Client portals, IB dashboards, anything with participant financials	Public leaderboards, marketing & CMS pages
Recommended	Yes — default	Fallback only

Framework guides

Because widgets are standard custom elements, every framework renders them the same way it renders any HTML tag. A few framework-specific notes:

React

React passes string attributes through unchanged — set embed-token as a normal prop on the lowercased tag. For object-valued config, set it imperatively via a ref.

Angular

Add CUSTOM_ELEMENTS_SCHEMA to the module that uses the tags. Bind attributes with [attr.embed-token].

Vue

Tell the compiler the tags are custom elements (isCustomElement in the Vue config), then bind with :embed-token as usual.

Vanilla / CMS

Just write the tag. The Attribute Auth path needs no JavaScript at all beyond the runtime script.

Theming

Widgets render in a Shadow DOM, so your host CSS never leaks in and the widget's CSS never leaks out. Control appearance with attributes rather than overriding styles:

theme — "light" (default) or "dark".
accent — a hex color used for highlights, bars and links; defaults to the FYNXT brand blue.
locale — BCP-47 locale for number, date and currency formatting (e.g. "en-AE").

See the widget reference for the attributes each widget supports.

← Previous

Widgets overview

Widget reference