Digital Distribution Hub

概览

Digital Distribution Hub是一个将游戏开发者与众多分发合作伙伴联结的解决方案，这些分发合作伙伴拥有进行游戏、虚拟物品、虚拟货币和捆绑包分发的自有平台或生态系统。

分发合作伙伴 — 可分发游戏和游戏内商品并具有自己的商店和账单系统的数字平台或生态系统。艾克索拉分发合作伙伴示例：

聚合多项服务的超级应用
银行应用程序
电信及网络服务提供商
自助终端机
返利和奖励活动提供商
电商市场

对于游戏开发者的好处：

与高速增长的分发合作伙伴建立直接联系，从而扩大游戏的受众。
让游戏进入具有特定用户基础的新分发渠道，从而增加营收。
通过广告和横幅提升游戏在第三方平台上的自发发现流量。

对于分发合作伙伴的好处：

通过提供更多游戏内容增加用户的忠诚度。用户可以直接在应用或服务中购买游戏密钥、虚拟物品、虚拟货币和捆绑包。
通过快速流行的游戏行业留存老用户，吸引新用户。
通过销售游戏行业主要发行商的游戏密钥、虚拟物品和虚拟货币赚取佣金，从而提高营收。

运行机制

游戏密钥的用户购买流程

虚拟物品和虚拟货币的用户购买流程

交互过程

游戏开发者在发布商帐户中创建项目，然后上传游戏密钥、虚拟物品、虚拟货币和捆绑包。
分发合作伙伴请求用户数据：
- 销售游戏时 — 请求用户邮箱地址以发送密钥和收据
- 销售游戏内商品时 — 请求用户游戏内ID以向该ID添加商品，以及用户的邮箱地址以发送收据
用户在分发合作伙伴界面输入以下数据：
- 如购买游戏 — 输入邮箱地址以接收密钥和收据
- 如购买游戏内商品 — 输入游戏内ID以将商品添加到物品库，以及邮箱地址以接收收据
分发合作伙伴调用创建用户令牌方法并传入邮箱地址（必需）和用户ID（销售虚拟物品、虚拟货币和捆绑包时为必需）作为参数。
艾克索拉检查用户是否在游戏中存在（如游戏开发者设置了Webhook）。对于销售虚拟物品和虚拟货币，Webhook为必需，但对销售游戏密钥非必需。
艾克索拉创建一个包含用户数据的令牌并将其发送给分发合作伙伴。
分发合作伙伴请求游戏目录或游戏内商品目录。
艾克索拉在响应中返回请求的目录。
分发合作伙伴收到该目录并将其向用户显示。
用户进行购买。分发合作伙伴创建购物车。
分发合作伙伴发送用户购物车以创建订单。
艾克索拉返回订单ID以及含折扣和税的购物车价格。
分发合作伙伴将购物车总价向用户显示。
如用户前往支付，分发合作伙伴进行扣款并显示支付状态页面。
分发合作伙伴通知艾克索拉订单已支付并发送支付信息。
艾克索拉将购买信息通知游戏开发者。
购买了游戏的用户收到包含购买详情的邮件并可以激活游戏密钥。如用户购买的是虚拟物品或虚拟货币，将添加到其物品库。

游戏开发者侧的集成

如何连接Digital Distribution Hub

要通过分发渠道推广您的游戏：

在发布商帐户中连接商店并下载：
- 游戏密钥或游戏密钥捆绑包（如销售游戏密钥）；
- 虚拟物品、虚拟货币或捆绑包（如销售游戏内商品）。
设置Webhook。
联系您的客户成功经理或发送邮件至 csm@xsolla.com为您的项目激活Digital Distribution Hub。

如果您还不是艾克索拉合作伙伴，但对于合作以及连接Digital Distribution Hub有兴趣，请发送邮件至 business@xsolla.com。

如何设置Webhook

要实现以下事项，设置Webhook为必需：

