个性化商品目录

本教程将介绍如何完成以下任务：

• 使用在己侧创建的属性对目录进行个性化（适用于使用支付中心访问令牌来授权用户的合作伙伴）
• 在艾克索拉侧以JSON机制指定属性验证规则并向用户添加属性（适用于使用艾克索拉登录管理器来授权用户的合作伙伴）
• 创建目录显示规则
• 为具有不同属性值的用户获取商品目录

前提条件

开始前，请确保：

• 已创建游戏内商品或游戏密钥目录，个性化将针对它们进行配置。
• 已了解用户属性部分（适用于使用艾克索拉登录管理器来授权用户的合作伙伴）。
• 已在登录管理器项目设置的用户数据库 > 用户部分添加了用户，这样才能对它们添加属性（适用于使用艾克索拉登录管理器来授权用户的合作伙伴）。

使用支付中心访问令牌授权用户时的个性化

如使用支付中心访问令牌来授权用户，可在获取令牌时传入属性。此情况下，请完成以下操作来设置个性化：

1. 在您的系统中创建属性。
2. 在您的系统中向用户添加属性。
3. 实现用户属性值在游戏中发生改变时更新属性值的逻辑。
4. 使用您的属性创建目录显示规则。
5. 获取支付中心访问令牌时传入属性。
6. 在请求商品目录的方法中使用收到的令牌。

使用艾克索拉登录管理器授权用户时的个性化

如使用艾克索拉登录管理器来授权用户，需：

1. 在艾克索拉侧为用户属性创建一个JSON机制并在其中指定属性（可选）。

2. 使用Login API向用户添加属性并更新属性值。
3. 使用创建的属性创建目录显示规则。
4. 实现获取用户的JWT。您可以在此示例中找到获取JWT的方法列表。
5. 在请求商品目录的方法中使用收到的令牌。

有几种向用户添加属性的方式：

• 使用属性更新方法：
  • 从服务器更新用户属性
  • 从服务器更新用户的只读属性

1. 使用这些方法向用户添加属性并更新属性值。要个性化目录，必需保持属性值的更新：用户属性值在游戏中发生改变时，在艾克索拉中更新属性值。

1. 示例：用户到达新等级、完成了一个任务或进行了一次购买。

1. 您可以同时更新一个或多个属性的值。但这不适用于JSON机制中指定为必需的属性 — 如未指定必需的属性值，将无法调用属性更新API方法。

• 如使用通过自定义ID进行认证方法，请在授权用户时直接传入实际属性值。在该方法中，您可以传递包含用户属性当前值的数组。

个性化设置示例

本例演示如何设置目录个性化：Medium crystal set商品仅对购买了MyTestGame游戏的用户显示。

创建属性机制

• “string”类型的“game”属性 — 用户购买的游戏的名称。“game”属性标记为必需。如不传入“game”属性则无法调用属性更新方法。

• “integer”类型的“purchase_number”属性 — 用户购买的数量。

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"title": "Example",
	"description": "JSON Schema description.",
	"properties": {
		"game": {
			"description": "Name of the game played by a user.",
			"type": "string"
		},
		"purchase_number": {
			"description": "The number of purchases the user made.",
			"type": "integer"
		}
	},
	"additionalProperties": false,
	"required": [
		"game"
	],
	"type": "object"
}

向用户添加属性

请使用从服务器更新用户的只读属性方法向用户数据库中的用户添加属性。

在从服务器更新用户的只读属性方法中，必须指定：

• 服务器令牌。
• 用户属性值。
• user_id — 在发布商帐户中登录管理器项目设置的用户数据库 > 用户部分中指定的用户标识符。
• publisher_id — 在以下位置指定的商户ID：
  • 在公司设置 > 公司部分。
  • 在发布商帐户任意页面的浏览器地址栏的URL中。URL的格式如下：https:​//publisher.xsolla.com/<merchant ID>/<Publisher Account section>。
• publisher_project_id — 可在发布商帐户中项目名称旁边找到的项目ID。

使用生成JWT方法初步获得服务器令牌。

