Авторизация / Кросс-платформенный аккаунт

Кросс-платформенный аккаунт

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

Глоссарий

В Личном кабинете доступны следующие типы варианта авторизации:

  1. Стандартный — вариант авторизации, который используется для хранения единых аккаунтов.
  2. Теневой — вариант авторизации, который используется для хранения аккаунтов платформ и аутентификации пользователя на платформе публикации.

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

Аккаунт платформы — аккаунт пользователя, который создается в теневом варианте авторизации и связан с конкретной платформой публикации. Аккаунт платформы может быть привязан к единому аккаунту, но не к другому аккаунту платформы. Удаление привязки аккаунта платформы невозможно.

Платформа публикации — платформа, на которой распространяется игра. Например, Steam, Xbox, PlayStation.

Кросс-платформенный аккаунт — единый аккаунт, к которому привязаны один или более аккаунтов платформ.

Каждый аккаунт пользователя с играми на определенной платформе должен быть сопоставлен с аккаунтом платформы в теневом варианте авторизации. Например, у пользователя есть аккаунт с играми на Xbox и PlayStation. Тогда к теневому варианту авторизации могут быть привязаны два аккаунта платформы: аккаунт на Xbox и аккаунт на PlayStation.

Использование кросс-платформенного аккаунта

Использование кросс-платформенного аккаунта позволяет:

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

Если аккаунт платформы привязан к единому аккаунту:

  1. Пользователь авторизуется на платформе.
  2. Сервер Авторизации Иксолла выдает пользователю токен единого аккаунта.
  3. Сервер Авторизации Иксолла авторизует пользователя единого аккаунта.

При использовании кросс-платформенного аккаунта ID пользователя в токене будет совпадать с ID единого аккаунта. ID пользователя можно найти в JWT > поле sub.

Сценарий привязки аккаунтов

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

  1. Пользователь впервые входит в игру на консольной платформе.
  2. Интерфейс игры предлагает привязать аккаунт платформы и единый аккаунт игры пользователя.
  3. Пользователь переходит в приложение и авторизуется в едином аккаунте.
  4. Приложение отправляет запрос Create code for linking accounts на сервер Авторизации Иксолла.
  5. Приложение отображает игроку код привязки.
  6. Пользователь возвращается к консольной платформе и вводит полученный код.
  7. Сервер игры отправляет запрос Link accounts by code на сервер Авторизации Иксолла.
  8. На экране консольной платформы выводится сообщение об успешности привязки.

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

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

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

Для интеграции кросс-платформенного аккаунта понадобятся следующие параметры из Личного кабинета:

  • main_project_id — ID стандартного варианта авторизации в UUID формате. Например: f6c5011a-715e-4e5e-b7b1-a4812d85b8c8.
  • shadow_project_id — ID варианта авторизации в UUID формате, который будет использоваться в качестве теневого. Создайте теневой вариант авторизации, указав для него publisher_project_id в настройках варианта авторизации. ID созданного проекта — это shadow_project_id.
  • publisher_project_id — ID проекта. Параметр отображается в разделе Настройки проекта > Общие настройки > ID варианта авторизации.

Передайте аккаунт-менеджеру проекта параметры shadow_project_id и publisher_project_id, чтобы получить параметры OAuth 2.0 клиента:

  • client_id — идентификатор OAuth 2.0 клиента;
  • client_secret — секретный ключ OAuth 2.0 клиента.
Перечисленные параметры используются для получения серверного токена.

Чтобы интегрировать кросс-платформенный аккаунт, выполните следующие шаги:

  1. Реализуйте аутентификацию пользователей:
    1. В едином аккаунте.
    2. В аккаунте платформы.
  2. Выполните привязку аккаунтов:
    1. Получение кода привязки.
    2. Привязка аккаунтов.

Аутентификация пользователя в едином аккаунте

Единый аккаунт создается в варианте авторизации с указанным main_project_id. Для регистрации и аутентификации может использоваться как виджет авторизации, так и Login API.

Аутентификация пользователя в аккаунте платформы

Для регистрации и аутентификации пользователей через платформу выберите способ и следуйте инструкции. Вы можете совмещать эти способы. Например, для платформы Xbox использовать автоматическую аутентификацию, а для другой платформы — аутентификацию через custom ID.

Аутентификация через custom ID

Для создания аккаунта платформы используйте на сервере игры метод Auth by custom ID. Передайте в него:

  • Параметр publisher_project_id или shadow_project_id. Если в запросе отсутствуют оба параметра, сервер Авторизации Иксолла вернет ошибку.
  • Серверный токен.
  • Информацию об аккаунте пользователя на платформе в параметре social_profile.

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

Сценарий аутентификации:

  1. Клиент игры выполняет запрос на аутентификацию на сервер игры, когда пользователь запускает игру.
  2. Сервер игры генерирует или использует уже существующий custom ID пользователя.
  3. Сервер игры отправляет запрос Auth by custom ID c указанием платформы и ID пользователя на этой платформе (параметры platform и user_id соответственно) на сервер Авторизации Иксолла. Если пользователь с переданным custom ID не найден, создается новый пользователь.
  4. Сервер Авторизации Иксолла возвращает токен серверу игры.

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

Copy
Full screen
Small screen
POST /api/users/login/server_custom_id?publisher_project_id=<publisher_project_id> HTTP/1.1
Host: login.xsolla.com
X-Server-Authorization: <server_token>
Content-Type: application/json

{
  "server_custom_id": "secret_value",
  "social_profile": {
    "platform": "xbox",
    "user_id": "123"
  }
}

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

Copy
Full screen
Small screen
HTTP/1.1 200 OK
Content-Type: application/json

{
  "token": "<platform_user_token>"
}

Автоматическая аутентификация

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

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

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

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

  1. Используйте метод Create code for linking accounts. Передайте в него пользовательский токен, полученный при авторизация в едином аккаунте.
  2. Отобразите полученный код пользователю.

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

Copy
Full screen
Small screen
POST /api/users/account/code HTTP/1.1
Host: login.xsolla.com
Authorization: Bearer <main_user_token>

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

Copy
Full screen
Small screen
HTTP/1.1 200 OK
Content-Type: application/json

{
  "code": "123456"
}

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

Для привязки аккаунта платформы к единому аккаунту используйте метод Link accounts by code. Передайте в него параметр code со значением кода привязки, введенного пользователем на консольной платформе.

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

Copy
Full screen
Small screen
POST /api/users/account/link HTTP/1.1
Host: login.xsolla.com
X-Server-Authorization: <server_token>
Content-Type: application/json

{
  "code": "123456",
  "platform": "xbox",
  "user_id": "123",
  "publisher_project_id": 44056
}

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

Copy
Full screen
Small screen
HTTP/1.1 204 No Content