根据游戏中的用户ID验证用户并显示个性化目录
验证用户并将其所购游戏内商品加入其物品库
将艾克索拉侧的交易ID与游戏开发者系统中的交易ID关联
在订单中传入额外用户参数
接收购买通知

要设置Webhook：

在发布商帐户中打开您的项目。
在侧边栏中单击项目设置，然后前往Webhooks。
将Webhooks开关设置为开。
指定Webhook URL。
默认会生成一个用于项目Webhook签名的密钥。如要生成一个新密钥，请单击刷新图标。
单击保存设置。

对于分发虚拟物品和虚拟货币，设置Webhook为必需。如没有Webhook，游戏内商品将无法添加到用户的物品库。

用户验证

艾克索拉发送一个用户验证Webhook来验证游戏中是否存在该用户。通过用户验证可以：

向用户显示个性化的目录（如在响应中传入了用户属性）
完成购买后将商品添加到用户的物品库

为确认收到Webhook，您的服务器应返回：

不带消息正文的HTTP代码204（如游戏中存在该用户）;
描述问题的HTTP代码400（如果指定用户未找到或传入的签名无效）。

关于Webhook机制的详细列表及示例，请参阅API参考了解详细信息。

在响应中，您可以在custom_parameters对象中传入其他交易参数。

Copy

Full screen

Small screen

 1{
 2"$schema": "http://json-schema.org/draft-04/schema#",
 3"type": "object",
 4"additionalProperties": false,
 5"properties": {
 6  "user_attributes": {
 7    "type": "object",
 8    "required": false,
 9    "minProperties": 1,
10    "maxProperties": 100,
11    "patternProperties": {
12      "^[\\w-_.]{1,255}$": {
13        "oneOf": [
14          {
15            "type": "integer"
16          },
17          {
18            "type": "string",
19            "minLength": 1,
20            "maxLength": 255
21          },
22          {
23            "type": "array",
24            "items": {
25              "type": "string",
26              "maxLength": 255
27            },
28            "minItems": 1,
29            "maxItems": 1000
30          }
31        ]
32      }
33    },
34    "additionalProperties": false
35  }
36}
37}

响应示例：

Copy

Full screen

Small screen

1{
2  "user_attributes": {
3    "age": 18,
4    "level": 1,
5    "game": "WoW",
6    "is_baned": false,
7    "registration_date": "2022-01-01"
8  }
9}

交易ID的关联

如使用外部ID（您自己系统上的交易ID）并希望将其与艾克索拉侧的交易ID关联或传入额外交易参数，请实现以下Webhook处理：

Copy

Full screen

Small screen

 1{
 2  "$schema": "http://json-schema.org/draft-07/schema#",
 3  "type": "object",
 4  "additionalProperties": false,
 5  "properties": {
 6    "notification_type": {
 7      "type": "string"
 8    },
 9    "order_id": {
10      "type": "integer"
11    },
12    "project_id": {
13      "type": "integer"
14    },
15    "user": {
16      "type": "object",
17      "properties": {
18        "external_id": {
19          "type": "string"
20        },
21        "email": {
22          "type": "string"
23        }
24      }
25    },
26    "items": {
27      "type": "array",
28      "items": {
29        "type": "object",
30        "properties": {
31          "item_id": {
32            "type": "integer"
33          },
34          "sku":  {
35            "type": "string"
36          },
37          "quantity": {
38            "type": "integer"
39          },
40          "type": {
41            "type": "string"
42          }
43        }
44      }
45    }
46  }
47}

请求示例：

Copy

Full screen

Small screen

 1{
 2  "notification_type": "create_external_transaction",
 3  "order_id": 1,
 4  "project_id": 51336,
 5  "user": {
 6    "external_id": "user_id",
 7    "email": "public_email@test.com"
 8  },
 9  "items": [
10    {
11      "item_id": 101,
12      "sku": "mithril_dagger",
13      "quantity": 2,
14      "type": "virtual_good"
15    }
16  ]
17}

在响应中，您可以在custom_parameters对象中传入其他交易参数。