然后，前往从服务器更新用户的只读属性方法。

含attributes数组的请求正文格式如下：

{
  "attributes": [
    {
      "key": "game",
      "permission": "private",
      "value": "MyTestGame"
    },
 {   
     "key": "purchase_number",
      "permission": "private",
      "value": "30"
    }

  ],
  "publisher_id": 000000,
  "publisher_project_id": 000000
}

执行该请求的结果是，没有任何属性的用户现在有包含指定值的属性了：

创建目录显示规则

设置一条规则，仅对购买了MyTestGame的用户显示Medium Crystal Set商品。

具体方法：

1. 在发布商帐户中，前往商店 > 目录管理 > 目录显示规则。
2. 单击创建规则，然后完成必填字段：
   1. 用户属性字段中的属性键 — game
   2. 类型 — string
   3. 比较符 — equal to
   4. 值 — MyTestGame

3. 指定符合条件时应显示的商品。下例中，Medium Crystal Set对拥有MyTestGame的用户显示。

4. 检查规则，激活并保存。

获取令牌

获取艾克索拉登录管理器JWT

• 通过用户名和密码进行认证
• 通过社交网络进行认证
• 通过邮箱免密认证
• 通过手机号码免密认证
• 通过设备ID进行认证
• 通过自定义ID进行认证
• 以及JWT或OAuth.2.0方法组下用于获取用户令牌的其他方法

获取支付中心访问令牌

使用需要的属性获取支付中心访问令牌。方法是在创建令牌方法的attributes对象中传入“game”: “MyTestGame”。

示例请求正文：

{
  "settings": {
    "currency": "USD",
    "language": "en",
    "project_id": 000001,
    "ui": {
      "size": "medium"
    }
  },
  "user": {
    "email": {
      "value": "email@example.com"
    },
    "id": {
      "value": "user_2"
    },
    "name": {
      "value": "John Smith"
    },
    "attributes": {
      "game": "MyTestGame"
    }
  }
}

获取商品目录

使用艾克索拉登录管理器JWT获取商品目录

对于添加了game属性且值为MyTestGame的用户，用该用户的令牌获取目录。方法是，在获取虚拟物品列表方法中指定以下项：

• 在授权头中获得的用户JWT
• 作为路径参数的发布商帐户中的项目ID

响应包含三个商品：

• Empire Key
• Small crystal pack
• Medium crystal set（即个性化规则配置的对象）

"attributes": [
{
    "attr_type": "server",
    "key": "game",
    "permission": "private",
    "value": "OtherGame",
    "read_only": true
 },
{
    "attr_type": "server",
    "key": "purchase_number",
    "permission": "private",
    "value": "30",
    "read_only": true
  }
]

使用获得的令牌的获取虚拟物品列表方法返回两个商品：Empire Key和Small crystal pack，而应用了个性化规则的Medium crystal set则不在响应中。

作为对比，现在再传入game属性和值MyTestGame。

对于有游戏MyTestGame的用户，通过自定义ID进行认证方法中的attributes数组如下所示：

"attributes": [
{
    "attr_type": "server",
    "key": "game",
    "permission": "private",
    "value": "MyTestGame",
    "read_only": true
 },
{
    "attr_type": "server",
    "key": "purchase_number",
    "permission": "private",
    "value": "30",
    "read_only": true
  }
]

在获取虚拟物品列表方法中请求商品目录时请指定获得的令牌。

这样，Medium Crystal Set就会包含在响应中：

使用支付中心访问令牌获取商品目录

要获取个性化商品目录，需在获取虚拟物品列表方法中指定以下项：

• 在授权头中获得的支付中心访问令牌
• 作为路径参数的发布商帐户中的项目ID

响应包含三个商品：

• Empire Key
• Small crystal pack
• Medium crystal set（即个性化规则配置的对象）

您可以测试在用户没有值为MyTestGame的game属性情况下获取商品目录时的响应。

收到支付中心访问令牌时，请删除attributes对象，然后使用获取虚拟物品列表方法再次请求商品目录。这样响应中就不包含Medium Crystal Set了：