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, followed by either:

  • injecting <fluid-widget> web component into the DOM, providing required init attributes (Automatic Init)
  • calling fluid.init function with the init params object (Programmatic Init)

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)- (overscroll behavior)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 <fluid-widget> custom element expects several attributes required for initialisation (more on attributes here). If the required initialisation parameters are provided at injection, the widget will automatically initialise and be ready for use. This initialisation should occur once per user session, immediately after user authentication. A notification will indicate that the widget is ready for opening - it should not be allowed to open before this notification is emitted.

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

Programmatic Init​

This method is recommended if the widget is embedded in an element rendered on open, injected many times.

1. login => initfluid.init({operatorId, userId, sessionId,locale, countryCode, currencyCode, (bonuses),(userData), (overscrollBehavior)})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

If your website injects the Fluid component multiple times during a user session, ensure the widget is initialised upon user authentication. To do this, call the global fluid.init function with the necessary payload immediately after downloading the Fluid script. This 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 and to update widget parameters, use the reactive attributes.

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

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

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.

Fluid custom element attributes in detail​

Fluid widget setup expects a list of parameters to properly configure itself for an authenticated user:

  • operator-id - unique identifier of the host site / operator **
  • session-id - up-to-date session code of the currently authenticated user **
  • user-id - identifier of currently authenticated user **
  • user-data - details of currently authenticated user of type FluidUserData **
  • locale - locale tag according to IETF BCP 47 (e.g. en-NZ or es-MX), with en (default English) and ar (default Arabic) being an exception **. POSIX-style underscores are normalised automatically (en_GB is accepted as en-GB). If the value is still invalid after normalisation, the widget falls back to en and emits a fluid-error event with message invalid-init-attributes.
  • country - country of currently authenticated user in ISO 3166-1 Alpha-3 format **
  • currency - currency code according to ISO 4217 **
  • transaction - deposit | withdrawal | quick-deposit
  • lock-transaction-type - When true, the user cannot switch from the current transaction type.
  • open - true or false
  • balance - current user balance in given currency
  • withdrawable-balance - amount available to withdraw
  • bonuses - stringified bonus data, structure described below
  • deposit-limit - responsible gaming deposit limit
  • success-cta-link - link for the CTA button after a successful transaction
  • z-index - use a value high enough to display the wallet in front of other elements on the host site
  • turned-over-percentage - percentage of the turned over amount. If none is provided the information will not be displayed
  • transaction-attributes - a stringified JSON object of key-value pairs that will be sent to the payment provider as transaction attributes together with the user agent and bonus code (if applicable)
  • deposit-amount - the amount that will be pre-filled for the user in deposit. It takes precedence over the configured ones and should be unset for bringing back the default behaviour
  • prefilled-bonus-code - pre-fills the manual bonus code input field
  • two-factor-auth-enabled - when "true", adds a 2FA verification step to the withdrawal flow. See verify2FA
  • overscroll-behavior-auto - when added, the parameter will allow to set overscroll-behavior to auto for the inline version of the cashier.
  • withdrawal-warning - a stringified JSON object that displays a custom warning message on the withdrawal input screen, optionally with an action CTA. See Withdrawal Warning below for the object shape, examples and the emitted event.

** Mandatory for Automatic Init

The operator-id value must correspond to the Payment Operator Config property value. This value is provided by Fluid Payments.

Observed (reactive) Attributes​

The following attributes are observed by the widget and change in their value on the host site causes a reaction/event within the wallet.

  • open - triggers the wallet to become visible or hidden
  • balance and withdrawable-balance - update withdrawal information
  • session-id - assures consistently valid user session

Other reactive attributes are observed only while the wallet is closed:

  • transaction - updates transaction type
  • lock-transaction-type — locks the transaction type, preventing the user from switching between Deposit and Withdrawal
  • bonuses - updates bonuses information
  • deposit-limit - updates responsible gaming deposit limit amount
  • user-data - updates user data for resolving Suggested Deposit Amounts, Payment Methods Order and KYC status
  • success-cta-link - sets the link to follow on successful transaction
  • turned-over-percentage - sets the turned over percentage
  • transaction-attributes - updates transaction attributes sent with each transaction request
  • prefilled-bonus-code - pre-fills the manual bonus code input field. Requires manualBonusCodesEnabled to be enabled in operator configuration. The code is not auto-validated; the user must click "Apply" to trigger verification via the Bridge API
  • two-factor-auth-enabled - when set to "true", adds a 2FA verification step to the withdrawal flow. The user must enter a 6-digit authenticator code before the withdrawal is submitted. Code validation is handled via the Bridge API. This is a per-player flag — the host evaluates whether the player has 2FA enabled and sets it accordingly
  • withdrawal-warning - updates the custom warning message displayed on the withdrawal input screen

Note that there won't be any reaction to changes of those attributes while the wallet is open. This is to assure integrity of user's experience and that the transaction flow is not interrupted by any changes on the host site.