响应:

Copy

Full screen

Small screen

 1{
 2  "id": "validation_transaction_info_response.json",
 3 "$schema": "http://json-schema.org/draft-07/schema#",
 4 "description": "DDH Project Transaction Info Response",
 5 "type": "object",
 6 "additionalProperties": true,
 7 "properties": {
 8   "id": {
 9     "type": "string",
10     "minLength": 1
11   },
12  "custom_parameters": {
13     "type": "object",
14     "additionalProperties": true,
15     "minProperties": 1,
16     "maxProperties": 200
17   }
18 }
19}

响应示例：

Copy

Full screen

Small screen

1{
2    "id":"123"
3}

用于关联交易ID的Webhook参数列表：

参数	类型	描述
notification_type	string	通知类型。
order_id	integer	订单ID。
project_id	integer	加载游戏密钥或游戏密钥捆绑包、游戏内商品或游戏内商品捆绑包的项目的ID。
user.external_id	string	游戏开发者侧的用户ID。
items	string	用户所购物品的清单。
items.sku	string	商品的唯一ID。
items.quantity	integer	商品数量。
items.type	string	商品类型。接受`virtual_good`、`virtual_currency`、`physical_good`、`unit`值。`unit`类型用于游戏。
items.unit_items	array	包含游戏数据的数组。
items.unit_items.type	string	游戏密钥套餐的商品类型。接受`game_key`值。
items.unit_items.sku	string	游戏密钥套餐唯一ID。对于具体某平台上的游戏，值的格式为`sku_drm`。例如对于Steam上sku为110101的游戏，该值为`“sku”: “110101_steam”`。

购买通知

用户支付所购商品后，您将获得：

包含支付信息的支付Webhook。
购物车内容Webhook，其中包含要添加到物品库的商品的信息。

分发合作伙伴侧的集成

如有兴趣集成Digital Distribution Hub，请发送邮件至 psbusiness@xsolla.com联系集成经理，获取与Digital Distribution Hub API交互所需的参数：

集成过程中，需发送支付成功或取消支付的通知（步骤9）。要在艾克索拉侧正确处理通知，请告诉您的艾克索拉经理您发送通知的服务器IP地址。如IP地址发生更改，请尽快告知该经理。

分发合作伙伴无需创建发布商帐户即可使用Digital Distribution Hub API。但对游戏开发者而言，创建发布商帐户为必需，这样才能使用用于游戏密钥和游戏内商品销售的API方法。

要在您的应用或服务中分发游戏，请实现以下游戏购买逻辑：

显示输入以下信息的表单：
- 用户邮箱地址 — 销售游戏时
- 用户邮箱地址和游戏内ID — 销售游戏内商品时

销售游戏和游戏内商品时邮箱地址字段为必填。艾克索拉向用户指定的游戏地址发送包含支付信息的收据。

用户ID用于销售虚拟物品、虚拟货币及虚拟物品和货币捆绑包的项目。在该情况下，还必须提示用户输入其在注册游戏时收到的ID。

示例：

传入收到的用户数据：
- 用户邮箱地址。始终为必需。
- 用户的游戏内ID。销售游戏内商品时为必需。

这些数据用于验证用户在游戏中是否存在及接收授权令牌。

使用创建用户令牌方法。在请求中传入参数：

参数	类型	描述
project_id	integer	加载游戏密钥或游戏密钥捆绑包、游戏内商品或游戏内商品捆绑包的项目的ID。
user.email	string	用户邮箱地址。
user.id	string or null	游戏中的唯一用户标识符。

包含用户数据的授权令牌在响应中返回。

导入：
- 游戏目录（使用获取游戏列表方法）;
- 虚拟物品目录（使用获取虚拟物品列表方法）;
- 虚拟货币目录（使用获取虚拟货币列表方法）;
- 游戏或游戏内商品捆绑包目录（使用获取捆绑包列表方法）。

在请求中传入步骤2中收到的令牌和以下参数：

