Кросс-платформенный инвентарь

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

Кросс-платформенный инвентарь позволяет синхронизировать инвентарь пользователя в игре на разных платформах публикации (Steam, EGS, PlayStation, XBox и т.д.), получать данные об инвентаре и балансе пользователя и управлять ими.

Синхронизация обеспечивается выполнением следующих шагов:

  1. Игрок привязывает свои аккаунты на платформах к единому аккаунту, который обеспечивает идентификацию конкретного игрока на разных платформах.
  2. Иксолла обеспечивает механизм связывания аккаунтов платформ с единым аккаунтом и объединение инвентаря на платформах.

Компоненты решения включают в себя:

  • Клиент игры
  • Сервер игры
  • Веб-приложение с интерфейсом привязки аккаунтов
  • Авторизацию Иксолла (Xsolla Login), обеспечивающую наличие единого аккаунта и механизм связывания аккаунтов
  • Инвентарь игрока (Xsolla Player Inventory) для хранения инвентаря игрока

Сценарий пользователя

Для привязки аккаунта онлайн-платформы (Steam, EGS) к единому аккаунту необходимо реализовать идентификацию пользователей в игре, используя учетную запись Авторизации Иксолла, либо использовать алгоритм привязки аккаунта для консольных платформ.

Алгоритм привязки аккаунта консольной платформы к единому аккаунту реализован следующим образом:

  1. Игрок впервые совершает вход в игру на консольной платформе.
  2. В интерфейсе игры отображается предложение выполнить привязку аккаунта платформы к единому аккаунту игры.
  3. Если игрок подтверждает действие:
    1. Осуществляется переход в стороннее приложение (например, сайт игры или мобильное приложение), где игрок авторизуется в едином аккаунте игры или создает его.
    2. После авторизации в приложении отображается цифробуквенный код привязки.
  4. Игрок возвращается к консольной версии игры и вводит код.
  5. Осуществляется привязка аккаунта платформы к единому аккаунту с выводом сообщения на экране консоли.
  6. Инвентарь игрока на платформе объединяется с инвентарем, привязанным к единому аккаунту.

Note: Премиальная валюта (валюта, которую игрок приобретает за реальные деньги) не объединяется с инвентарем. Согласно требованиям консольных платформ публикации, премиальная валюта, приобретенная через консоли PlayStation, Xbox и Nintendo Switch, не объединяется и хранится отдельно.
Notice: После успешной привязки аккаунт платформы больше нельзя отвязать от единого аккаунта. Также, если игрок при первом входе в игру отказывается от привязки, данное действие невозможно выполнить повторно.

Для кого подходит

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

Note: Решение можно подключить только до выхода игры на вторую платформу публикации. Например, если игра уже вышла на PC-платформу и планирует релиз на PlayStation, ей нужно подключить кросс-платформенный инвентарь до релиза на PlayStation.

Как настроить

Чтобы подключить кросс-платформенный инвентарь:

  1. Подключите Инвентарь игрока. В части аутентификации необходимо реализовать базовую HTTP-аутентификацию для работы с серверными методами и аутентификацию через Xsolla Login по протоколу OAuth 2.0 для работы с клиентскими методами. OAuth 2.0 авторизация также необходима для доступа к методам Login API и реализации методов привязки аккаунтов.
  2. Реализуйте интерфейс для связывания аккаунтов, включая:
    1. авторизацию и управление инвентарем на сервере игры;
    2. авторизацию и управление инвентарем на клиенте игры;
    3. методы привязки аккаунтов.

Note: Если у вас уже реализована синхронизация аккаунтов на стороне сервера игры, достаточно настроить только Инвентарь игрока для синхронизации инвентаря пользователя.

Интерфейс для связывания аккаунтов

В интерфейсе для связывания аккаунтов должны быть реализованы следующие возможности:

  • Предложение связать аккаунт платформы с единым аккаунтом.
  • Возможность согласиться или отказаться от привязки.
  • Поле для ввода кода привязки, если пользователь согласился на привязку.
  • Отображение ссылки на мобильное или веб-приложение, в котором пользователь может осуществить привязку аккаунта платформы к единому аккаунту.

Механизм авторизации пользователей в едином аккаунте реализуется следующим образом:

  1. Интегрируйте виджет Авторизации Иксолла в приложение.
  2. При авторизации игрока через виджет, в приложение передается JWT. Реализуйте отправку JWT из приложения в метод получения кода привязки и вывод кода привязки в приложении.
  3. Реализуйте на стороне сервера игры авторизацию игрока через токен.
  4. При переходе игрока в консольную версию игры и вводе кода привязки реализуйте передачу токена, user_id пользователя на консольной платформе и ID платформы в метод привязки к единому аккаунту.

Note: Если вы хотите осуществить миграцию существующих аккаунтов для их хранения на стороне Иксоллы, обратитесь к аккаунт-менеджеру проекта или напишите на am@xsolla.com.

Авторизация на сервере игры

Чтобы получить доступ к методам Login API для работы с инвентарем игрока на сервере игры, необходимо настроить OAuth2.0 авторизацию и получить серверный токен доступа.

