In-Game Overlay

Introduction

The in-game overlay is a frontend component provided by Unibo that is rendered alongside the game. It displays active campaigns, player progress, and rewards in real time while the player is in a game session.
The in-game overlay is loaded and controlled by the platform and communicates directly with Unibo services. It does not replace or modify the game itself and does not interact with game provider logic.


Prerequisites

Required identifiers

The overlay requires a valid player and game context. This context is primarily resolved via platform-set cookies.
The values used by the in-game overlay must match the identifiers used in the Event Stream and Metadata integrations.


Cookies

The in-game overlay relies on platform-set cookies to resolve player and game context. Cookie names and formats are part of the integration contract and must be implemented exactly as specified below.

Required cookies

  • unibo_player_id - Platform-generated player identifier.
  • unibo_game_id - Identifier of the currently played game.
  • unibo_language - Language code used by the in-game overlay (ISO 639-1, e.g. en, fi, de).
  • unibo_registration_date - Date of the current player’s registration, provided as a Unix timestamp in seconds.If the value includes decimals, the decimal part must be stripped (no rounding).Example: 1652442998.905513 → 1652442998

Conditional cookies

  • unibo_currency - Required only for platforms with a multi-currency setup where a player can have more than one account currency.

Important cookie rules

  • Cookies must be set on a domain accessible to the overlay.
  • If the game is served over HTTP, cookies must not include the Secure flag.
  • Incorrect cookie configuration is one of the most common causes of overlay initialization failures.

Cookie timing requirement

All required cookies must be set before initializing the overlay.


In-Game Overlay placement (DOM contract)

The in-game overlay is rendered alongside the game, not inside the game canvas.

Required DOM element

A container element with the id unibo-overlay must exist in the DOM before the overlay is initialized.
Example structure:
<div id="unibo-overlay">
  <iframe id="game"></iframe>
</div>


Initialization

Load the script

<script src="https://overlay.unibo.io/overlay.js"></script>

Loading this script makes a global uniboOverlay object available on the page.


Initialize the overlay

The overlay is initialized by calling uniboOverlay.init().
const initConfig = { expand: true };
uniboOverlay.init(initConfig);
Player and game context is resolved from cookies.Initialization configuration controls overlay behavior only.

Configuration options

expand (optional)Boolean that defines whether the overlay should be expanded or collapsed initially.Default value is true.


Lifecycle management

The overlay lifecycle is controlled by the platform and follows three strict rules:
  • The overlay must be initialized when a game session starts
  • The overlay must be unmounted when the game session ends
  • A new overlay instance must be created for each game launch

Unmounting the overlay

Failing to call unmount() when the game session ends can result in multiple overlay instances and undefined behavior.
Unmounting must occur when:
  • The player exits the game
  • The game container is destroyed
  • The player navigates away from the game view
uniboOverlay.unmount();


Device behavior (implementation expectations)

This section describes expected behavior to support correct integration and QA validation.

Desktop (expected behavior)

  • The game remains visible while the overlay is rendered alongside it
  • When the overlay expands, the game may be pushed slightly to the side
  • The game and overlay should remain visible without requiring page scroll
  • The overlay and game should maintain equal height

Mobile (expected behavior)

  • The overlay supports both portrait and landscape orientations
  • Language changes on the site should be reflected in the overlay
  • Reloading the page should reload the overlay
Portrait:
  • The overlay may partially overlay the game when expanded
  • The overlay should not push the game downward when collapsed
Landscape:
  • Expanding the overlay may make the game window slightly tighter
If actual behavior differs from the above, treat this as a QA mismatch and confirm with Unibo rather than adjusting based on assumptions.


Error handling and resilience

During QA, test scenarios where the overlay script fails to load (e.g. 404 or network failure).
In these cases:
  • The website and game must remain fully functional
  • No blocking errors should be thrown
  • The overlay will simply not render


Styling and visual reference

Styling and visual customization are handled separately from the technical integration.
The in-game overlay is styled to match the operator’s brand guidelines and is typically configured during the integration process. Visual examples and layout references are provided in separate  styling documentation .