Overlay

Introduction

Once the metadata is configured and events are successfully streaming to Unibo, players can begin making progress on the campaigns set up by the campaign manager. For players to view their campaign progress directly on the site, the Unibo Overlay must be added to the game page. This process involves the following three steps:
    Set CookiesThe platform must set four mandatory cookies (optionally five) to ensure proper functionality.
    Import and Configure the JavaScript FileImport the designated JavaScript file into the site and ensure correct configuration. This includes both the initialization process and the accurate placement of the overlay within the game page.
    Customize the Overlay ThemeThe overlay’s theme should align with the brand’s look and feel. A custom theme can be created by configuring colors in the Overlay Settings Page within the Back Office, as managed by the campaign manager.

Quality Assurance Considerations

During the QA process, it is essential to test scenarios where the script responds with a 404 error or similar failure codes. The website should remain functional, with the only impact being the absence of the Unibo overlay. This ensures a seamless user experience even in cases where the overlay fails to load.
The Unibo Overlay will not appear if there are no active campaigns configured for the specific player and game combination in the Back Office. However, the WebSocket connection to *.unibo.io should remain active under these circumstances.

Video Game Overlay Implementation Steps:

Check Box with Check Setup cookies:

Cookies should be readable by the overlay script. Make sure the cookie does not have  Secure flag .
Title
Title
Title
Use case
Name
Description
Authentication
unibo_registrationDate
Date of current user's registration, provided as Unix Timestamp in seconds, without the value after the decimal point. If you have the values after decimal point, they need to be stripped (no rounding), for example: 1652442998.905513 will become 1652442998.

Example: "1652442998"
Authentication
unibo_userId
The playerId from the Meta Data and Event feed.

Example: "StQ-1"
Campaign display
unibo_language
Two letters code of language according to ISO 639-1
standard

Example: "en"
Campaign display
unibo_gameId
The gameId from the Meta Data and Event feed.

Example: "btg/bonanza"
Players with multiple currencies(optional)
unibo_displayCurrency
Used to display overlay in specific currency if player can have more than oneExample: "EUR"

Check Box with Check Define Unibo settings and create a global constructor:

Title
Title
Setting
Description
allowedUsers (optional)
An array of numbers or strings, to display only restricted players. If empty or not set, the overlay will be displayed for all users.

Example: ['StQ-1', 111, ’232322’, ‘abc123xyz’] ; 
const uniboSettings = {
  allowedUsers: [],
};

const uniboOverlay = new UniboOverlay(uniboSettings);

Check Box with Check Initialize the Overlay on your page:

Title
Title
Setting
Description
expand (optional)
Boolean value which defines if overlay should be automatically expanded or collapsed. The default value is true .

Example: false ;

const initConfig = {
  expand: true 
}
uniboOverlay.init(initConfig);

Check Box with Check Remember to unmount the Overlay:

Proper Use of the unmount() Function for Overlay Instances

When working with the Overlay instance, it is essential to call the unmount() function to ensure efficient resource management and prevent potential memory leaks.

Purpose of the function

The unmount() function serves the following purposes:
  • Terminate the WebSocket connection: Ensures that all network communications are properly closed.
  • Dismount the Unibo Overlay instance: Safely removes the widget and associated resources from the application.

Importance of Calling the function

Neglecting to call the unmount() function can result in resource leaks, including unclosed WebSocket connections and residual widget elements. Over time, this can negatively impact the performance and stability of your application. To maintain a robust application, always invoke the unmount() function when the Overlay instance is no longer required or before navigating away from the current view.

When to call the function

To maintain optimal application performance and effective resource management, include the unmount() function as part of your cleanup processes in the following scenarios:
  • When closing a game: Ensures proper disposal of resources associated with the game.
  • When switching between games: Prevents residual artifacts and resource conflicts when transitioning contexts.
By adhering to these practices, you can safeguard your application against performance degradation and ensure long-term stability.
Usage:
uniboOverlay.unmount();

Check Box with Check Put the Unibo widget in the right place:

The example wrapper below can't have any applied CSS styles to it
<!-- This container should be a parent of your game container -->
<div id="unibo-overlay">
  <!-- This iframe is just an example, it should be your game container -->
  <iframe id="game">...</iframe>
</div>

Check Box with Check Set up the style for the Overlay

To ensure that the Overlay is fully displayed in portrait mode without obstructing the game, we recommend that you set up one of the following styles:
  • Set the height of the div with the ID unibo-iframe-container-mobile that contains the game to 100%.
  • Set the height of the div with the ID unibo-iframe-container-mobile that contains the game to the window.innerHeight minus 90px.
In addition to the setup above we've put together a guide with which we encourage you to read through.

Good practices

  • In order to have the game and overlay centered, the game container should have a width and height set statically (for example by javaScript on window resize). The container that wraps the game should have centered content, without any CSS applied by the casino, it will be justify-content: center;
  • Ensure that the overlay is properly integrated by following one of these methods:
  • Integration of the overlay into an HTML file.
  • If the overlay is integrated into a JS file instead of an HTML file, confirm that the overlay is initialized only once.

