Skip to main content

Gamification (CataBoom™) Integration Guide

Presented by Exchange Solutions | October 7, 2025

Overview of CataBoom™ integration​

Intended audience​

This guide explains how to set up and configure CataBoom game mechanics with ES Loyalty. The integration ensures that loyalty members who earn a gameplay have rewards correctly attributed to their loyalty accounts.

CataBoom is an engagement and gamification solution that lets companies embed different game mechanics to engage and reward loyalty members. The integration drives loyalty acquisition (increasing enrollments), increases member engagement and average order value (AOV), and reduces churn and loyalty program abandonment.

The promotion engine in ES Loyalty™ evaluates offer types for standard transactions and activities, and awards gameplay for those that require it.

ES Loyalty currently supports the following game types in CataBoom (these interact with Exchange Solutions to provide game links and update points):

  1. Scratch Off: Click or scratch an area on the game card to reveal a reward.
  2. Slot Machine: Spin the reels to win rewards.
  3. Spin the Wheel: Spin a wheel to land on rewards.
  4. Quick Play: Streamlined, rapid interactive experiences with instant gratification elements.

Integration requires the following steps:

  1. Create the connection between CataBoom and Exchange Solutions: Create two webhooks so that the gamification mechanics can identify which loyalty member is playing and ensure that points earned are rewarded to the correct loyalty account in ES Loyalty. The two webhooks are an authentication webhook and a reward webhook.
  2. Create the game mechanics within CataBoom's platform and use the partner webhook.
  3. Configure supported CataBoom game mechanics in ES Loyalty so that these game types can be offered as loyalty rewards when the required behaviors for an offer are met.

Pre-requisites​

  1. The client must have a CataBoom instance.
  2. The Exchange Solutions Technical Solutions Architect (TSA) has enabled CataBoom integration for the client's loyalty instance.
  3. The TSA has access to the client's CataBoom instance (the admin portal), which typically uses the following URL format: 
    https://admin.cataboom.com/a/<client_Environment_Name>/campaigns
    The TSA team member assigned to this account has an Admin role created by CataBoom. The first TSA is assigned an Admin role and can provide Admin roles to other Exchange Solutions team members as required.
  4. Ensure that the TSA member has access to Link Configuration. This is needed when setting up the game mechanics. If required, ask CataBoom to grant access to this location in their console.

Integration tasks​

1. Configure authentication webhook​

  1. In the header, click the Webhooks menu.
  2. Scroll down to the Authentication Webhooks section.
  3. Click Create Webhook.
  4. Enter the following webhook details:
    • Webhook Name: ESL Auth Webhook
    • Webhook URL: 
      https://<env>/oauth2/token?client_id=<client_Id_value>&client_secret=<client_secret_value>&grant_type=client_credentials
    • Webhook Method: POST
    • Webhook Type: Auth
  5. Enter the following header details:
    • Header Key Name: Content-Type
    • Header Key Value: application/x-www-form-urlencoded

2. Configure partner ad-hoc reward webhook​

  1. In the header, click the Webhooks menu.
  2. Click Create Webhook.
  3. Enter the following webhook details:
    • Webhook Name: ESL Partner Ad-hoc Reward Webhook
    • Webhook URL: 
      https://api2-us-east-1.stage.exchangesolutions.com/qa-<client>-partner/client/partners/CATABOOM/adhoc-reward
    • Webhook Method: POST
  4. Click Save and Continue. You are directed to the ESL Partner Ad-hoc Reward Webhook details page.
  5. Add the following details:
    • Webhook Type: Standard
    • Authentication: Select the auth webhook created in the previous step: ESL Auth Webhook.
  6. Scroll down to the Body section.
  7. Select Text.
  8. Enter the following body content:
{
  "correlationId": "{{sys.play.code}}",
  "identifierType": "ACCOUNT_ID",
  "identifierValue": "{{passed_AccountID}}",
  "businessUnit": "suncor",
  "rewardId": "CATABOOM_ENROLL",
  "externalReferenceId": "{{passed_jti}}",
  "rewardAmount": {{sys.prize.description}},
  "extendedData": {
    "offerCode": "{{passed_OfferCode}}",
    "transactionID": "{{passed_TransactionID}}",
    "gameID": "{{passed_GameID}}"
  }
}