Note: Чтобы получить client_id и client_secret, обратитесь к аккаунт-менеджеру проекта или напишите на am@xsolla.com.

Запрос

<?php
$uri = 'https://login.xsolla.com/api/oauth2/token';
$body = [
    'grant_type' => 'client_credentials',
    'client_id' => 1,
    'client_secret' => 'client_secret'
];

$headers = [
    'Content-type: application/x-www-form-urlencoded'
];

$request = curl_init($uri);
curl_setopt($request, CURLOPT_RETURNTRANSFER, true);
curl_setopt($request, CURLOPT_POST, true);
curl_setopt($request, CURLOPT_POSTFIELDS, http_build_query($body));

curl_setopt($request, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($request);
print_r($response);

Ответ

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",           
    "token_type":"bearer",
    "expires_in":3600,
    "scope": ""
}

Управление инвентарем игрока на сервере игры

Для работы с инвентарем игрока доступны следующие серверные методы:

В указанные методы необходимо передавать user_id пользователя на платформе и ID платформы.

Авторизация на клиенте игры

Реализуйте вызов метода для получения JWT, который будет использоваться для работы с инвентарем игрока на клиенте игры. В запросе необходимо передать:

  • server_custom_id — уникальный идентификатор пользователя в игре.
  • social_profile->user_id — уникальный идентификатор пользователя на платформе.

Запрос

<?php
$uri = 'https://login.xsolla.com/api/users/login/server_custom_id';
$queryParams = [
    'publisher_project_id' => 44056
];
$queryParamsString = '?' . http_build_query($queryParams);

$body = '
    {
        "server_custom_id": "1234567890asdfghjkl",
        "social_profile": {
          "platform": "xbox_live",
          "user_id": "4352354"
        }
    }
';

$headers = [
    'Content-type: application/json',
    'x-server-authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'
];

$request = curl_init($uri . $queryParamsString);
curl_setopt($request, CURLOPT_RETURNTRANSFER, true);
curl_setopt($request, CURLOPT_POSTFIELDS, $body);
curl_setopt($request, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($request);

Ответ

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Note: Для получения JWT также можно использовать метод User tokenization.

Управление инвентарем игрока на клиенте игры

Для работы с инвентарем игрока доступны следующие клиентские методы:

Для управления инвентарем игрока на консольных платформах:

  1. Реализуйте передачу ID платформы в клиентские методы для соблюдения требования о хранении баланса премиальной валюты на стороне консольных платформ публикации.
  2. Реализуйте на сервере игры следующие шаги для работы с инвентарем пользователя на консольном клиенте:
    1. Игра получает серверный токен доступа для токенизации пользователей.
    2. Игра получает JWT по user_id пользователя на платформе и ID платформы.
    3. Игра передает JWT в указанные клиентские методы.

Методы привязки аккаунтов

Получение кода привязки

Реализуйте вызов метода для получения кода привязки, чтобы передать его пользователю.

Запрос

var data = null;
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
    if (this.readyState === this.DONE) {
        console.log(this.responseText);
    }
});
xhr.open("GET", "https://login.xsolla.com/api/users/account/code");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");
xhr.send(data);

Ответ

{
  "code": "123456"
}

Привязка к единому аккаунту

Реализуйте вызов метода для привязки аккаунта платформы к единому аккаунту, где:

  • code — код привязки;
  • publisher_project_id — идентификатор проекта из Личного кабинета Иксолла;
  • user_id — идентификатор пользователя на платформе.

Убедитесь, что перед вызовом метода выполнены следующие шаги:

  1. Реализован интерфейс отображения кода привязки пользователю и форма для ввода полученного кода.
  2. Реализован метод получения серверного токена для авторизации.
  3. Реализован метод получения кода привязки.

Note: Для привязки аккаунта платформы к единому аккаунту также можно использовать метод Connect game account to Xsolla.

Запрос

<?php
$uri = 'https://login.xsolla.com/api/users/account/link';
$body = '
    {
        "code": "234155",
        "platform": "xbox_live",
        "publisher_project_id": "12423354",
        "user_id": "4352354"
    }
';

$headers = [
    'Content-type: application/x-www-form-urlencoded',
    'x-server-authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'
];

$request = curl_init($uri);
curl_setopt($request, CURLOPT_RETURNTRANSFER, true);
curl_setopt($request, CURLOPT_POSTFIELDS, $body);
curl_setopt($request, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($request);

Ответ

204 OK

Список платформ

ПлатформаID платформыКомментарий
PlayStation Networkplaystation_network-
XBox Livexbox_live-
PC Standalonepc_standalone-
Nintendo eShopnintendo_shop-
Google Playgoogle_play-
Apple Storeapp_store_ios-
Android (независимая продажа)android_standaloneИгра публикуется индивидуально вне магазинов.
IOS (независимая продажа)ios_standaloneИгра публикуется индивидуально вне магазинов.
Android (альтернативный магазин)android_otherИгра публикуется в альтернативном PlayMarket-магазине.
IOS (альтернативный магазин)ios_otherИгра публикуется в альтернативном AppStore-магазине.
PC (альтернативный магазин)pc_other-
Иксоллаxsolla-