Notifications emitted by the Fluid Wallet​

In addition to receiving information from the host site, the Fluid wallet emits information out to the host website using CustomEvent (https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent), with the detail property containing the information. This property is an object with the following structure, also available as a type in the @fluidpayments/types package as FluidNotificationDetail

type FluidNotificationDetail = {
	message: string;
	[key: string]: any;
};

message contains a string with the different event types listed below.

Add the following code to receive those events:

fluid.addEventListener("fluid-command", onFluidCommand);
fluid.addEventListener("fluid-info", onFluidInfo);
fluid.addEventListener("fluid-error", onFluidError);
  • fluid-info - messages of informational nature, with the purpose of e.g. tracking or allowing user action
  • fluid-error - unexpected failure notifications
  • fluid-command - commands to react to

Possible values of those types can be expected to be:

  • fluid-info:
    • initialised - wallet has been prepared for opening - it should not be allowed to open before this is emitted
    • opened - the wallet has been opened
    • destroyed - the wallet instance has been terminated
    • internal-operation-change - transaction flow has been amended internally, e.g. upon withdrawal without a positive withdrawable balance
    • success-cta-click - user clicked on the CTA shown on the transaction success screen
    • deposit-success - when a successful deposit is made
    • deposit-failure - deposit attempt failed
    • error-cta-clicked - user clicked on the CTA shown on the transaction failure screen
    • withdrawal-success - when a successful withdrawal is made
    • withdrawal-failure - withdrawal attempt failed
    • withdrawal-cancelled - when a withdrawal is cancelled
    • contact-support - user clicked on the Contact Support link shown on transaction failure screen
    • bonus-changed - user changed selected deposit bonus
    • payment-method-changed - user changed the selected payment method
    • dialog-opened - a dialog has been opened from the wallet
    • dialog-closed - a dialog has been closed from the wallet
  • fluid-error:
    • initialisation-failure - Fluid wasn’t able to configure itself, e.g. due to a network or backend issue
    • operation-execution-failure - an operation failed unexpectedly due to an error
    • invalid-bonus-data - the bonus data is not in the correct format expected
    • invalid-user-data - the user data is not in the correct format expected
    • invalid-transaction-attributes - the transaction attributes are not in the correct format expected
    • invalid-init-attributes - an init attribute (currently the locale) failed validation; the widget falls back to a safe default (en for locale) and keeps initialising. When the widget is initialised programmatically via fluid.init(...), the call rejects with an error instead (see Programmatic Init above).
    • invalid-withdrawal-warning - the withdrawal-warning attribute could not be parsed as JSON. The widget renders no warning until the attribute is corrected. See Withdrawal Warning.
  • fluid-command:
    • close - user selected to close the wallet from within, the open attribute should be set to false
    • handle-transaction - when deposit or withdrawal is to be handled outside of Fluid
    • start-kyc-verification - when the user clicks on the Verify button in the fluent message
    • withdrawal-warning-cta-clicked - user clicked the CTA shown in the configured withdrawal warning. The host should react accordingly (for example, navigate the user to the bonuses screen). See Withdrawal Warning.

Note that fluid-infonotifications are not primarily designed for tracking, although some carry detailed information on the event, e.g. payment-method-changed, bonus-changed and all transaction result ones include activityId, representing unique user interaction with the wallet, which allows for stitching those events with a particular transaction id.

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 type="module" src="https://get.fluidpayments.io/index.js"></script>

<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.

Initial mandatory attributes are: operator-id, session-id, user-id, user-data, country, and locale.

Bonus Data Object​

The structure containing sample data (type of FluidBonusData available in the @fluidpayments/types package) is as follows:

const bonusData = [{
    "code": "DepositBonus",
    "title": "Deposit Bonus",
    "description": "100% up to 200€ + 10 Mega Spins",
    "logoUrl": "https://<operator-site>.com/assets/img/rewards/bonus-img/deposit-bonus.png",
    "maxBonus": 200,
    "maxBonusPercentage": 150,
    "minDeposit": 10,
    "maxDeposit": 250;
    "minDepositCount": 2;
    "maxDepositCount": 10;
    "minDaysSinceRegistration": 25;
    "maxDaysSinceRegistration": 180;
    "selected": true,
    "termsAndConditions": "Welcome Offer Terms And Conditions 1...",
    "paymentMethodFilter": {
        "applyTo": [
            {
                "providerType": "CREDITCARD"
            },
            {
                "providerType": "WEBREDIRECT",
                "service": "BLIXTPAY"
            }
        ],
        "excludeFrom": [
            {
                "providerType": "JETON"
            }
        ]
    }
}]