3. Configure supported CataBoom game in the CataBoom Console​

  1. ES Loyalty currently supports the following four game types:

    • Scratch Off: The player digitally scratches off a ticket to reveal a reward.
    • Slots: Similar to a casino slots wheel.
    • Spin the Wheel: A wheel spins and the prize is determined by where it comes to rest.
    • Quick Play: Click-and-reveal games that require simple actions.

    To configure supported games, click Campaigns on the navigation menu.

  2. Click the New Campaign button.

  3. Enter the following details:

    • Campaign Name: Use the following naming pattern: <GAME_TYPE>_<VARIATION>. For example: SCRATCH_OFF_MULTISCRATCH_3, SLOTS_3_REEL_SLOTS, or SPIN_WHEEL_SINGLE_WHEEL_SPIN.
    • URL: Accept the default value. Words are typically separated by hyphens. Note this value—it will be the game ID entered in the ES Loyalty Console.
    • Game Category: Select one of the supported game types listed in step 1.
    • Game: Select the desired variation of the supported game type.

  4. Click Create.

  5. Navigate to the newly created game campaign page.

  6. Click the Link Configuration button.

  7. On the right-hand side of the page, check Enable Dynamic Tokens.

  8. Scroll down and click Save Changes. This must be done before making any further changes to this page.

  9. Navigate to Map to Context.

  10. Select Form and add the following entries:

    Context variable nameSourcePassed parameter value
    passed_AccountIDPassed ParametersAccountID
    passed_OfferCodePassed ParametersOfferCode
    passed_TransactionIDPassed ParametersTransactionID
    passed_jtiPassed Parametersjti
    passed_GameIDPassed ParametersGameID

  11. Click Save Changes.

  12. Click the Summary menu on the navigation bar.

  13. Expand the Prize Options accordion section.

  14. Select Prize Control and Odds Setup:

    • Ensure that the Prize Level reflects the bonus points to be awarded.
    • For Prize Level 0 (the result when no prize is awarded), set the value to 0.
    • For Prize Level 1 and higher, set the value to the desired reward amount as an integer.
    • Obtain prize count or win percentage (Prcnt %) configuration details from CataBoom and the client, then enter those values here.
    • Click Save Prize Changes.

  15. Click the Summary menu on the navigation bar.

  16. Expand the Call-To-Action Links accordion section.

  17. For Exit Control, change the logic to Exit based on Logic.

  18. For Logic Exit 0, select Exit URL from the dropdown menu.

  19. Accept the remaining defaults.

  20. Click Save Changes.

  21. Click Summary.

  22. Expand the Call-to-Action Links accordion section.

  23. Click the Custom Logic Editor text button.

  24. Insert the following logic:

{
  "if": [
    {
      "==": [
        {
          "var": ["api.status"]
        },
        "200"
      ]
    },
    {
      "type": "cta",
      "value": "0"
    },
    {
      "type": "message",
      "value": "error"
    }
  ]
}
  1. Click Save Changes.

4. Set up game webhook trigger​

  1. To ensure that members who play games and earn points have those points reflected in their loyalty account, click Webhook Triggers in the navigation bar.
  2. On the right-hand side of the page, click the Add Writeback button.
  3. Enter the following information:
    • Writeback Name: Award Points
    • Enable Game Result Writeback: Ensure that all boxes are blue (enabled).
    • Trigger: Select Player Completes Game.
    • Webhooks: Select the Partner Ad-hoc Reward Webhook configured in step 2.
  4. Click Save Changes.

5. Set up game configuration in ES Loyalty Console​

note

Before proceeding, ensure that gamification-related configuration options are enabled and that users have the appropriate gamification roles and permissions.

