Enable Unibo for your Platform

Last update ﻿ 
﻿
Table of contents
👋 Introduction
🔗 Integration Process
📆  The kickoff
📆  The check-in
📆 The takeoff checklist
🤖 Four Key Deliverables
✅ Meta Data
✅ Event Feed
✅ Game Companion / Overlay
✅ Rewards API
📚 Additional resources
﻿
﻿﻿ Introduction This document aims to provide all required information to understand the requirements and the steps of the Unibo Gamification Product setup.
﻿
The setup consists of making sure that the four channels of communication between your platform and the Unibo Product are integrated and functioning. Those are:
Title
Title
Communication Channel
What is it?
Meta Data
Usually just players and games data. Both are required to setup campaigns.
Event Feed
Contains real time game events, such as bet, wins and deposits. Required to enable campaign progression.
Rewards
An API that receives payout requests. In required to let your Unibo Instance send rewards to players that have successfully completed all defined requirements in a campaign.
Game Companion / Overlay
The campaign tracker to the left of your game. Required in order to let the players understand their progress.
In addition to enabling these four channels of platform communication, we will also help you configure Unibo and support you in setting up your first few campaigns. After that, you'll be well on your way on the increased player engagement journey.
﻿
﻿﻿ Integration ProcessWe like to keep our integration process simple and adaptable to your platform. We start with a kickoff and end with a takeoff checklist before enabling Unibo for all your players. In between we'll have regular check-ins to see where we are and remove any impediments to a successful Unibo launch.
﻿
﻿﻿  The kickoffAfter our commercial agreement, we will meet up to hold an Enablement Kickoff meeting. At that meeting we'll go through answering the following questions:
﻿
.1What are the gaps between currently available APIs and/or Data Feeds and Unibo's needs?
.2Which changes do we need to make in order to establish the four channels?
.3Who is responsible for what?
.4When will we hold check-ins? I.e. how often do we meet to review progress?
 
