如何设置跨平台物品库

运行机制

跨平台物品库允许游戏开发者同步一个游戏在不同平台(Steam、EGS、PlayStation、XBox等)上的用户物品库、管理用户物品库和余额,以及收集相关数据等。

同步物品库需要以下步骤:

  1. 用户将其在不同平台上的帐户与主帐户关联,后者用于识别玩家在不同平台上的身份。
  2. 艾克索拉提供将平台帐户与主帐户关联和跨平台同步物品库的机制。

本解决方案包含以下组件:

  • 游戏客户端
  • 游戏服务器
  • 提供帐户关联UI的Web应用程序
  • 提供主帐户和关联机制的艾克索拉登录管理器
  • 存储用户物品库的艾克索拉玩家物品库

用户流程

要将平台帐户(Steam或EGS)关联到主帐户,需使用艾克索拉登录管理器帐户或使用在主机平台上关联帐户的算法实现用户在游戏中的认证。

将游戏主机帐户与主帐户关联的算法如下:

  1. 玩家首次在游戏主机平台上进入游戏。
  2. 游戏显示将平台帐户与主帐户关联的提示消息。
  3. 如果玩家确认关联:
    1. 玩家将重定向到一个小应用(如游戏网站或移动应用),玩家在其中可进行身份认证或创建主帐户。
    2. 在应用中成功认证后,玩家将收到一个由字母和数字组成的帐户关联码。
  4. 玩家返回游戏的主机版本并输入该关联码。
  5. 主帐户即与平台帐户关联,且游戏主机显示确认消息。
  6. 玩家在平台上的物品库与主帐户关联的物品库同步。

Note:
物品库中的付费货币(使用真实货币购买的货币)不会同步。根据主机平台的规定,通过PlayStation、Xbox和Nintendo Switch游戏主机购买的付费货币不会堆叠,而是单独存储。
Notice:
帐户一旦关联后即不可取消关联。此外,如果用户首次进入游戏时拒绝了帐户关联,则以后也无法进行关联。

适用对象

计划进行跨平台游戏发布的游戏开发者,希望让玩家可跨平台访问其购买物及奖励,从而建立忠实的玩家基础。

Note:
本解决方案只能在游戏在第二发布平台上发布之前进行连接。例如,如果游戏已经在PC平台上发布且即将在PlayStation上发布,则必须在游戏在PlayStation上发布之前连接跨平台物品库。

如何获取

要连接跨平台物品库:

  1. 连接玩家物品库。实现基本认证以与服务器方法交互,实现基于OAuth 2.0的艾克索拉登录管理器认证以与客户端方法交互。访问Login API方法及实现帐户关联方法也需要基于OAuth 2.0的认证。
  2. 实现帐户关联UI,包括:
    1. 基于游戏服务器的认证物品库管理
    2. 基于游戏客户端的认证物品库管理
    3. 帐户关联方法

Note:
如果已在游戏服务器测实现了帐户同步,则只需要设置玩家物品库即可同步用户物品库。

帐户关联UI

帐户关联UI应具备以下功能:

  • 显示将平台帐户与主帐户关联的提示消息
  • 同意或拒绝关联帐户
  • 提交关联码(如用户同意关联)
  • 显示用于关联帐户的移动或Web应用的URL

在主帐户中认证用户的机制如下:

  1. 登录管理器小组件与应用集成。
  2. 用户通过小组件进行认证时会传给应用一个JWT。实现将JWT从应用传给获取关联码的方法以及在应用UI中显示关联码的方法。
  3. 在游戏服务器侧实现通过JWT认证
  4. 实现当用户进入游戏的主机版本并提交了帐户关联码时,将令牌、主机平台上的user_id和平台ID传给关联主帐户的方法。

Note:
如要将现有帐户导出至艾克索拉存储,请联系您的项目帐户经理或发送邮件至am@xsolla.com与我们联系。

游戏服务器上的认证

要访问在游戏服务器上管理玩家物品库的Login API方法,需设置OAuth 2.0认证并获取服务器访问令牌

Note:
要获取client_idclient_secret,请联系您的项目帐户经理或发送邮件至am@xsolla.com与我们联系。

请求

Copy
Full screen
Small screen
<?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);

响应

Copy
Full screen
Small screen
{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",           
    "token_type":"bearer",
    "expires_in":3600,
    "scope": ""
}

在游戏服务器上管理玩家物品库

物品库管理方法包括以下服务器方法:

必须将用户在平台上的user_id和平台ID传给这些方法。

游戏客户端上的认证

实现Auth by custom ID API方法以在游戏客户端中管理用户物品库。在请求中传入以下参数:

  • server_custom_id — 游戏中的唯一用户标识符
  • social_profile->user_id — 平台上的唯一用户标识符

请求

Copy
Full screen
Small screen
<?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);

响应

Copy
Full screen
Small screen
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Note:
也可使用User tokenization方法获取JWT。

在游戏客户端中管理玩家物品库

物品库管理方法包括以下服务器方法:

要在主机平台上管理物品库:

  1. 实现将平台ID传给客户端的方法以根据主机平台的规定在主机发布平台上存储付费货币余额。
  2. 在游戏服务器上实现以下步骤以在主机客户端中管理用户物品库:
    1. 游戏收到一个服务器访问令牌以将用户令牌化。
    2. 游戏收到根据用户在平台上的user_id和平台ID生成的JWT。
    3. 游戏将JWT传入指定的客户端方法。

帐户关联方法

获取关联码

实现Create code for linking accounts API方法获取关联码并传给用户。

请求

Copy
Full screen
Small screen
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);

响应

Copy
Full screen
Small screen
{
  "code": "123456"
}

关联主帐户

实现Link accounts by code API方法,其中:

  • code — 关联码
  • publisher_project_id — 发布商帐户中的项目ID
  • user_id — 平台上的用户标识符

调用该方法之前,请确保已完成下列步骤:

  1. 已实现UI来显示帐户关联码以及关联码的输入表单。
  2. 已实现获取服务器访问令牌的方法。
  3. 已实现获取关联码的方法。

Note:
也可以使用Connect game account to Xsolla API方法将平台帐户关联到主帐户。

请求

Copy
Full screen
Small screen
<?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);

响应

Copy
Full screen
Small screen
204 OK

平台列表

平台平台ID注释
PlayStation Networkplaystation_network-
XBox Livexbox_live-
PC独立pc_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-