The gamification mechanics created in CataBoom produce a gamification identifier (game ID). This identifier must be stored in Exchange Solutions to ensure that the correct game link is surfaced when the offer is fulfilled.

  1. After logging in to the ES Loyalty Console, navigate to Promotions > Games. If the client has multiple business units, you may also need to select a business unit.

  2. This page is used to manage (create and update) CataBoom games used as reward types for offers. Only PUBLISHED game types can be associated with a promotion. The Action dropdown menu lets the marketer:

    • Edit | Delete game details (applicable when game status is DRAFT, ACTIVE, or DISABLED).
    • Disable game. The game will not be available as a reward type when creating an offer. Applicable when game status is ACTIVE.
    • Enable game. The game becomes available as a reward type when creating an offer. Applicable when game status is DISABLED.

  3. Click the + Game button to create and save a new game reward type.

  4. Fill in the required fields:

    • Game ID: Copy the game identifier from CataBoom's game URL (obtained from the CataBoom Game mechanics page). The game identifier is the highlighted segment of the CataBoom URL.
    • Game Label: The value entered here appears in the dropdown when selecting a gameplay as a reward. Enter descriptive text.
    • Game Description: Optional. Include a description to clearly explain what the game is about.
    • JWT Secret: Obtain this value from the corresponding CataBoom Game Mechanics page.

  5. When finished, click Save and Publish. This makes the game available as a reward type (a non-points reward) that can be associated with an offer.

6. Create an offer with gameplay as reward type​

  1. A marketer can create a promotion that rewards a gameplay when a unit or spend behavior is met in a single transaction. For example:

    • Purchase 10L of fuel and get rewarded with Spin the Wheel for bonus points.
    • Spend $50 on P&G products and win up to 5,000 points.

    For details about what is and isn't supported, see Supported use cases that reward gameplay and Non-supported use cases for gameplay.

  2. To create a promotion that rewards gameplay, navigate to Promotions > Offers > Business Unit (if applicable).

  3. Click the + Offer button to create a new offer.

  4. Populate the desired Offer Details and other fields.

  5. In the Details section, under Required Behaviors 1, select an option from the dropdown. This reveals the next section you need to complete.

  6. Scroll down to the Rewards section.

  7. Under What currency will be rewarded, select Gameplay.

  8. Under the Game label, the published managed game types are available to assign as a reward to a promotion.

  9. Some marketers may want to serve gameplay only to members who have consented to game rules. The consent-for-game-rules value must be added as an EMD attribute and made targetable. When creating a promotion that rewards gameplay and targeting by audience, ensure that one of the targeting condition criteria is the EMD game consent attribute.

  10. When the rest of the offer is configured, click Save and Publish.

7. Send gameplay URLs to members​

Members who complete the required behavior receive a gameplay URL through one of the following methods:

  1. Gameplay email: A triggered email containing the gameplay URL is sent to the member as soon as they complete the required behavior. This is currently supported for clients who use Optimove as their Email Service Provider.

  2. From the web app: Web developers can retrieve gameplay URLs for ACTIVE promotions earned by a member using the following Exchange Solutions CUX endpoint:

    client/users/:correlationId/gameplays

8. Configure daily games (optional)​

Daily games don't require promotions. Members can play a game and earn points that are added directly to their loyalty account balance.

To support daily games:

  1. Instead of creating a dynamic token, create a game with a public URL.
  2. If the member already exists, they proceed immediately to playing the game. After playing, the member can earn points that are reflected in their loyalty account.
  3. If the customer is not yet registered as a member, provide a registration form. Each user is directed to enroll on the client's registration page. After enrolling, the user is served the public URL within the client's member program site.
  4. Members click the link and self-identify using either their loyalty ID or email to advance to the game and earn points.

Best practices for gamification integration​

  1. Create one game mechanic per loyalty promotion so that a gameplay is provided as a reward when the required unit or spend behavior is met in a single transaction.
  2. If a marketer wants to reuse a game mechanic, they should do so only after all loyalty promotions that reward that gameplay have been completed.

Supported use cases that reward gameplay​

  1. Purchase X liters of fuel in a single transaction and receive gameplay as a reward.
  2. Single-behavior offers that result in gameplay being awarded:
    • One offer: Purchase $10 of fuel at the pump and receive a gameplay.
    • A separate offer: Purchase $20 in the C-Store and receive a gameplay.
  3. Perform a redemption (POS-based redemption transactions only) and receive gameplay as a reward.

Non-supported use cases for gameplay​

The following use cases do not currently support the awarding of gameplay:

  1. Non-purchase behavior.
  2. Performing an activity (for example, filling in a survey) in a single transaction.
  3. Frequency offers.
  4. Multi-behavior offers; for example, purchase $10 of fuel at the pump and purchase $20 in the C-Store.
tip

Need additional resources? Supporting documentation for this integration is available through your TSA. Reach out to them if you need reference materials beyond what's covered here.

Last updated on