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>

2. 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.

3. 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 available methods

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.

This method is also helpful when you need to update the player locale.

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.

This method is also helpful when you need to update the player locale.

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>

destroy 🆕

Allows you to destroy/clean all the information related to the widgets saved in the redux toolkit, local storage, socket instance, and remove the GamificationWidgets function.

Important This function was thought to use when the player logs out the casino.

Example

<script>
    GamanzaEngageClient.getInstance(function(GamificationWidgets) {
        if(GamificationWidgets)
            GamificationWidgets.destroyWidgets();
        }
    })
</script>

---

version: 1

The initial version of the Gamanza Engage Widget Client library is now deprecated.

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.