Digital Distribution Hub

О решении

Digital Distribution Hub — это решение, которое связывает разработчиков игр с многочисленными партнерами-дистрибьюторами, предлагающими собственные платформы или экосистемы для распространения игр, виртуальных предметов, виртуальной валюты и бандлов.

Партнеры-дистрибьюторы — цифровые платформы или экосистемы, обладающие своей витриной и биллингом, через которые могут распространяться игры и внутриигровые товары. Примеры партнеров-дистрибьюторов Xsolla:

• суперприложения, которые объединяют множество сервисов;
• банковские приложения;
• телекоммуникационные и интернет-провайдеры;
• платежные терминалы;
• поставщики программ кешбэка и вознаграждений;
• торговые площадки электронной коммерции.

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

• Расширение аудитории игр за счет прямого подключения к быстрорастущим партнерам-дистрибьюторам.
• Увеличение доходов за счет добавления игры в новые каналы дистрибуции с уникальной пользовательской базой.
• Увеличение органического трафика за счет рекламы и баннеров на сторонних платформах.

Преимущества для партнера-дистрибьютора:

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

Как это работает

Сценарий пользователя при покупке игровых ключей

Сценарий пользователя при покупке внутриигровых предметов и виртуальной валюты

Сценарий взаимодействия

1. Разработчик игр создает проект в Личном кабинете и загружает игровые ключи, виртуальные предметы, виртуальную валюту, бандлы.
2. Партнер-дистрибьютор запрашивает данные пользователя:
   • при продаже игр — email-адрес пользователя, на который будут отправлены ключи и чек;
   • при продаже внутриигровых товаров — ID пользователя в игре, которому будут добавлены товары, и email-адрес пользователя, на который будет отправлен чек.
3. Пользователь вводит в интерфейсе партнера-дистрибьютора следующие данные:
   • при покупке игр — email-адрес, на который будут отправлены ключи и чек;
   • при покупке внутриигровых товаров — ID в игре для добавления товаров в инвентарь и email-адрес для получения чека.
4. Партнер-дистрибьютор вызывает метод Создание токена пользователя и передает в параметрах email-адрес (обязательно) и ID пользователя (при продаже виртуальных предметов, виртуальной валюты и бандлов).
5. Xsolla проверяет существование пользователя в игре, если у разработчика игр настроены вебхуки. Настройка вебхуков для продажи игровых ключей опциональна, для продажи внутриигровых товаров обязательна.
6. Xsolla создает токен с данными пользователя и отправляет токен партнеру-дистрибьютору.
7. Партнер-дистрибьютор запрашивает каталог товаров или каталог игр.
8. Xsolla возвращает в ответе запрашиваемый каталог товаров или каталог игр.
9. Партнер-дистрибьютор получает каталог и отображает его пользователю.
10. Пользователь совершает покупку. Партнер-дистрибьютор формирует корзину.
11. Партнер-дистрибьютор отправляет корзину пользователя для оформления заказа.
12. Xsolla возвращает идентификатор заказа и стоимость корзины с учетом скидок и налогов.
13. Партнер-дистрибьютор отображает пользователю итоговую стоимость корзины.
14. Если пользователь продолжает оплату, партнер-дистрибьютор списывает денежные средства пользователя и отображает страницу со статусом платежа.
15. Партнер-дистрибьютор оповещает Xsolla, что заказ оплачен, и передает информацию о платеже.
16. Xsolla уведомляет разработчика игры о покупке.
17. Пользователь, купивший игру, получает письмо с деталями покупки на указанный email-адрес и может активировать игровые ключи. Если пользователь купил внутриигровые товары, они будут добавлены в его инвентарь.

Интеграция на стороне разработчика игр

Как подключить Digital Distribution Hub

Чтобы продвигать вашу игру с помощью каналов дистрибуции:

1. В проекте в Личном кабинете перейдите в раздел Каталог товаров и создайте:
   • Игровые ключи или бандлы с игровыми ключами, если вы продаете игровые ключи.
   • Виртуальные предметы, виртуальную валюту или бандлы, если вы продаете внутриигровые товары.
2. Настройте вебхуки.
3. Обратитесь к вашему персональному менеджеру или напишите на csm@xsolla.com, чтобы активировать Digital Distribution Hub для выбранного вами проекта.

Как настроить вебхуки

Настройка вебхуков необходима:

• для валидации пользователя и персонализации каталога товаров по ID пользователя в игре;
• валидации пользователя и добавления купленных внутриигровых товаров в его инвентарь;
• связи ID транзакции со стороны Xsolla с ID транзакции в системе разработчика игр;
• передачи дополнительных параметров пользователя в заказе;
• получения оповещений о совершении покупки.

Чтобы настроить вебхуки:

1. Откройте проект в Личном кабинете.
2. Перейдите в раздел Настройки проекта > Вебхуки.
3. Установите переключатель Вебхуки в положение Вкл.
4. Укажите URL-адрес, на который вы хотите получать вебхуки.
5. Секретный ключ проекта для подписи вебхуков генерируется по умолчанию. Если вы хотите изменить его, нажмите значок обновления.
6. Нажмите Сохранить настройки.

