Client side integration

Introduction

Client side integration is divided into three types:

• Desktop browser integration is done by embedding a client application into an iFrame. In this case, it is necessary to pass a number of parameters in the URL (query params) for correct operation.

• Mobile browser integration is done by straight redirect to a client app with passing of needed parameters in URL (query params) for correct operation. To avoid showing the provider domain in the browser address bar, configure a CNAME (DNS record that maps a brand domain alias to the canonical provider domain). In case of any difficulties with this type of integration it is possible to use iFrame integration just like with desktop browser. With the iFrame integration it is necessary to meet the embedding recommendations

• Native mobile apps integration (Android, iOS) is done by embedding a client application into a WebView. In this case, it is necessary to pass a number of parameters in the URL (query params) for correct operation.

info

URL of a client app needs to be requested from provider.

URL example

Legacy Method

The URL building method described below is legacy and is supported for backward compatibility.

It is recommended to use the new method /game/url from the Backend API to generate URLs with specified parameters.

URL template should match the form:

https://<game_provider_base_url>?<query_parameters>

where:

• game_provider_base_url - basic URL address needed for launch

• query_parameters - request parameters of the format query string, needed for launching the specific product

Parameter	Description	Type	Requirements	Explanation
cid	unique brand identifier	string	mandatory	identifier can be the same for all environments within the brand
productId	brand game identifier	string	mandatory	current identifiers: nft-aviatrix, second-chance, aviatrix-fruits
sessionToken	token with user session	string	optional	token must be generated by the brand for further requests from server part of provider. Expected length: 1-255 runes. Not required for demo mode
lang	language code	string	optional	format code ISO 639-1. Default value is en
lobbyUrl	lobby url	string	optional	needed for redirects to brand homepage
isDemo	isDemo= value true or false	string	optional	needed to enable the demo mode of the game. Required parameter for demo mode
code	promocode	string	optional	needed for direct opening of the promo code entry form. If a value is passed (code=promocode1&…), a modal window will open, and the input will be filled. If the parameter is empty (code=&…), the entry form will open with an empty input value.
hideExitButton	hideExitButton= value true or false	string	optional	controls the visibility of the menu exit button, overriding its display if enabled in the config

Example of the URL for standard game launch:

https://domain.com?cid=somebrand&productId=nft-aviatrix&sessionToken=abcd1234&lang=en&lobbyUrl=https://somebrand.com

Example of the URL for demo mode game launch:

https://domain.com?cid=somebrand&productId=nft-aviatrix&isDemo=true

Example of the URL for direct opening of the promo code entry form:

https://domain.com?cid=someplatform&productId=nft-aviatrix&code=promocode1

info

If parameter productId will receive nft-aviatrix (or ID of any other game) value - the needed game will be launched.

Embedding recommendations

Desktop web version (iFrame)

Styles (css rules)

During client app embedding in iFrame it is needed to

• add to iframe tag

  • scrolling="no"
  • frameborder="0"
  • allow=“autoplay; clipboard-write; fullscreen”

• write "reset" styles on the element:

margin: 0;
padding: 0;
border: 0;
font-size: 100%;
font: inherit;
vertical-align: baseline;

We recommend to set the height and width of iFrame:

// full width
min-width: 100vw;
width: 100vw;

// height without the top menu of the parent window (host-header-height - menu height)
height: calc(100vh - var(--host-header-height));

iFrame communication (postMessage)

After successfully loading the page inside an iframe, the provider can communicate with the brand using postMessage messages.

Provider -> Brand

On the provider side, there is a mechanism for sending postMessage to the parent window (the brand). To handle these messages on the brand side, you need to subscribe to the message event.

The structure of the message data:

• action - (string) - the name of the action
• payload - (string) - the payload of the message

Available actions (action):

• appReady - signals the completion of the splash screen display and the full initialization of the game.
• game.location (deprecated) — an event that signals the user has clicked the exit button in the game, with the mandatory parameter lobbyUrl. It’s expected that the brand will capture this event and perform the necessary redirect.
• game.redirect - an event that signals a user's transition to another game. The event payload contains a gameId property with the game identifier. The brand is expected to handle this event and perform the redirect.
• game.exit — an event that signals the user has clicked the exit button in the game. It’s expected that the brand will capture this event and perform the necessary redirect.

Example:

// https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage#the_dispatched_event
window.addEventListener('message', ({ data: messageData }) => {
  const { action, payload } = messageData || {};

  if (action === 'game.exit') {
    // Some logic...
  }
});

Brand -> Provider

On the provider side, there is a mechanism for receiving postMessage from the brand.

The structure of the message data:

• action - (string) - the name of the action

Available actions (action):

• updateBalance - perform a balance update in the provider's iframe

Usage example:

document.querySelector('iframe').contentWindow.postMessage({ 
	action: 'updateBalance', 
}, '*')

querySelector

In case there can be multiple iframes on the brand page, you can use the unique attribute id="aviatrix" to select the provider's iframe, which needs to be specified in the iframe tag.

After that, the selector can look like this:

 document.querySelector('iframe[id="aviatrix"]')

Mobile web version (direct)

With this recommended type of mobile web integration brand doesn't need to care about the style features of embedding. This task is undertaken by the provider.

Mobile web version (iFrame)

When integrating into mobile devices via an iFrame, it is recommended to use the full height of the screen, removing the header, footer and other navigation elements, if any. Thus, the game interface will occupy the entire available area of the screen, providing the user with maximum immersion, as well as improving the interaction process.