Fluid Sweepstakes

Fluid Sweepstakes (<fluid-virtual>) is tailored for sweepstakes platforms. It supports virtual currency pack purchases and redemption features.

When to use Fluid Sweepstakes

Use Fluid Sweepstakes when your platform:

• Operates as a sweepstakes or social casino
• Uses virtual currencies (e.g. Gold Coins, Sweeps Coins)
• Needs a cashier for purchasing currency packs and redeeming winnings

What users see

• Pack browsing. Packs are listed with promoted packs first, and can be grouped into categories that users browse through a row of pills. A special promotion pack gets its own banner.
• Custom amount. Users can also buy a custom amount through an amount input field, which shows the converted amount of each currency as they type.
• Visual highlights. Packs can carry a coloured badge to highlight an offer, and a “Hot” tag to draw attention.

You choose which of these to show: the promotional packs and categories are optional, and you leave out what doesn’t fit your promotional strategy. See Packs for how each pack property maps to what users see.

Loading the script

<script src="https://get.fluidpayments.io/index.js"></script>

Mounting the widget

<fluid-virtual
  operator-id="your-operator-id"
  session-id="user-session-id"
  user-id="user-id"
  locale="en"
  currency="USD"
  country="USA"
  virtual-currencies='{"version":2,"currencies":[{"id":"gc","name":"Gold Coins","code":"GC","symbol":"GC","exchangeRateToFiatCurrency":1000},{"id":"sc","name":"Sweeps Coins","code":"SC","symbol":"SC","exchangeRateToFiatCurrency":1}],"primaryId":"gc","secondaryId":"sc"}'
></fluid-virtual>

currency is the user’s FIAT currency, the one pack prices are expressed in. virtual-currencies is required for Fluid Sweepstakes. It’s a JSON object, so wrap it in single quotes in HTML — see Virtual currencies below for the format.

Mount the element once the user has authenticated, and keep it in the DOM for the whole user session. See Session handling for the full lifecycle.

Initialisation

const virtual = document.createElement('fluid-virtual');

// Set required attributes
virtual.setAttribute('operator-id', 'your-operator-id');
virtual.setAttribute('session-id', 'user-session-id');
virtual.setAttribute('user-id', 'user-id');
virtual.setAttribute('locale', 'en');
virtual.setAttribute('currency', 'USD');
virtual.setAttribute('country', 'USA');
virtual.setAttribute('virtual-currencies', JSON.stringify(virtualCurrencies)); // see Virtual currencies below

// Attach listeners
virtual.addEventListener('fluid-info', handleInfo);
virtual.addEventListener('fluid-error', handleError);
virtual.addEventListener('fluid-command', handleCommand);

// Mount
document.body.appendChild(virtual);

Opening

Once the initialised event fires, set open to true. To choose the flow, set the transaction attribute first — it is applied only while the wallet is closed:

// Open to the purchase flow
virtual.setAttribute('transaction', 'deposit');
virtual.setAttribute('open', 'true');

// Open to the redeem flow
virtual.setAttribute('transaction', 'withdrawal');
virtual.setAttribute('open', 'true');

// Open to Quick Buy
virtual.setAttribute('transaction', 'quick-deposit');
virtual.setAttribute('open', 'true');

Quick Buy (quick-deposit) is a shortened purchase flow on a single screen: the player picks a pack and pays without going through the separate steps. It ignores a preselected pack or category, which apply to the purchase flow only (see Packs).

Virtual currency data

Fluid Sweepstakes requires virtual currency and balance data to be passed via data objects. See Data Objects for the full specification.

Note

The virtual-currencies, balance and packs payloads are versioned. Send version: 2 for the multi-currency shape shown on this page. Payloads without a version field are still read as the previous shape, so existing integrations keep working — see Backwards compatibility.

Virtual currencies

Required. Define the virtual currencies your platform uses as a VirtualCurrencies object, and say which one is primary (the currency to play with) and which is secondary (the redeemable one). Both need an exchangeRateToFiatCurrency:

const virtualCurrencies = {
  version: 2,
  currencies: [
    { id: 'gc', name: 'Gold Coins', code: 'GC', symbol: 'GC', exchangeRateToFiatCurrency: 1000 },
    { id: 'sc', name: 'Sweeps Coins', code: 'SC', symbol: 'SC', exchangeRateToFiatCurrency: 1 }
  ],
  primaryId: 'gc',
  secondaryId: 'sc'
};

virtual.setAttribute('virtual-currencies', JSON.stringify(virtualCurrencies));

Balance

Pass the user’s current balance in the balance attribute as a stringified VirtualBalance object — one amount for the primary currency, one for the secondary. Unlike on <fluid-widget>, balance here is JSON, not a plain number, and withdrawable-balance is not supported:

virtual.setAttribute('balance', JSON.stringify({
  version: 2,
  primaryBalance: 1000,
  secondaryBalance: 50
}));

Packs

Define the purchasable currency packs as a PackSet. Each pack’s items refer to the currency ids defined above, and price is in the FIAT currency:

virtual.setAttribute('packs', JSON.stringify({
  version: 2,
  promoted: [
    {
      version: 2,
      packId: 'pack-2',
      variant: 'promotion',
      value: {
        price: 19.99,
        items: [
          { currencyId: 'gc', amount: 25000 },
          { currencyId: 'sc', amount: 25 }
        ]
      },
      logoUrl: 'https://example.com/packs/pack-2.png'
    }
  ],
  regular: [
    {
      version: 2,
      packId: 'pack-1',
      variant: 'regular',
      value: {
        price: 9.99,
        items: [
          { currencyId: 'gc', amount: 10000 },
          { currencyId: 'sc', amount: 10 }
        ]
      },
      logoUrl: 'https://example.com/packs/pack-1.png'
    }
  ]
}));

For a pack set using every slot and categories, see the example pack set.

Event handling

Fluid Sweepstakes emits the same events as the other widgets. A currency pack purchase is reported as deposit-success and a redemption as withdrawal-success — see Events & Errors for the full list:

virtual.addEventListener('fluid-info', (e) => {
  const { message } = e.detail;

  switch (message) {
    case 'initialised':
      break;
    case 'deposit-success':
      // Currency pack purchased
      break;
    case 'withdrawal-success':
      // Redemption successful
      break;
  }
});

Cleanup

virtual.remove();

Remove the element when the user session ends, for example on logout.

Full example

An example of everything that can be injected into your page on user login. Only operator-id, session-id, user-id, locale, country, currency and virtual-currencies are required:

<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 FIAT currency code>"
  transaction="<deposit / withdrawal / quick-deposit>"
  lock-transaction-type="<false / true>"
  open="<false / true>"
  balance="<user current balances>"
  packs="<packs data>"
  virtual-currencies="<virtual currency data>"
  transaction-limits="<transaction limit data>"
  success-cta-link="<link to URL/path following a successful transaction>"
  z-index="<z-index value>"
  transaction-attributes="<stringified JSON object of key-value pairs for the payment provider>"
  deposit-amount="<pre-filled deposit amount>"
  turned-over-percentage="<turned over percentage>"
  allow-decimal-amounts="<true / false>"
></fluid-virtual>

See the Attributes reference for what each attribute does and which ones are reactive.