Проверка существования пользователя

Xsolla отправляет вебхук Проверка существования пользователя, чтобы удостовериться, что данный пользователь существует в игре. Валидация пользователя позволяет:

• отобразить персонализированный каталог товаров для пользователя, если в ответе вы передадите атрибуты пользователя;
• добавить товары в инвентарь пользователя после покупки.

Чтобы подтвердить получение вебхука, ваш сервер должен вернуть:

• 204 HTTP-код без тела сообщения в случае успешного ответа, если пользователь существует в игре;
• 400 HTTP-код с описанием проблемы, если указанный пользователь не был найден или если передана недействительная подпись.

Полный список и механизм работы вебхуков с примерами обработки подробно описан в справочнике API.

В ответе вы можете передать дополнительные параметры транзакции в объекте custom_parameters.

 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}

Пример ответа:

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 транзакций

 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}

Пример запроса:

 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.

Ожидаемый ответ:

 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}

Пример ответа:

1{
2    "id":"123"
3}

Список параметров вебхука для связывания ID транзакций:

Оповещение о совершении покупки

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

Интеграция на стороне партнера-дистрибьютора

Если вы заинтересованы в интеграции Digital Distribution Hub, напишите на psbusiness@xsolla.com для связи с менеджером и получения обязательных параметров для работы с методами Digital Distribution Hub API:

• geotype;
• project_id;
• distribution_hub_id и api_key.

В процессе интеграции вам потребуется отправлять уведомления об успешной оплате или отмене платежа (шаг 9). Для корректной обработки уведомлений на стороне Xsolla сообщите вашему менеджеру IP-адрес сервера, с которого вы отправляете уведомления. Если IP-адрес меняется, необходимо своевременно уведомить об этом менеджера.

1. Отобразите форму для ввода:
   • email-адреса пользователя — при продаже игр;
   • email-адреса и ID пользователя в игре — при продаже внутриигровых товаров.

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

1. Пример:

2. Передайте полученные данные пользователя:
   • Email-адрес пользователя. Обязателен всегда.
   • ID пользователя в игре. Обязателен при продаже внутриигровых товаров.

1. Данные используются для проверки существования этого пользователя в игре и получения авторизационного токена.

1. Используйте метод Создание токена пользователя. В запросе передайте параметры:

1. В ответе вернется авторизационный токен с данными пользователя.

3. Импортируйте:
   • каталог игр, используя метод Получение списка игр;
   • каталог виртуальных предметов, используя метод Получение списка виртуальных предметов;
   • каталог виртуальных валют, используя метод Получение списка виртуальных валют;
   • каталог бандлов с играми или товарами, используя метод Получение списка бандлов.

1. В запросе передайте токен, полученный на шаге 2, и следующий параметр:

4. Отобразите каталог игр и товаров на своей витрине. В интерфейсе реализуйте возможность для выбора:
   • количества игровых ключей и платформы публикации игры;
   • количества виртуальных предметов;
   • количества виртуальной валюты или пакетов виртуальной валюты с фиксированным количеством валюты;
   • количества бандлов.

1. Если вы используете корзину, количество товара может быть указано в корзине пользователя. Если вы не используете корзину, выбор количества товара может быть реализован в каталоге.

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

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

1. Если вы не используете корзину, перейдите к шагу 6 и используйте метод Создание заказа с указанным предметом.

5. Для наполнения корзины используйте метод Наполнение корзины предметами.

1. Пользователь может добавлять и убирать товары, изменять их количество в одном заказе. Для обновления корзины вы можете использовать:
   • метод Наполнение корзины предметами каждый раз, когда пользователь меняет состав корзины;
   • методы обновления корзины и удаления предмета:
     • Обновление предмета из текущей корзины;
     • Удаление всех предметов из текущей корзины;
     • Удаление предмета из текущей корзины.

1. В этом случае после обновления корзины воспользуйтесь методом Получение корзины текущего пользователя.

1. В запросах методов наполнения и обновления корзины передайте следующие параметры:

1. После вызова метода Наполнение корзины предметами или метода Получение корзины текущего пользователя в ответе вернется текущая информация о выбранных товарах — цены до и после применения скидок, бонусные товары.

6. Для создания заказа и покупки корзины используйте метод Создание заказа со всеми предметами из текущей корзины. В запросе передайте следующие параметры:

1. В ответе вернется ID заказа и стоимость корзины с учетом налогов.

7. Отобразите пользователю итоговую стоимость корзины.
8. Осуществите списание денежных средств пользователя внутри вашей платформы. Отобразите пользователю статус платежа.
9. Отправьте уведомление об успешной оплате. Если платеж не был выполнен или был оформлен возврат, отправьте уведомление об отмене платежа.

1. Для корректной обработки уведомлений на стороне Xsolla сообщите IP-адрес сервера, с которого вы отправляете уведомления, вашему менеджеру на стороне Xsolla. Если IP-адрес меняется, необходимо своевременно уведомить об этом менеджера.