Figure 4 - Definition of Bonuses Passed to the Fluid Widget (Example)

  • The termsAndConditions of the bonus should be provided as an HTML string.
  • The logoUrl represents the URL of the bonus image*. If logoUrl is absent or the path is 404, a fallback image will be used. This fallback image has to be set from the CMS's theme.
  • Bonus codes will be available for all payment methods unless a paymentMethodFilter is specified.
  • If a paymentMethodFilter is used, the bonus is applied depending on the properties set.
    • If applyTo is set then the bonus only would apply to those listed payment methods.
    • If excludeFrom is set then the bonus won’t apply to those payment methods.
  • providerType is sufficient if the payment method does not have a service. Both values should be provided exactly as in Payment Provider configuration
  • maxBonus and maxBonusPercentage are not mandatory.
  • maxBonusPercentage requires a maxBonus value.
  • minDeposit is an optional property indicating the minimum deposit amount required for the bonus.
  • maxDeposit is an optional property indicating the maximum deposit amount required for the bonus.
  • minDaysSinceRegistration is an optional property indicating the minimum days since player registration required for the bonus.
  • maxDaysSinceRegistration is an optional property indicating the maximum days since player registration required for the bonus.
  • If there is a maxBonus but no maxBonusPercentage, it is assumed that maxBonusPercentage is 100% (examples of bonus calculations can be found in the deposit example section).
  • selected is an optional property indicating the bonus should be preselected. If more than 1 bonus is set to true a bonus configuration error will be thrown.

*Bonus logo image size should be 84x84px (168px168px for retina)

User Data Object​

Used for resolving Suggested Deposit Amounts and Payment Methods Order with use of Machine Learning based on historical transactions' data.

The structure, available as FluidUserData type in the @fluidpayments/types package, is as follows:

type FluidUserData = {
	age?: number;
	affiliateId?: string;
	depositCount?: number;
	daysSinceRegistration?: number;
	fullName?: string;
	kycStatus?: FluidKycStatus;
	lifetimeDeposit?: number;
	previousDeposit?: number;
	tags?: string[];
};

All the properties are optional.

Withdrawal Warning​

The withdrawal-warning attribute lets you surface a custom notice on the withdrawal input screen, for example, when an active bonus must be reviewed or cancelled before the player can withdraw. The warning appears in the initial (pre-focus) state of the amount input and is dismissed once the player focuses the input.

The attribute is observed while the wallet is closed: updating it then replaces the rendered warning the next time the wallet is opened.

The attribute value is a JSON string with the following shape:

type WithdrawalWarning = {
	title: string; // required, shown as the heading
	message?: string; // optional body text
	ctaLabel?: string; // optional; when set, renders a CTA button. Clicking emits `withdrawal-warning-cta-clicked` (fluid-command)
};

Field rules:

  • title is required. If it is missing, the warning is silently not shown.
  • message and ctaLabel are optional and independent. ctaLabel works with or without a message.
  • When ctaLabel is set, a primary CTA button is rendered under the message. Clicking it emits a fluid-command event with message: "withdrawal-warning-cta-clicked". Use this to react on the host page (for example, navigate the player to the bonuses screen).
  • If the attribute value is not valid JSON, the widget emits an invalid-withdrawal-warning fluid-error event and renders no warning.

Minimal example — title and message only:

<fluid-widget
	withdrawal-warning='{"title":"Active or Pending Bonuses","message":"You currently have an active/pending bonus. Please visit your profile and cancel the bonus to enable withdrawals."}'
	...
>
</fluid-widget>

With an action CTA:

<fluid-widget
	withdrawal-warning='{"title":"Active or Pending Bonuses","message":"You currently have an active/pending bonus. Please visit your profile and cancel the bonus to enable withdrawals.","ctaLabel":"Review bonuses"}'
	...
>
</fluid-widget>

Manual Bonus Codes​

When the Manual Bonus Codes feature is enabled in the CMS (Manual Bonus Codes Enabled), the widget displays a text input allowing the user to enter a bonus code manually. The widget validates the code using the verifyBonusCode Bridge API method.

Enabling the feature​

The feature is controlled by the Manual Bonus Codes Enabled setting in the Fluid CMS. When enabled, a bonus code input field appears in the deposit flow alongside the regular bonus list.

Bridge handler​

The host page must register a verifyBonusCode handler as described in the Window Bridge API documentation. The handler receives { code: string } (the trimmed user input) and must return a FluidBridgeVerifyBonusCodeResponse:

  • When status is 'valid', the bonus object must conform to the same structure as entries in the Bonus Data Object — including optional paymentMethodFilter, logoUrl, and termsAndConditions.
  • When status is 'invalid', the widget displays an error message to the user.
  • Optionally, return autoOptedIn: true on a valid response to control the post-validation bonus UX. See autoOptedIn behaviour for the full behaviour table.

CSS​

Font​

The font-family used by the widget will inherit from its parent element, ensuring consistency with the host site's typography.
If another font is desired, it can be set on the parent element of the <fluid-widget>.
The widget uses three different font weights, so the font-family should include all of them.