Skip to main content

Fluid Virtual Widget Integration for Sweepstakes

The Fluid Virtual, same as the standard 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 injecting <fluid-virtual> web component into the DOM, providing required init attributes.

Automatic Init​

Init Params- operator id- user id- session id- locale- country code- currency code- virtual currencies- packs- (user data)Reactive Params- session id- transaction type- lock transaction type- open- balance- deposit limit- deposit amount- user data- turned over percentage- success cta link- transaction attributeslogin => inject => initHost sitewidget

The <fluid-virtual> 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.

Fluid Virtual 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 - FIAT currency code according to ISO 4217 **
  • virtual-currencies - virtual currencies held by the user, object of type VirtualCurrencies available in the @fluidpayments/types package, stringified as JSON:
type VirtualCurrencies = {
    depositCurrency: VirtualCurrency;
    withdrawalCurrency: VirtualCurrency;
};

type VirtualCurrency = {
    name: string;
    code: string;
    symbol: string;
    exchangeRateToFiatCurrency: number;
    icon?: string;
    conversionOffset?: number;
};
  • 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 balances, object of type VirtualBalance available in the @fluidpayments/types package, stringified as JSON:
type VirtualBalance = {
    depositCurrencyBalance: number;
    withdrawalCurrencyBalance: number;
    lockedWithdrawalCurrencyBalance?: number;
};
  • packs - stringified packs 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 - up-to-date balance information in virtual currencies
  • 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 Quick Buy and Redeem
  • 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

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 - 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.
  • 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
    • handle-banner-cta-click - when the user clicks on the banner on the first step of Quick Buy flow

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 src="https://get.fluidpayments.io/index.js"></script>
<fluid-virtual
    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>"
    packs="<packs 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>"
    virtual-currencies="<virtual currency data>"
>
</fluid-virtual>

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, locale, and currency.

Packs Data Object​

Fluid Virtual organises packs into five sections, each with its own layout: a grid of regular packs, a carousel of promoted packs (in the green, red, and yellow color variants), a promoted special banner, a promoted on abort modal, and a promoted upsell strip. The diagram below labels each pack type with the properties that drive its appearance — label, price, previousPrice, discount, info, tagged, and expirationDate — so you can map what you pass to what users see. The variant field only controls the badge colour; the badge text comes from label, the price-in-red treatment from priceHighlighted, and the upsell's secondary red badge from discount.

Anatomy of a Sweepstakes pack

Figure - Anatomy of a Sweepstakes pack

type Pack = {
    packId: string;
    variant: PackVariant;
    value: {
        price: number;
        previousPrice?: number;
        deposit: number;
        withdrawal: number;
    };
    logoUrl: string;
    logoAlt?: string;
    label?: string;
    title?: string; /** @deprecated Use `label` instead. */
    info?: string;
    tagged?: boolean;
    selected?: boolean;
    expirationDate?: Date;
    discount?: string;
    /**
     * When `true`, renders the current price in the accent (red) colour.
     * Has no visible effect when `value.previousPrice` is set — that path already uses the accent colour.
     * When omitted, treated as `false`.
     */
    priceHighlighted?: boolean;
};

type PackSet = {
    regular: Pack[];
    promoted: Pack[];
    promotedSpecial?: Pack;
    promotedUpsell?: Pack;
    promotedOnAbort?: Pack;
};

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