参数	类型	描述
project_id	integer	加载游戏密钥或游戏密钥捆绑包、游戏内商品或游戏内商品捆绑包的项目的ID。

在您的店面中显示游戏和游戏内商品目录。在界面中实现以下项的选择能力：
- 游戏密钥和游戏发布平台的数量；
- 虚拟物品的数量；
- 虚拟货币的数量或含固定数量货币的虚拟货币套餐的数量；
- 捆绑包的数量。

如使用购物车，则商品的数量可在用户购物车中指定。如不使用购物车，则可在目录中实现商品数量的选择。

在购物车中指定商品数量的示例：

如不使用购物车，请前往步骤6并使用使用指定商品创建订单方法。

要将商品加入购物车，请使用在购物车里添加商品方法。

用户可以在一个订单中添加、删除商品或更改数量。您可以使用以下方法更新购物车：
- 在购物车里添加商品方法，每次用户更改购物车内容时使用。
- 用于更新购物车及删除商品的方法：

此情况中，更新购物车后请使用获取当前用户的购物车。

在购物车加购和更新购物车方法的请求中传入以下参数：

参数	类型	描述
project_id	integer	加载游戏密钥或游戏密钥捆绑包、游戏内商品或游戏内商品捆绑包的项目的ID。
items.sku	string	游戏开发者在发布商帐户中指定的唯一商品ID。
items.quantity	integer	商品数量。
items.type	string	商品类型。接受`virtual_good`、`virtual_currency`、`physical_good`、`unit`值。`unit`类型用于游戏。
items.unit_items	array	包含游戏数据的数组。
items.unit_items.type	string	游戏密钥套餐的商品类型。接受`game_key`值。
items.unit_items.sku	string	游戏开发者在发布商帐户中指定的游戏密钥套餐唯一ID。对于具体某平台上的游戏，值的格式为`sku_drm`。例如对于Steam上sku为110101的游戏，该值为`“sku”: “110101_steam”`。

调用在购物车里添加商品或获取当前用户的购物车后，响应中将返回所选商品的更新信息，如折扣前后的价格、奖励品等。

要创建购物车订单并支付，请调用使用当前购物车中的所有商品创建订单方法。在请求中传入以下参数：

参数	类型	描述
project_id	integer	加载游戏密钥或游戏密钥捆绑包、游戏内商品或游戏内商品捆绑包的项目的ID。
geotype	number	艾克索拉侧的分发合作伙伴ID。
currency	string	订单货币。虚拟货币使用SKU，真实货币使用三个字母的ISO 4217代码。

响应将返回订单ID和含税的购物车价格。

您可以使用使用指定商品创建订单方法在不创建购物车的情况下创建订单。该情况下，用户只能购买一种类型的商品。

向用户显示购物车总价。
从您的平台扣取用户钱款。向用户显示支付状态。
发送支付通知。如发生退款或未完成支付，发送支付取消通知。

要在艾克索拉侧正确处理通知，请告诉您的艾克索拉经理您发送通知的服务器IP地址。如IP地址发生更改，请尽快告知该经理。

感谢您的反馈！

我们会查看您的留言并运用它改进用户体验。

上次更新时间: 2025年5月20日

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

概览
运行机制
游戏开发者侧的集成
分发合作伙伴侧的集成

Your browser is not supported. Please try a different browser

Digital Distribution Hub

概览

运行机制

游戏密钥的用户购买流程

虚拟物品和虚拟货币的用户购买流程

交互过程

游戏开发者侧的集成

如何连接Digital Distribution Hub

如何设置Webhook

用户验证

交易ID的关联

notification_type

order_id

project_id

user.external_id

items

items.sku

items.quantity

items.type

items.unit_items

items.unit_items.type

items.unit_items.sku

购买通知

分发合作伙伴侧的集成

project_id

user.email

user.id

project_id

project_id

items.sku

items.quantity

items.type

items.unit_items

items.unit_items.type

items.unit_items.sku

project_id

geotype

currency