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

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

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.

Packs Data Object

type Pack = {
    packId: string;
    variant: PackVariant;
    value: {
        price: number;
        previousPrice?: number;
        deposit: number;
        withdrawal: number;
    }
    logoUrl: string;
    logoAlt?: string;
    title?: string;
    info?: string;
    tagged?: boolean;
    selected?: boolean;
    expirationDate?: Date;
    discount?: string;
}

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-discount-01',
            logoUrl: 'assets/images/sweepstakes/pack-discount.png',
            variant: 'discount',
            discount: '-25%',
            value: {
                price: 49.99,
                previousPrice: 64.99,
                deposit: 65000,
                withdrawal: 65
            }
        },
        {
            packId: 'pack-exclusive-01',
            logoUrl: 'assets/images/sweepstakes/pack-exclusive.png',
            variant: 'exclusive',
            title: 'Exclusive',
            tagged: true,
            value: {
                price: 79.99,
                deposit: 100000,
                withdrawal: 100
            }
        },
        {
            packId: 'pack-bestvalue-01',
            logoUrl: 'assets/images/sweepstakes/pack-best-value.png',
            variant: 'best_value',
            title: 'Best value',
            value: {
                price: 9.99,
                deposit: 15000,
                withdrawal: 15
            }
        }
    ],
    promotedSpecial: {
        packId: 'pack-promotion-01',
        logoUrl: 'assets/images/sweepstakes/special-promotion.png',
        variant: 'promotion',
        title: 'Special promotion',
        info: '+ 5,000 purchases this week',
        expirationDate: '2026-12-31T23:59:59Z',
        value: {
            price: 74.99,
            previousPrice: 99.99,
            deposit: 10000,
            withdrawal: 5
        }
    },
    promotedUpsell: {
        packId: 'pack-promotion-upsell-01',
        logoUrl: 'assets/images/sweepstakes/upsell-promotion.png',
        variant: 'promotion',
        title: 'Exclusive Offer',
        expirationDate: '2026-12-31T23:59:59Z',
        discount: '-15%',
        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',
        title: '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' | 'discount' | 'exclusive' | 'best_value' | '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 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
• title (optional, string) - title label for the 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 label for the pack

*Pack logo image size should be 164×82px (328×164 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.