Перейти к основному содержимому

Интеграция клиентской части

Введение​

Интеграция клиентской части делится на три вида:

  • Интеграция для десктопных браузеров происходит через вставку клиентского приложения в iFrame. При этом необходимо передать ряд параметров в URL (query params) для корректной работы.

  • Интеграция для мобильных браузеров происходит через прямой редирект на клиентское приложение с передачей необходимых параметров в URL (query params) для корректной работы. При этом, чтобы у пользователя не возникли вопросы к виду URL в адресной строке браузера, необходимо "закрыть" доменное имя провайдера на доменное имя бренда с помощью DNS записи - CNAME. При возникновении трудностей с данным типом интеграции - можно прибегнуть к интеграции через iFrame, как в случае интеграции для десктопных браузеров. Однако необходимо соблюсти рекомендации по встраиванию

  • Интеграция для нативных мобильных приложений (android, ios) происходит через вставку клиентского приложения в Webview. При этом необходимо передать ряд параметров в URL (query params) для корректной работы.

к сведению

URL клиентского приложения необходимо получить у провайдера.

Пример URL​

Устаревший способ

Описанный ниже способ сборки URL является legacy и поддерживается для обратной совместимости.

Рекомендуется использовать новый метод /game/url из Backend API для генерации URL с заданными параметрами.

Шаблон URL должен соответствовать форме:

https://<game_provider_base_url>?<query_parameters>

где:

  • game_provider_base_url - базовый URL адрес, необходимый для запуска

  • query_parameters - параметры запроса формата query string, необходимые для запуска конкретного продукта

ПараметрОписаниеТипТребованияПояснение
cidуникальный идентификатор брендаstringобязательныйидентификатор одинаковый для всех окружений в рамках бренда
productIdидентификатор игры в рамках брендаstringобязательныйтекущие идентификаторы: nft-aviatrix, second-chance, aviatrix-fruits
sessionTokenтокен с пользовательской сессиейstringопциональныйтокен должен быть сгенерирован брендом для дальнейших запросов из серверной части провайдера. Ожидаемая длина: 1-255 символов. Для демо-режима параметр не нужен
langкод языкаstringопциональныйкод формата ISO 639-1. Значение по умолчанию: en
lobbyUrllobby urlstringопциональныйнужен для редиректов на домашнюю страницу бренда
isDemoisDemo= значения true или falsestringопциональныйнужен для включения демо-режима игры. Обязательный параметр для запуска демо-режима
codeпромокодstringопциональныйнужен для прямого открытия формы ввода промокода. Если значение передано (code=promocode1&…), произойдет открытие модального окна и заполнение инпута. Если параметр пустой (code=&…), откроется форма ввода с пустым значением инпута.
hideExitButtonhideExitButton= значения true или falsestringопциональныйпозволяет управлять видимостью кнопки выхода в меню, переопределяя её отображение, если оно включено в конфигурации

Пример URL для запуска стандартной игры:

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

Пример URL для запуска демо-режима игры:

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

Пример URL для прямого открытия формы ввода промокода:

https://domain.com?cid=someplatform&productId=nft-aviatrix&code=promocode1
к сведению

Если в параметр productId передать значение nft-aviatrix, то сразу же откроется данная игра.

Рекомендации по встраиванию​

Десктопная web версия (iFrame)​

Стили (css правила)​

При встраивании клиентского приложения в iFrame, необходимо

  • добавить к тегу iframe

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

  • прописать на элементе "обнуляющие" стили:

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

Также рекомендуем выставлять высоту и ширину iFrame:

// на всю ширину
min-width: 100vw;
width: 100vw;

// на высоту без верхнего меню родительского окна (host-header-height - высота меню)
height: calc(100vh - var(--host-header-height));

Desktop Integration

iFrame коммуникация (postMessage)​

После успешной загрузки страницы внутри iframe, провайдер может коммуницировать с брендом посредством postMessage сообщений.

Провайдер -> Бренд​

На стороне провайдера реализован механизм отправки postMessage в родительское окно (в бренд). Для обработки этих сообщений на стороне бренда нужно подписаться на событие message

Структура message data:

  • action - (string) - имя действия
  • payload - (string) - полезная нагрузка сообщения

Доступные действия(action):

  • appReady - сигнализирует о завершении показа экрана загрузки (splash screen) и полной инициализации игры.
  • game.location (deprecated) - событие, которое сигнализирует, что пользователь нажал на кнопку выхода из игры, при этом обязательным параметром является lobbyUrl. Ожидается, что бренд отловит это событие и сделает нужный редирект.
  • game.redirect - событие, которое сигнализирует о переходе пользователя в другую игру. В payload события передаётся свойство gameId с идентификатором игры. Ожидается, что бренд отловит это событие и выполнит редирект.
  • game.exit - событие, которое сигнализирует, что пользователь нажал на кнопку выхода из игры. Ожидается, что бренд отловит это событие и сделает нужный редирект.

Пример использования:

// 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...
  }
});
Бренд -> Провайдер​

На стороне провайдера реализован механизм получения postMessage от бренда.

Структура message data:

  • action - (string) - имя действия

Доступные действия(action):

  • updateBalance - выполнить обновление баланса в iframe провайдера

Пример использования:

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

В случае, если на странице бренда могут располагаться несколько iframe, то для выбора iframe провайдера можно использовать уникальный атрибут id="aviatrix", который необходимо указать в теге iframe.

После чего селектор может выглядеть так:

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

Мобильная web версия (direct)​

При данном, рекомендованном типе мобильной web интеграции, бренду не нужно заботиться о стилевых особенностях встраивания. Данную задачу на себя берет провайдер.

Мобильная web версия (iFrame)​

При интеграции в мобильные устройства через iFrame, рекомендуется задействовать всю высоту экрана, убрав хедер, футер и другие элементы навигации, если такие имеются. Таким образом игровой интерфейс займет всю доступную область экрана, обеспечивая пользователю максимальное погружение, а также улучшит процесс взаимодействия.

Mobile Integration