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.

Automatic Init

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.

Programmatic Init

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;
    transactionAttributes?: Record<string, string>;
}

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.

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 **
  • 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
  • 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

** 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
  • 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

Note that there won't be any reaction to changes of those 6 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 - the user has clicked on the CTA shown on the successful deposit or withdrawal screen
    • deposit-success - when a successful deposit is made
    • deposit-failure - deposit attempt failed
    • withdrawal-success - when a successful withdrawal is made
    • withdrawal-failure - withdrawal attempt failed
    • withdrawal-cancelled - when a withdrawal is cancelled
    • start-kyc-verification - when the user clicks on the Verify button in the fluent message
    • contact-support - when the user clicks on the Contact Support link in the failure screen
  • 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
  • fluid-command:
    • close - user selected to close the wallet from within, the open attribute should be set to false

Note: The list above gives examples of notifications emitted by the fluid widget, it is not an exhaustive list of all notifications.

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>
<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>"
    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>"
>
</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",
    "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.
  • 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;
    fullName?: string;
    previousDeposit?: number;
    lifetimeDeposit?: number;
    kycStatus?: FluidKycStatus;
}

All the properties are optional.