Skip to main content

Fluid Widget Integration

Integration​

The Fluid Widget is implemented as a web component integrated into the host page DOM. By design, the Fluid widget script should get injected into the host site upon user authentication.

After that, the widget can be initialised in one of two ways. Both end in the same state, a configured widget that emits initialised and is ready to open; they differ in what triggers the initialisation and in how the element is expected to live in your DOM:

  • Automatic Init: the <fluid-widget> element itself triggers initialisation when it is added to the DOM with the required attributes. The element is both the initialiser and the UI.
  • Programmatic Init: you trigger initialisation explicitly by calling fluid.init(...) right after the script loads, before any element exists. The element you mount later is only the UI, and mounting it is instant because the initialisation work is already done.

Choosing between them comes down to how your page treats the element:

Automatic InitProgrammatic Init
Initialisation is triggered byAdding the element to the DOMCalling fluid.init(...)
When it happensOn element mountRight after the script loads, before any mount
Attributes on the elementThe full required setOnly the reactive ones (session-id, transaction, open, balance, ...)
The element livesPermanently, mounted once per sessionWherever your framework puts it, mounted and unmounted freely
Use it whenThe widget element sits in a stable part of your page for the whole sessionYour framework re-renders or conditionally renders the element, e.g. it exists only while the cashier is open, or is recreated on route changes

Automatic Init​

This is the recommended way in most cases.

Init Params- operator id- user id- session id- locale- country code- currency code- (bonuses)- (user data)Reactive Params- session id- transaction type- lock transaction type- open- balance- withdrawable balance- deposit limit- deposit amount- bonuses- user data- turned over percentage- success cta link- transaction attributes- prefilled bonus code- two factor auth enabled- withdrawal warninglogin => inject => initHost sitewidget

The flow: on user authentication, inject the script and add <fluid-widget> with the required attributes (see the Attributes reference). The element initialises itself and a notification indicates the widget is ready for opening - it should not be allowed to open before this notification is emitted. The element then stays in the DOM for the whole session, driven through its reactive attributes.

Once the session ends, the widget should be removed from the DOM to ensure proper shutdown.

For the rules that keep a session healthy, and fixes for the mistakes that most often break new integrations, see Session handling.

Programmatic Init​

Use this method when the element is not permanent: when it is rendered only while the cashier is open, recreated on navigation, or otherwise injected many times during a session. If initialisation only happened on mount, every one of those mounts would start from scratch; fluid.init() moves that work to login time, so each mount finds everything prepared.

1. login => initfluid.init({operatorId, userId, sessionId,locale, countryCode, currencyCode, (bonuses),(userData)})Host site2. open => injectReactive Params- session id- transaction type- lock transaction type- open- balance- withdrawable balance- deposit limit- deposit amount- bonuses- user data- turned over percentage- success cta link- transaction attributes- prefilled bonus code- two factor auth enabled- withdrawal warningwidget

The flow: on user authentication, inject the script and immediately call the global fluid.init function with the init payload. The function accepts an instance of the FluidInitParams type, available in the @fluidpayments/types package. Unless it's specifically intended, fluid.init should be called only once per user session; to update widget parameters afterwards, use the reactive attributes.

type FluidInitParams = {
    operatorId: number;
    userId: string;
    sessionId: string;
    locale: string;
    countryCode: string;
    currencyCode: string;
    bonuses?: FluidBonusData;
    userData?: FluidUserData;
}

Note that fluid.init uses countryCode and currencyCode, while the HTML attributes are named country and currency.

Then, whenever your page renders the widget component, provide only the reactive parameters, like transaction, open, balance, withdrawable-balance, bonuses, deposit-limit, success-cta-link and session-id.

Important: fluid.init prepares the widget but does not render or open any UI. The UI always comes from the <fluid-widget> element and its open attribute.

Note: if bonuses data doesn't change the widget won't process it again on inject, same with session-id - if it's the same as provided to the init function, the widget won't re-initialise. Otherwise, if any of the required init parameters change, the widget will re-initialise itself on inject.

Validation: fluid.init validates locale before initialising. POSIX-style underscores are normalised (en_GB is accepted as en-GB); if the resulting value is still not a valid IETF BCP 47 tag, the returned promise rejects with an Error whose message describes the offending value. This differs from the HTML-attribute path, which falls back to en and emits a fluid-error event instead - programmatic callers are expected to surface the failure explicitly.

Warning: Only one Fluid Widget custom element should be present in the DOM, otherwise unexpected behaviour may occur.

Attributes​

The full attribute reference, including which attributes are required, which are shared with the other widgets and which are reactive, lives on the Attributes page.

Initial mandatory attributes for Automatic Init are: operator-id, session-id, user-id, locale, country, and currency.

Notifications​

The widget reports its state and user actions to the host site through fluid-info, fluid-error and fluid-command DOM events. The full catalogue, including every message value and which widgets emit it, lives on the Events and errors page.

For cases where the widget needs to request data or trigger an action on the host page and receive a typed response, see the Window Bridge API.

Example code​

The following is an example of what's to be injected to your website DOM upon user login for Automatic Init:

<script src="https://get.fluidpayments.io/index.js"></script>
<fluid-widget
	operator-id="<your operator ID>"
	session-id="<authenticated user session ID>"
	user-id="<authenticated user ID>"
	user-data="<authenticated user details>"
	locale="<locale tag>"
	country="<authenticated user country>"
	currency="<user currency code>"
	transaction="<deposit / withdrawal / quick-deposit>"
	lock-transaction-type="<false / true>"
	open="<false / true>"
	balance="<user current balance>"
	withdrawable-balance="<user current withdrawable balance>"
	bonuses="<bonus data>"
	deposit-limit="<responsible gaming current deposit limit>"
	success-cta-link="<link to URL/Path following successful transaction>"
	z-index="<z-index value>"
	transaction-attributes="<stringified json object of key-value pairs for payment provider>"
	deposit-amount="<pre-filled deposit amount>"
	prefilled-bonus-code="<bonus code to pre-fill>"
	two-factor-auth-enabled="<false / true>"
>
</fluid-widget>

It should stay present in the DOM for the time of user session.

The bonus and user data object shapes are documented on the Data objects page.

Going further​