const packs = {
    regular: [
        {
            packId: "pack-regular-01",
            logoUrl: "assets/images/sweepstakes/pack-4.99.png",
            variant: "regular",
            value: {
                price: 4.99,
                deposit: 5000,
                withdrawal: 5,
            },
        },
        {
            packId: "pack-regular-02",
            logoUrl: "assets/images/sweepstakes/pack-9.99.png",
            variant: "regular",
            value: {
                price: 9.99,
                deposit: 10000,
                withdrawal: 10,
            },
        },
    ],
    promoted: [
        {
            packId: "pack-red-01",
            logoUrl: "assets/images/sweepstakes/pack-red.png",
            variant: "red", // colour of the badge — purely visual
            label: "-25%", // text shown on the badge
            value: {
                price: 49.99,
                previousPrice: 64.99, // when set, the current price is auto-rendered in the accent (red) colour
                deposit: 65000,
                withdrawal: 65,
            },
        },
        {
            packId: "pack-yellow-01",
            logoUrl: "assets/images/sweepstakes/pack-yellow.png",
            variant: "yellow",
            label: "Exclusive",
            priceHighlighted: true, // renders the price in the accent (red) colour even without a previousPrice
            tagged: true,
            value: {
                price: 79.99,
                deposit: 100000,
                withdrawal: 100,
            },
        },
        {
            packId: "pack-green-01",
            logoUrl: "assets/images/sweepstakes/pack-green.png",
            variant: "green",
            label: "Best value",
            value: {
                price: 9.99,
                deposit: 15000,
                withdrawal: 15,
            },
        },
    ],
    promotedSpecial: {
        packId: "pack-promotion-01",
        logoUrl: "assets/images/sweepstakes/special-promotion.png",
        variant: "promotion",
        label: "Special promotion",
        info: "+ 5,000 purchases this week",
        expirationDate: "2026-12-31T23:59:59Z",
        value: {
            price: 74.99,
            previousPrice: 99.99, // previousPrice already paints the price in the accent colour — no priceHighlighted needed
            deposit: 10000,
            withdrawal: 5,
        },
    },
    promotedUpsell: {
        packId: "pack-promotion-upsell-01",
        logoUrl: "assets/images/sweepstakes/upsell-promotion.png",
        variant: "promotion",
        label: "Exclusive Offer",
        expirationDate: "2026-12-31T23:59:59Z",
        discount: "-15%", // the only place the `discount` field is rendered: as a second red badge next to `label`
        value: {
            price: 89.99,
            previousPrice: 99.99,
            deposit: 10000,
            withdrawal: 100,
        },
    },
    promotedOnAbort: {
        packId: "pack-promotion-upsell-modal-01",
        logoUrl: "assets/images/sweepstakes/upsell-promotion-modal.png",
        variant: "promotion",
        label: "Special promotion",
        info: "+ 5,000 purchases this week",
        expirationDate: "2026-12-31T23:59:59Z",
        value: {
            price: 89.99,
            previousPrice: 99.99,
            deposit: 10000,
            withdrawal: 100,
        },
    },
};

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

Packs usage​

  • regular: default list of packs, shown on First-Time Deposit and in the View All Packs dialog
  • promoted: packs displayed in the carousel
  • promotedSpecial: main promotional pack displayed below the carousel on First-Time Deposit and in the View All Packs dialog
  • promotedUpsell pack displayed at the bottom of the payment method selection on First-Time Deposit and on the first step of a Subsequent Deposit
  • promotedOnAbort if available, displayed in a modal when the user closes the wallet during the deposit journey

Packs structure​

  • packId (string) - unique identifier of the pack
  • variant (string) - 'regular' | 'green' | 'red' | 'yellow' | 'promotion'
  • value (object) - details of the pack:
    • price (number) - price of the pack in FIAT currency
    • previousPrice (optional, number) - previous price of the pack in FIAT currency, used to show a price discount
    • deposit (number) - amount of virtual currency credited to user's deposit balance
    • withdrawal (number) - amount of virtual currency credited to user's withdrawal balance
  • logoUrl (string) - URL of the pack image*
  • logoAlt (optional, string) - alt text for the pack image
  • label (optional, string) - text shown on the pack badge (for example "Best value" on a green pack)
  • info (optional, string) - additional info label for the pack
  • tagged (optional, boolean) - indicates if the pack should be visually tagged
  • selected (optional, boolean) - indicates if the pack is preselected
  • expirationDate (optional, Date) - expiration date of the pack in ISO 8601 format
  • discount (optional, string) - discount text, for example "-25%". Used only by the promoted upsell, where it renders as a second red badge alongside label.
  • priceHighlighted (optional, boolean) - renders the current price in the accent (red) colour. Has no visible effect when value.previousPrice is set (that path already uses the accent colour). Defaults to false when omitted.

Backwards compatibility​

The label property and the green/red/yellow variant values replace the previous title property and best_value/discount/exclusive variants. Existing integrations that still pass the deprecated names continue to work — Fluid normalizes them at the input boundary — but new integrations should use the new vocabulary, and existing operators are encouraged to migrate.

The normalization layer also preserves two side-effects the deprecated variants used to imply:

  • Packs sent with variant: "exclusive" automatically get priceHighlighted: true so the price keeps rendering in the accent colour, matching the old yellow-exclusive look.
  • Packs sent with variant: "discount" that only carry a discount text (and no label) automatically receive label = discount so the carousel badge keeps its text after the rendering switch from discount to label.

Pack image dimensions​

All the images used for the packs have a ratio of 2:1.
The available dimensions are:

  • regular, promoted and promotedUpsell packs: 154px × 77px (308px × 154px for retina)
  • promotedSpecial and promotedOnAbort packs: 328px × 164px (656px × 328px for retina)

The retina dimension is recommended, for a sharp display on mobile devices.

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.