Digital Distribution Hub
О решении
Digital Distribution Hub — это решение, которое связывает разработчиков игр с многочисленными партнерами-дистрибьюторами, предлагающими собственные платформы или экосистемы для распространения игр, виртуальных предметов, виртуальной валюты и бандлов.
Партнеры-дистрибьюторы — цифровые платформы или экосистемы, обладающие своей витриной и биллингом, через которые могут распространяться игры и внутриигровые товары. Примеры партнеров-дистрибьюторов Xsolla:
- суперприложения, которые объединяют множество сервисов;
- банковские приложения;
- телекоммуникационные и интернет-провайдеры;
- платежные терминалы;
- поставщики программ кешбэка и вознаграждений;
- торговые площадки электронной коммерции.
Преимущества для разработчика игр:
- Расширение аудитории игр за счет прямого подключения к быстрорастущим партнерам-дистрибьюторам.
- Увеличение доходов за счет добавления игры в новые каналы дистрибуции с уникальной пользовательской базой.
- Увеличение органического трафика за счет рекламы и баннеров на сторонних платформах.
Преимущества для партнера-дистрибьютора:
- Повышение лояльности ваших пользователей за счет расширения доступа к игровому контенту. Пользователи смогут приобретать игровые ключи, виртуальные предметы, виртуальную валюту и бандлы напрямую из приложения или сервиса.
- Удержание текущих и привлечение новых пользователей за счет растущей популярности игровой индустрии.
- Увеличение доходов за счет комиссии от продажи игровых ключей, виртуальных предметов и виртуальной валюты крупнейших участников рынка игровой индустрии.
Как это работает
Сценарий пользователя при покупке игровых ключей
Сценарий пользователя при покупке внутриигровых предметов и виртуальной валюты
Сценарий взаимодействия
- Разработчик игр создает проект в Личном кабинете и загружает игровые ключи, виртуальные предметы, виртуальную валюту, бандлы.
- Партнер-дистрибьютор запрашивает данные пользователя:
- при продаже игр — email-адрес пользователя, на который будут отправлены ключи и чек;
- при продаже внутриигровых товаров — ID пользователя в игре, которому будут добавлены товары, и email-адрес пользователя, на который будет отправлен чек.
- Пользователь вводит в интерфейсе партнера-дистрибьютора следующие данные:
- при покупке игр — email-адрес, на который будут отправлены ключи и чек;
- при покупке внутриигровых товаров — ID в игре для добавления товаров в инвентарь и email-адрес для получения чека.
- Партнер-дистрибьютор вызывает метод Создание токена пользователя и передает в параметрах email-адрес (обязательно) и ID пользователя (при продаже виртуальных предметов, виртуальной валюты и бандлов).
- Xsolla проверяет существование пользователя в игре, если у разработчика игр настроены вебхуки. Настройка вебхуков для продажи игровых ключей опциональна, для продажи внутриигровых товаров обязательна.
- Xsolla создает токен с данными пользователя и отправляет токен партнеру-дистрибьютору.
- Партнер-дистрибьютор запрашивает каталог товаров или каталог игр.
- Xsolla возвращает в ответе запрашиваемый каталог товаров или каталог игр.
- Партнер-дистрибьютор получает каталог и отображает его пользователю.
- Пользователь совершает покупку. Партнер-дистрибьютор формирует корзину.
- Партнер-дистрибьютор отправляет корзину пользователя для оформления заказа.
- Xsolla возвращает идентификатор заказа и стоимость корзины с учетом скидок и налогов.
- Партнер-дистрибьютор отображает пользователю итоговую стоимость корзины.
- Если пользователь продолжает оплату, партнер-дистрибьютор списывает денежные средства пользователя и отображает страницу со статусом платежа.
- Партнер-дистрибьютор оповещает Xsolla, что заказ оплачен, и передает информацию о платеже.
- Xsolla уведомляет разработчика игры о покупке.
- Пользователь, купивший игру, получает письмо с деталями покупки на указанный email-адрес и может активировать игровые ключи. Если пользователь купил внутриигровые товары, они будут добавлены в его инвентарь.
Интеграция на стороне разработчика игр
Как подключить Digital Distribution Hub
Чтобы продвигать вашу игру с помощью каналов дистрибуции:
- Подключите продукт Store в Личном кабинете и загрузите:
- игровые ключи или бандлы с игровыми ключами, если вы продаете игровые ключи;
- виртуальные предметы, виртуальную валюту или бандлы, если вы продаете внутриигровые товары.
- Настройте вебхуки.
- Обратитесь к вашему персональному менеджеру или напишите на csm@xsolla.com, чтобы активировать Digital Distribution Hub для выбранного вами проекта.
Как настроить вебхуки
Настройка вебхуков необходима:
- для валидации пользователя и персонализации каталога товаров по ID пользователя в игре;
- валидации пользователя и добавления купленных внутриигровых товаров в его инвентарь;
- связи ID транзакции со стороны Xsolla с ID транзакции в системе разработчика игр;
- передачи дополнительных параметров пользователя в заказе;
- получения оповещений о совершении покупки.
Чтобы настроить вебхуки:
- Откройте проект в Личном кабинете.
- Перейдите в раздел Настройки проекта > Вебхуки.
- Установите переключатель Вебхуки в положение Вкл.
- Укажите URL-адрес, на который вы хотите получать вебхуки.
- Секретный ключ проекта для подписи вебхуков генерируется по умолчанию. Если вы хотите изменить его, нажмите значок обновления.
- Нажмите Сохранить настройки.
Проверка существования пользователя
Xsolla отправляет вебхук Проверка существования пользователя, чтобы удостовериться, что данный пользователь существует в игре. Валидация пользователя позволяет:
- отобразить персонализированный каталог товаров для пользователя, если в ответе вы передадите атрибуты пользователя;
- добавить товары в инвентарь пользователя после покупки.
Чтобы подтвердить получение вебхука, ваш сервер должен вернуть:
- 204 HTTP-код без тела сообщения в случае успешного ответа, если пользователь существует в игре;
- 400 HTTP-код с описанием проблемы, если указанный пользователь не был найден или если передана недействительная подпись.
Полный список и механизм работы вебхуков с примерами обработки подробно описан в справочнике API.
В ответе вы можете передать дополнительные параметры транзакции в объекте custom_parameters
.
- json
1{
2"$schema": "http://json-schema.org/draft-04/schema#",
3"type": "object",
4"additionalProperties": false,
5"properties": {
6 "user_attributes": {
7 "type": "object",
8 "required": false,
9 "minProperties": 1,
10 "maxProperties": 100,
11 "patternProperties": {
12 "^[\\w-_.]{1,255}$": {
13 "oneOf": [
14 {
15 "type": "integer"
16 },
17 {
18 "type": "string",
19 "minLength": 1,
20 "maxLength": 255
21 },
22 {
23 "type": "array",
24 "items": {
25 "type": "string",
26 "maxLength": 255
27 },
28 "minItems": 1,
29 "maxItems": 1000
30 }
31 ]
32 }
33 },
34 "additionalProperties": false
35 }
36}
37}
Пример ответа:
- json
1{
2 "user_attributes": {
3 "age": 18,
4 "level": 1,
5 "game": "WoW",
6 "is_baned": false,
7 "registration_date": "2022-01-01"
8 }
9}
Связывание ID транзакций
Если вы используете внешний ID (ID транзакции в вашей системе) и хотите связать его с ID транзакции на стороне Xsolla или хотите передать дополнительные параметры транзакции, реализуйте обработку следующего вебхука:- json
1{
2 "$schema": "http://json-schema.org/draft-07/schema#",
3 "type": "object",
4 "additionalProperties": false,
5 "properties": {
6 "notification_type": {
7 "type": "string"
8 },
9 "order_id": {
10 "type": "integer"
11 },
12 "project_id": {
13 "type": "integer"
14 },
15 "user": {
16 "type": "object",
17 "properties": {
18 "external_id": {
19 "type": "string"
20 },
21 "email": {
22 "type": "string"
23 }
24 }
25 },
26 "items": {
27 "type": "array",
28 "items": {
29 "type": "object",
30 "properties": {
31 "item_id": {
32 "type": "integer"
33 },
34 "sku": {
35 "type": "string"
36 },
37 "quantity": {
38 "type": "integer"
39 },
40 "type": {
41 "type": "string"
42 }
43 }
44 }
45 }
46 }
47}
Пример запроса:
- json
1{
2 "notification_type": "create_external_transaction",
3 "order_id": 1,
4 "project_id": 51336,
5 "user": {
6 "external_id": "user_id",
7 "email": "public_email@test.com"
8 },
9 "items": [
10 {
11 "item_id": 101,
12 "sku": "mithril_dagger",
13 "quantity": 2,
14 "type": "virtual_good"
15 }
16 ]
17}
В ответе вы можете передать дополнительные параметры транзакции в объекте custom_parameters
.
Ожидаемый ответ:
- json
1{
2 "id": "validation_transaction_info_response.json",
3 "$schema": "http://json-schema.org/draft-07/schema#",
4 "description": "DDH Project Transaction Info Response",
5 "type": "object",
6 "additionalProperties": true,
7 "properties": {
8 "id": {
9 "type": "string",
10 "minLength": 1
11 },
12 "custom_parameters": {
13 "type": "object",
14 "additionalProperties": true,
15 "minProperties": 1,
16 "maxProperties": 200
17 }
18 }
19}
Пример ответа:
- json
1{
2 "id":"123"
3}
Список параметров вебхука для связывания ID транзакций:
Параметр | Тип | Описание |
---|---|---|
notification_type | string | Тип оповещения. |
order_id | integer | ID заказа. |
project_id | integer | ID проекта, в который загружены игровые ключи или бандлы с игровыми ключами, внутриигровые товары или бандлы с товарами. |
user.external_id | string | ID пользователя на стороне разработчика игр. |
items | string | Список предметов, которые купил пользователь. |
items.sku | string | Уникальный артикул товара. |
items.quantity | integer | Количество предметов. |
items.type | string | Тип товара. Может принимать значения virtual_good , virtual_currency , physical_good , unit . Тип unit используется для игр. |
items.unit_items | array | Массив с данными об игре. |
items.unit_items.type | string | Тип товара для пакета игровых ключей. Может принимать значение game_key . |
items.unit_items.sku | string | Уникальный артикул пакета игровых ключей. Для игры на конкретной платформе используется значение в формате sku_drm . Пример для игры с артикулом 110101 на steam: “sku”: “110101_steam” . |
Оповещение о совершении покупки
После того как пользователь оплачивает покупку, вы получаете:- Вебхук об оплате, который содержит платежную информацию.
- Вебхук о составе корзины, который содержит информацию о товарах для начисления в инвентарь.
Интеграция на стороне партнера-дистрибьютора
Если вы заинтересованы в интеграции Digital Distribution Hub, напишите на psbusiness@xsolla.com для связи с менеджером и получения обязательных параметров для работы с методами Digital Distribution Hub API:
В процессе интеграции вам потребуется отправлять уведомления об успешной оплате или отмене платежа (шаг 9). Для корректной обработки уведомлений на стороне Xsolla сообщите вашему менеджеру IP-адрес сервера, с которого вы отправляете уведомления. Если IP-адрес меняется, необходимо своевременно уведомить об этом менеджера.
- Отобразите форму для ввода:
- email-адреса пользователя — при продаже игр;
- email-адреса и ID пользователя в игре — при продаже внутриигровых товаров.
- ID пользователя в игре используется для проектов, которые продают виртуальные предметы, валюту и бандлы с предметами и валютой. В этом случае также необходимо отобразить подсказку для пользователя о необходимости ввода ID, который он получил при регистрации в игре.
- Пример:

- Передайте полученные данные пользователя:
- Email-адрес пользователя. Обязателен всегда.
- ID пользователя в игре. Обязателен при продаже внутриигровых товаров.
- Данные используются для проверки существования этого пользователя в игре и получения авторизационного токена.
- Используйте метод Создание токена пользователя. В запросе передайте параметры:
Параметр | Тип | Описание |
---|---|---|
project_id | integer | ID проекта, в который загружены игровые ключи или бандлы с игровыми ключами, внутриигровые товары или бандлы с товарами. |
user.email | string | Email-адрес пользователя. |
user.id | string or null | Уникальный ID пользователя в игре. |
- В ответе вернется авторизационный токен с данными пользователя.
- Импортируйте:
- каталог игр, используя метод Получение списка игр;
- каталог виртуальных предметов, используя метод Получение списка виртуальных предметов;
- каталог виртуальных валют, используя метод Получение списка виртуальных валют;
- каталог бандлов с играми или товарами, используя метод Получение списка бандлов.
- В запросе передайте токен, полученный на шаге 2, и следующий параметр:
Параметр | Тип | Описание |
---|---|---|
project_id | integer | ID проекта, в который загружены игровые ключи или бандлы с игровыми ключами, внутриигровые товары или бандлы с товарами. |
- Отобразите каталог игр и товаров на своей витрине. В интерфейсе реализуйте возможность для выбора:
- количества игровых ключей и платформы публикации игры;
- количества виртуальных предметов;
- количества виртуальной валюты или пакетов виртуальной валюты с фиксированным количеством валюты;
- количества бандлов.
- Если вы используете корзину, количество товара может быть указано в корзине пользователя. Если вы не используете корзину, выбор количества товара может быть реализован в каталоге.
- Пример для указания количества товаров в корзине:

- Пример для указания количества товаров в каталоге:

- Если вы не используете корзину, перейдите к шагу 6 и используйте метод Создание заказа с указанным предметом.
- Для наполнения корзины используйте метод Наполнение корзины предметами.
- Пользователь может добавлять и убирать товары, изменять их количество в одном заказе. Для обновления корзины вы можете использовать:
- метод Наполнение корзины предметами каждый раз, когда пользователь меняет состав корзины;
- методы обновления корзины и удаления предмета:
- В этом случае после обновления корзины воспользуйтесь методом Получение корзины текущего пользователя.
- В запросах методов наполнения и обновления корзины передайте следующие параметры:
Параметр | Тип | Описание |
---|---|---|
project_id | integer | ID проекта, в который загружены игровые ключи или бандлы с игровыми ключами, внутриигровые товары или бандлы с товарами. |
items.sku | string | Уникальный артикул товара, который указывает разработчик игр в Личном кабинете. |
items.quantity | integer | Количество предметов. |
items.type | string | Тип товара. Может принимать значения virtual_good , virtual_currency , physical_good , unit . Тип unit используется для игр. |
items.unit_items | array | Массив с данными об игре. |
items.unit_items.type | string | Тип товара для пакета игровых ключей. Может принимать значение game_key . |
items.unit_items.sku | string | Уникальный артикул пакета игровых ключей, который указывает разработчик игр в Личном кабинете. Для игры на конкретной платформе используется значение в формате sku_drm . Пример для игры с артикулом 110101 на steam: “sku”: “110101_steam” . |
- После вызова метода Наполнение корзины предметами или метода Получение корзины текущего пользователя в ответе вернется текущая информация о выбранных товарах — цены до и после применения скидок, бонусные товары.
- Для создания заказа и покупки корзины используйте метод Создание заказа со всеми предметами из текущей корзины. В запросе передайте следующие параметры:
Параметр | Тип | Описание |
---|---|---|
project_id | integer | ID проекта, в который загружены игровые ключи или бандлы с игровыми ключами, внутриигровые товары или бандлы с товарами. |
| number | ID партнера-дистрибьютора на стороне Xsolla. |
| string | Валюта платежа. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217. |
- В ответе вернется ID заказа и стоимость корзины с учетом налогов.
- Отобразите пользователю итоговую стоимость корзины.
- Осуществите списание денежных средств пользователя внутри вашей платформы. Отобразите пользователю статус платежа.
- Отправьте уведомление об успешной оплате. Если платеж не был выполнен или был оформлен возврат, отправьте уведомление об отмене платежа.
- Для корректной обработки уведомлений на стороне Xsolla сообщите IP-адрес сервера, с которого вы отправляете уведомления, вашему менеджеру на стороне Xsolla. Если IP-адрес меняется, необходимо своевременно уведомить об этом менеджера.
Нашли опечатку или ошибку в тексте? Выделите ее и нажмите Ctrl+Enter.