个性化商品目录

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

  • 使用在己侧创建的属性对目录进行个性化（适用于使用支付中心访问令牌来授权用户的合作伙伴）
  • 在艾克索拉侧以JSON机制指定属性验证规则并向用户添加属性（适用于使用艾克索拉登录管理器来授权用户的合作伙伴）
  • 创建目录显示规则
  • 为具有不同属性值的用户获取商品目录
注：
本教程不涉及设置个性化促销活动。使用艾克索拉登录管理器来授权用户时，您可以使用与个性化商品目录同样的方式来设置个性化促销活动。

前提条件

开始前，请确保：

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

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

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

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

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

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

注：
您可以：
  • 为用户属性创建一个JSON机制，并仅传递在该JSON机制中指定的属性。具体方法是，在JSON机制中，在additionalProperties对象中指定false。这样将自动验证所指定的属性。
  • 为用户属性创建一个JSON机制，并传递在该JSON机制中指定的属性以及该JSON机制中未提及的其他属性。具体方法是，在JSON机制中，在additionalProperties对象中指定true。这样将自动验证所指定的属性。
  • 不为用户属性创建一个JSON机制。此情况下，可传递任何属性且不执行属性验证。
对于商品目录个性化，建议在JSON机制的properties对象中指定属性及其类型，以确保自动验证属性键和值。

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

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

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

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

  1. 您可以同时更新一个或多个属性的值。但这不适用于JSON机制中指定为必需的属性 — 如未指定必需的属性值，将无法调用属性更新API方法。
注：
  • 如使用通过自定义ID进行认证方法，请在授权用户时直接传入实际属性值。在该方法中，您可以传递包含用户属性当前值的数组。
注：
建议创建只读的服务器属性。方法是传入参数值“attr_type”: “server”和“read_only”: “true”。

个性化设置示例

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

注：
Medium Crystal Set和MyTestGame仅为示例名称。您可以使用您项目中的商品和属性来配置目录个性化。
我们还提供了在艾克索拉侧（通过艾克索拉登录管理器进行用户授权）和在合作伙伴侧（通过支付中心访问令牌进行用户授权）创建属性的参考方案。对于支付中心访问令牌方案，可直接前往创建目录显示规则。

创建属性机制

使用游戏名称和和购买数的相应属性添加JSON机制。方法是在机制中指定以下项：
  • “string”类型的“game”属性 — 用户购买的游戏的名称。“game”属性标记为必需。如不传入“game”属性则无法调用属性更新方法。

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

机制示例：
Copy
Full screen
Small screen
  • json

{
	"$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。
注：

API方法中的参数名称在不同产品中可能不同：

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


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

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

Copy
Full screen
Small screen
  • json
{
  "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
  1. 指定符合条件时应显示的商品。下例中，Medium Crystal Set对拥有MyTestGame的用户显示。
  1. 检查规则，激活并保存。

获取令牌

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

对添加了值为MyTestGame的game属性的用户获取其令牌。
您可以在无用户参与的客户端或服务器侧成功用户授权后获取艾克索拉登录管理器JWT。方法是使用以下艾克索拉登录管理器授权方法之一：

获取支付中心访问令牌

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

示例请求正文：

Copy
Full screen
Small screen
  • json

{
  "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还是支付中心访问令牌进行授权）。

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

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

响应包含三个商品：

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


您可以测试在属性值不符合规则指定条件的情况下获取商品目录时的响应。测试时，您可以在使用通过自定义ID进行认证方法获取令牌时直接传入属性。
注：
此方法仅适用于使用通过自定义ID进行认证来授权的的用户。
使用通过自定义ID进行认证方法获取用户JWT，并在attributes数组中传入game属性和值OtherGame：
Copy
Full screen
Small screen
  • json
"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数组如下所示：

Copy
Full screen
Small screen
  • json

"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就会包含在响应中：

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

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

响应包含三个商品：

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


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

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

本文对您的有帮助吗？
谢谢！
我们还有其他可改进之处吗？ 留言
非常抱歉
请说明为何本文没有帮助到您。 留言
感谢您的反馈！
我们会查看您的留言并运用它改进用户体验。
为此页面评分
为此页面评分
我们还有其他可改进之处吗？

不想回答

感谢您的反馈！
上次更新时间: 2024年4月17日

发现了错别字或其他内容错误？ 请选择文本，然后按Ctrl+Enter。

报告问题
我们非常重视内容质量。您的反馈将帮助我们做得更好。
请留下邮箱以便我们后续跟进
感谢您的反馈！