Skip to main content

Frontend Integration

version: 2

The widgets are snippets of code that can be used to display certain information from the player. Some specific configurations are needed to get the code that would be responsible for displaying the data.

To use the widgets there are a few steps that must be followed:

  1. A script must be added to obtain the minified code for the widgets, like this:
<script src="https://{cdn-region}.gamanzaengage.com/casino-ui-widgets-v2/bundle.v2.min.js"></script>
  1. Once the bundle is loaded, the widgets must be initialized with a configuration object.
<script>
  const config = {...} // This will be explained on the next page

  GamanzaEngageClient.init(config, function(GamificationWidgets){})
</script>

The init function requires a callback as its second argument. This callback function is invoked once the client library is ready, serving as a safe entry point for using the UI Widgets. The callback receives the GamificationWidgets as its parameter, which provides access to various functions documented in the GamificationWidgets interface API.

To retrieve the instance of the GamificationWidgets you can use the GamanzaEngageClient.getInstance function as follows:

GamanzaEngageClient.getInstance(function (GamificationWidgets) {
  if (GamificationWidgets) GamificationWidgets.reloadOne('...');
  else {
    // Fallback, if the GamanzaEngageClient is not initialized proceed to call the GamanzaEngageClient.init function.
  }
});

Please notice that the getInstance function requires a callback to provide the GamificationWidgets instance. If the widgets are not initialized, the GamificationWidgets will be null.

  1. For each widget to appear, you must add a div with a specific class and data-type.

You must specify some properties to display each respective widget properly.

Examples:

<div class="gamification_widget" data-type="avatar"></div>
<div class="gamification_widget" data-type="reward-shop"></div>

GamanzaEngageClient and GamificationWidgets API Interfaces​

GamanzaEngageClient​

Once you properly load the Gamanza Engage client library script into your website, a global object called GamanzaEngageClient is created in your website runtime, this object exposes the following functions:

- init(config: Object, callback: (GamificationWidgets) => void)​

Initialize the Gamanza Engage Client library, see Configuration for more details.

Once the client library is initialized, the callback function is called passing the instance of the GamificationWidgets client library.

- getInstance(callback: (GamificationWidgets) => void)​

You must use this function to safely retrieve the instance of the Gamanza Engage Client library to interact with the widgets. If for some reason the client library is not properly initialized, the GamificationWidgets is passed as null.

GamificationWidgets​

By using the GamanzaEngageClient.getInstance you can retrieve the instance of the Gamanza Engage Client library. This instance contains the following methods:

reload​

const reload: (newLocale?: string) => void

Allows loading multiple widgets that were not loaded, usually when you are using async content loading or single page web applications that load new nodes into your webpage and require to render widgets on those new DOM nodes.

Important This function force reloads all the visible widgets.

Example:

<script>
    GamanzaEngageClient.getInstance(function(GamificationWidgets){
        if(GamificationWidgets)
            GamificationWidgets.reload();
        else {
            // Fallback, if the GamanzaEngageClient is not initialized proceed to call the GamanzaEngageClient.init function.
        }
    })
</script>

reloadOne​

const reloadOne: (widgetId: string, newLocale?: string) => void

Allows loading one widget by id. This must be an id added to the gamification_widget element.

Example:

<script>
    GamanzaEngageClient.getInstance(function(GamificationWidgets) {
        if(GamificationWidgets)
            GamificationWidgets.reloadOne('my-widget-id');
        else {
            // Fallback, if the GamanzaEngageClient is not initialized proceed to call the GamanzaEngageClient.init function.
        }
    })
</script>

...


<div class="gamification_widget" data-type="avatar" id="my-widget-id"></div>

getPlayer 🆕​

const getPlayer = (callback: (data: any | null) => void) => {
  if (callback && typeof callback === 'function') {
    callback(playerData);
  }
};

Allows you to get basic player information, such as gamification opt-in status. You have to pass a callback to the function, in order to obtain the player data and do something with it (we recommend saving it in your own state)

We added a custom event called GamanzaEngage_Client_Initialized that will run once the call to the player information api has finished. You can implement it like so, when the widgets are first initialized, to make sure the call to our api has already returned the necessary info.

<script>
    getPlayerFunction(function(data) {
        // Store the player data received
    })

    document.addEventListener('GamanzaEngage_Client_Initialized', (event) => {
      const { detail } = event as CustomEvent
      detail.getPlayer(getPlayer)
    })
</script>

And you can use it like this, once the widgets have been initialized:

<script>
    getPlayerFunction(function(data) {
        // Store the player data received
    })

    GamanzaEngageClient.getInstance(function(GamificationWidgets) {

        if(GamificationWidgets)
            GamificationWidgets.getPlayer(getPlayerFunction);
        else {
            // Fallback, if the GamanzaEngageClient is not initialized proceed to call the GamanzaEngageClient.init function.
        }
    })
</script>

Migrate from Widgets V1 to V2​

The initial version of the Gamanza Engage Widget Client library utilized a global GamificationWidgets object. This implementation has been deprecated by Version 2.

Changes​

  • New Scripts Loader
  • Module Federation
  • Code Splitting
  • Improve scripts load time

Version 1 Deprecation Window and support​

While Version 1 of the Widgets continues to receive maintenance updates, it has entered its deprecation phase. To ensure uninterrupted service and access to the latest features, all clients are required to migrate to Version 2. The deprecation timeline is as follows:

  • 🛠️ Maintenance Support: Continues through April 30th, 2025
  • ⚠️ End-of-Life Date: June 30th, 2025

After the end-of-life date, Version 1 will be permanently decommissioned and will no longer be accessible. We strongly recommend completing the migration well in advance of these dates to prevent any service disruptions.

Migration Steps​

1. Update the CDN Script tags​

Change the script tag for the CDN resource to load the new version

  • From: https://{cdn-region}.gamanzaengage.com/casino-ui-widgets/bundle.min.js
  • To: https://{cdn-region}.gamanzaengage.com/casino-ui-widgets-v2/bundle.v2.min.js

2. Client library Initialization​

Update the Client library initialization by using the GamanzaEngageClient.init instead of GamificationWidgets.config

3. Replace the GamificationWidgets usage​

Replace the usage of the direct GamificationWidgets global object to use the GamanzaEngageClient.getInstance and validate that the callback function in the GamanzaEngageClient.getInstance argument is not null. If the argument is null, it means that the Gamanza Engage Client library is not properly initialized and you have to properly manage the initialization flow.

info

If you have any questions please don't hesitate to contact your Customer Success Representative, or reach out for help in one of our support channels.