Acceptance criteria on desktop:

  • The game is centered but then gets slightly pushed to the side when the overlay expands.
  • There is some padding on each side even when the Overlay is opened
  • There is some padding in the bottom as well, both overlay and game are clearly visible without a scroll
  • The height of the Overlay and the game should be the same
  • When resizing the screen, it should follow the same padding rules and keep the same height as the overlay
  • When reloading the page, the overlay should load again
  • When switching to another language on the site, the language for the overlay should switch as well.

Acceptance criteria on mobile

Portrait & Landscape:
  • When reloading the page, the overlay should load again
  • When switching to another language on the site, the language for the overlay should switch as well.
Portrait:
  • There is no empty space anywhere, only the game and the overlay.
  • The game resizes properly once the overlay has been loaded, the overlay should never push down the bottom part of the game when the Overlay is closed
  • When the Overlay is opened, the mini Overlay should be on the top of the game and the Overlay compact should be will display a portion on top, overlaying the game.
Landscape:
  • When the overlay opens it should make the game window slightly tighter (as per the video)

Check Box with Check Event messages handling:

We have implemented a system to notify about any changes to the overlay view by sending relevant events. These notifications are categorized into four types:
  • show (Overlay is visible to the player)
  • hide (Overlay is completely invisible to the player)
  • expand (Overlay is expanded to the player)
  • collapse (Overlay is collapsed to the player)

Below is an example of how this can be implemented on your end:
window.addEventListener('message', (event) => {
  if (event.data?.source === 'unibo') {
    console.log('Received Unibo event:', event);
    switch (event.data.type) {
      case 'collapse':
        console.log('Overlay is collapsed');
        break;
      case 'expand':
        console.log('Overlay is expanded');
        break;
      case 'show':
        console.log('Overlay is shown');
        break;
      case 'hide':
        console.log('Overlay is hidden');
        break;
      default:
        console.warn('Unknown message type:', event.data.type);
    }
  }
});

Some useful methods:

We have introduced several methods designed to enhance user experience and provide the platform with greater control over overlay behavior:
  • collapse() 
uniboOverlay.collapse();
  • expand()
uniboOverlay.expand();


Confetti Ball Summary

The final result should look like this:

JavaScript

<script src="INSERT SCRIPT URL"></script>

<script>
  // Unibo settings object
  const uniboSettings = {
    allowedUsers: [],
  };

  // UniboOverlay is global constructor in window object
  const uniboOverlay = new UniboOverlay(uniboSettings);

  // Method to run overlay in game page along with configuration
  const initConfig = {
    expand: true
  }
  uniboOverlay.init(initConfig);
  
  // Optional methods to handle custom behaviour
  uniboOverlay.collapse();
  uniboOverlay.expand();
  
  // Optionally react to coming events
  window.addEventListener('message', (event) => {
    if (event.data?.source === 'unibo') {
      ...
    }
  }
  
  // When player closed the game
  uniboOverlay.unmount();
</script>

HTML

<!-- This container should be a parent of your game container -->
<div id="unibo-overlay">
  <!-- This iframe is just an example, it should be your game container -->
  <iframe id="game">...</iframe>
</div>

FAQ

Q: Can the Unibo overlay only be constructed if the html element (<div id=“unibo-overlay”>) exist in the DOM?A: Yes.
Q: Does the overlay have a listener on cookie changes? For example, if we change games while staying on the game page, can the same instance be reused?A: No, you need to unmount() and initialize a new instance of the overlay when the player changes the current game page.
Q: If the overlay can be reused, do we need to call init again if the gameID changes?A: Yes.
Q: What exactly does unmount do? Can the same instance be initialized again after being unmounted?A: unmount should be part of your cleanup process to maintain optimal performance and resource management. It terminates the WebSocket connection and unmounts the Unibo Overlay instance.
Q: If the overlay cannot be reused, does this mean we need to create a new overlay for every game launch?A: Yes.
Q: What’s the best way to determine if the Unibo sidebar is in an open or closed state? Are there any events for this?A: Yes, there are events for this: collapse and expand.
Q: Regarding cookies, do they need to be set before calling init?A: Yes.
Q: Is there a method that allows us to control the overlay behavior ourselves, such as collapsing or expanding?A: Yes, there are methods like collapse() and expand().
Q: Should the cookies be on our domain?A: Yes, they should be on your domain. Also, ensure the cookies do not have the Secure flag.
Q: Are Unibo settings, like the widget ID, something we can change from the back office, or is it part of a configuration we send?A: We control this. We set it up and then provide you with the required variables.
Q: Is the default id unibo-overlay?A: Yes.
Q: Is it possible to decide whether the overlay is open or closed when we run init()?A: Yes, there is a configuration option called expand. Here is an example usage:
uniboOverlay.init({ expand: false });