﻿﻿  The check-inMost of the enabling work is done by the Unibo team. However, if we discover changes in APIs or Data Feeds during the kickoff those might have to be (re)-implemented by the platform. We'll meet on a regular cadence to check on progress until we're ready.
﻿
﻿﻿ The takeoff checklistWhen the four channels have been implemented, and the data has been verified, the Unibo team will go through a final "Takeoff Checklist". We do this to ensure that the whole product is working as expected before running the first few campaigns.
﻿
﻿
﻿﻿ Four Key Deliverables﻿﻿ Meta DataFor most use cases, we'll only need game and player data. This information is primarily used to set up your Unibo campaigns. We'll need two different data sets per data type. We need an initial seed of all information and then updates on a regular basis, preferably in real time. If you have a larger player base (millions of players), our recommendation is that you restrict the initial data set to only active players and/or send all of them to us as a CSV-file close to launch. If you have less than millions of players, Unibo prefers an API endpoint where all new players from a certain point in time can be fetched. The default is to query that endpoint every minute.
﻿
Unibo is GDPR-compliant and will not store any PIIs (Personal Identifiable Information) such as name or email addresses. All the information we store is strictly used for player segmentation.
﻿
Sample Player Data for Segmentation
Title
Title
Title
Field (* = mandatory)
Data Type
Additional info
playerId *
String
Unique identifying value
currencies *
String[]
ISO-4217 currency code
country *
String
2 letter ISO 3166-1 country code
registrationDate *
String
ISO-8601
gender *
String
"M" = Male
"F" = Female
"O" = Other
status *
String
Any of "ACTIVE", "BLOCKED", "FROZEN" or "INACTIVE"
affiliateName 
String
playerTags 
String[]
Sample Games Data for Segmentation
Title
Title
Title
Field (* = mandatory)
Data Type
Additional Info
gameId 
String
Example: "4399 or btg/bonanza"
gameName 
String
Example: "Bonanza"
gameProvider 
String
Example: "Big Time Gaming"
gameCategory 
String
Example: "table-games"
gameSubCategory 
String
Example: "blackjack"
The above can be adjusted depending on your use case and will be discussed during the kickoff meeting.
﻿
﻿﻿ Event FeedThe typical platform pushes events to the Unibo Consumer, in JSON format. The key events are bets, wins, withdrawals and deposits. The bets and wins are referenced to as game rounds even if the bets and wins will be separated over time. Below is a schema example from the  Unibo Consumer API documentation (link). ﻿
﻿
It's important that the timestamp is set to when the game round was finished, not when the message was sent. The reason for this is to allow us to understand the end-to-end player experience.
Unibo handles events in an idempotent manner using the unique_id. This means that you can re-send events without risking  duplication.
{
  "items": [
    {
      "event": "gameround",
      "data": {
        "unique_id": "9cd823d3fe",
        "timestamp": "2022-11-28T16:24:14.050Z",
        "player_id": "StQ-1",
        "game_id": "GD8",
        "round_id": "f7ltidMBAwexDojlJBY",
        "amount": 0.5,
        "currency": "EUR",
        "is_win": false,
        "is_bonus": false
      }
    },
    {
      "event": "deposit",
      "data": {
        "unique_id": "9cd823d3fe",
        "timestamp": "2022-11-28T16:24:14.050Z",
        "player_id": "StQ-1",
        "amount": 100,
        "currency": "EUR",
        "method": "Credit Card"
      }
    },
    {
      "event": "withdraw",
      "data": {
        "unique_id": "9cd823d3fe",
        "timestamp": "2022-11-28T16:24:14.050Z",
        "player_id": "StQ-1",
        "amount": 100,
        "currency": "EUR",
        "method": "Bank Transfer"
      }
    }
  ]
}
﻿
﻿﻿ Game Companion / OverlayOnce the metadata is in place and the events are streaming to Unibo players can make progress on the campaigns the campaign manager has set up. In order for the players to view their progress on the site, the Unibo Game Companion / Overlay needs to be added to the game page. This is done in four steps:
﻿
.1Game Companion / Overlay theme should match the look and feel of the brand. A new theme is created by configuring the colors in the Overlay2 Setting Page in the Back Office by the campaign manager
.2A Javascript file, the overlay/companion, is added to the site and configured
.3The platform sets four cookies as described in the settings table below
﻿
During the QA process, please make sure that you also test what happens when the script responds with 404 or a similar error code. The website should still work as normal, just Unibo not loading.
﻿
Cookie settings
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_display_currency
Used to display overlay in specific currency if player can have more than one﻿﻿﻿Example: "EUR"
Game Companion / Overlay Settings
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’] ; 
Methods
init()
Append overlay widget to id set in Unibo settings, running WebSocket connection with game data
unmount()
Kill the WebSocket connection and unmount Unibo overlay widget
When working with the Overlay instance, it is crucial to call the unmount() function to ensure proper resource management and prevent potential memory leaks. 
﻿
Purpose of the unmount() function
- Terminate WebSocket connection.
- Unmount Unibo Overlay instance.
﻿
Importance of calling unmount() function
Failure to call unmount() may lead to resource leaks, such as unclosed WebSocket connections and leftover widget elements, which can degrade application performance and stability over time. Always ensure that unmount() is invoked when the Overlay instance is no longer needed or before navigating away from the current view.
﻿
When to call unmount() function?
- Make this a part of your cleanup process to maintain optimal performance and resource management in your application.
- Always call unmount function when closing a game.
- Always call unmount function when switching between games.
Overlay will not show up when there's no active campaigns for player/game combination configured in backoffice. ﻿The websockets connection to *.unibo.io should be active though.
Sample Game Companion / Overlay Configuration
<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
  uniboOverlay.init();
</script>
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>
﻿
Recommendation to set up the style for the Game Companion / Overlay
To ensure that the Game Companion / 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. 
﻿
﻿﻿ ⁠⁠Overlay Implementation - Best Practices⁠ ﻿
﻿﻿ Rewards APIUnibo requires an endpoint where various types of payouts can be made in order to reward the player. In order to enable all current campaign types we need the following payout types.
Title
Title
Prize type
Description
Cash
We must be able to add a specified amount of cash to the player’s account balance. These funds must NOT have a wagering requirement.
Bonus Money
 We must be able to add a specified amount of cash to the player’s bonus balance.
Deposit Bonus
We must be able to activate the deposit bonus for a given player.
Free Spins
We must be able to add a specified amount of free spins to the player that might be used in a given game or games.
You can check some ﻿ 🎁⁠⁠Rewards API examples⁠ .
﻿
We'll go through, alternatively plan, the Reward API on our kickoff.
﻿
﻿﻿ Additional resourcesDetailed API documentation for the Casino and Payment events are available at: 
﻿
﻿ Unibo Consumer API documentation ﻿
﻿﻿ ⁠⁠Overlay Implementation - Best Practices⁠ ﻿
﻿
Last updated on ﻿ by ﻿AdAdam Pajkert.
﻿
Enable Unibo for your Platform

﻿﻿ Introduction

﻿﻿ Integration Process

﻿﻿ The kickoff

﻿﻿ The check-in

﻿﻿ The takeoff checklist

﻿﻿ Four Key Deliverables

﻿﻿ Meta Data

﻿﻿ Event Feed

﻿﻿ Game Companion / Overlay

﻿﻿ Rewards API

﻿﻿ Additional resources

Introduction

Integration Process

The kickoff

The check-in

The takeoff checklist

Four Key Deliverables

Meta Data

Event Feed

Game Companion / Overlay

Rewards API

Additional resources
