跨平台帐户

运行机制

词汇表

您在发布商帐户中可访问以下登录管理器项目类型：

1. 标准登录管理器项目是用于存储主帐户的登录管理器项目。
2. 影子登录管理器项目是用于存储平台帐户的登录管理器项目。

主帐户是一种在标准登录管理器项目中创建的帐户，并与各种平台帐户关联。主帐户用于在不同平台上认证玩家身份。

平台帐户是一种在影子登录管理器项目中创建的帐户，并与某个具体的发布平台关联。一个平台帐户不能关联其他平台帐户，也不能取消平台帐户与主帐户的关联。

发布平台是用于分发游戏的游戏平台（例如Steam、PlayStation、Xbox等）。

跨平台帐户是一个关联了主帐户和平台帐户的帐户。

每个拥有某平台游戏的用户帐户对应影子登录管理器项目中的一个平台帐户。例如，如果用户帐户中拥有Xbox和PlayStation平台上的游戏，则影子登录管理器平台帐户应关联至相应的Xbox和PlayStation平台帐户。

使用跨平台帐户

跨平台帐户允许：

• 在不同平台上拥有同一个游戏帐户。
• 从平台帐户获取社交帐户好友列表。
• 使用跨平台物品库同步不同平台上的用户物品库

主帐户和平台帐户关联后：

1. 用户在平台上进行认证。
2. 艾克索拉登录管理器服务器向用户发送主帐户令牌。
3. 艾克索拉登录管理器服务器认证主帐户用户。

使用跨平台帐户时，令牌中的用户ID与主帐户ID相同。您可以在JWT > sub声明中找到用户ID。

帐户关联过程

如果用户拥有主帐户，则其在平台上进行认证的过程中可将该平台帐户关联至主帐户。过程如下：

1. 玩家在游戏控制台平台上首次进入该游戏。
2. 游戏UI显示可将平台帐户关联至主帐户的提示消息。
3. 用户启动应用程序并进入主帐户。
4. 应用程序向艾克索拉登录管理器服务器发送Create code for linking accounts请求。
5. 应用程序UI向用户显示一个帐户关联码。
6. 用户返回游戏控制台并输入关联码。
7. 游戏服务器向艾克索拉登录管理器服务器发送Link accounts by code请求。
8. 游戏控制台显示确认消息。

适用对象

集成了登录管理器并拥有发布平台帐户的合作伙伴。

如何获取

要集成跨平台帐户，需要发布商帐户中的以下参数：

• main_project_id — UUID格式的标准登录管理器项目ID。例如：f6c5011a-715e-4e5e-b7b1-a4812d85b8c8。
• shadow_project_id — UUID格式的影子登录管理器项目ID。该项目用作一个影子登录管理器项目。请创建一个影子登录管理器项目，并在登录管理器项目设置中指定其publisher_project_id。shadow_project_id是所创建项目的ID。
• publisher_project_id — 项目ID。该参数在项目设置 > 常规设置 > 项目ID中显示。

将shadow_project_id和publisher_project_id发送给您的帐户经理以获取以下OAuth 2.0客户端参数：

• client_id — OAuth 2.0客户端ID
• 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请求，并指定平台和用户标识符（参数platform和user_id）。如果未找到符合所传custom ID的用户，则创建新用户。
4. 艾克索拉登录管理器服务器向游戏服务器发送一个令牌。

请求示例：

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

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

curl --request POST \
  --url 'https://login.xsolla.com/api/users/login/server_custom_id?publisher_project_id=publisher_project_id' \
  --header 'content-type: application/json' \
  --header 'x-server-authorization: server_token' \
  --data '{"server_custom_id":"secret_value","social_profile":{"platform":"xbox","user_id":"123"}}'

响应示例：

HTTP/1.1 200 OK
Content-Type: application/json

{
  "token": "<platform_user_token>"
}

静默认证

按照静默认证说明进行设置。在游戏服务器上使用静默认证调用来创建平台帐户。

如果使用静默认证调用，则将可从不同平台获取用户好友列表。支持静默认证的平台列表见该高级诀窍。

获取关联码

要获取关联码：

1. 使用Create code for linking accounts调用。将在主帐户中认证过程中收到的用户令牌传入该调用。
2. 向用户显示收到的关联码。

请求示例：

POST https://login.xsolla.com/api/users/account/code HTTP/1.1
Authorization: Bearer <main_user_token>

curl --request POST \
  --url https://login.xsolla.com/api/users/account/code \
  --header 'authorization: main_user_token'

响应示例：

HTTP/1.1 200 OK
Content-Type: application/json

{
  "code": "123456"
}

关联帐户

使用Link accounts by code调用将平台帐户链接至主帐户。将code参数连同用户在控制台平台上输入的关联码值传入该调用。

请求示例：

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

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

curl --request POST \
  --url https://login.xsolla.com/api/users/account/link \
  --header 'content-type: application/json' \
  --header 'x-server-authorization: server_token' \
  --data '{"code":"123456","platform":"xbox","publisher_project_id":44056,"user_id":"123"}'

响应示例：

HTTP/1.1 204 No Content