概览

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

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

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

对于游戏开发者的好处：

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

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

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

运行机制

游戏密钥的用户购买流程

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

交互过程

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

游戏开发者侧的集成

如何连接Digital Distribution Hub

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

如何设置Webhook

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

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

要设置Webhook：

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

用户验证

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

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

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

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

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

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

{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"additionalProperties": false,
"properties": {
  "user_attributes": {
    "type": "object",
    "required": false,
    "minProperties": 1,
    "maxProperties": 100,
    "patternProperties": {
      "^[\\w-_.]{1,255}$": {
        "oneOf": [
          {
            "type": "integer"
          },
          {
            "type": "string",
            "minLength": 1,
            "maxLength": 255
          },
          {
            "type": "array",
            "items": {
              "type": "string",
              "maxLength": 255
            },
            "minItems": 1,
            "maxItems": 1000
          }
        ]
      }
    },
    "additionalProperties": false
  }
}
}

响应示例：

{
  "user_attributes": {
    "age": 18,
    "level": 1,
    "game": "WoW",
    "is_baned": false,
    "registration_date": "2022-01-01"
  }
}

交易ID的关联

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "notification_type": {
      "type": "string"
    },
    "order_id": {
      "type": "integer"
    },
    "project_id": {
      "type": "integer"
    },
    "user": {
      "type": "object",
      "properties": {
        "external_id": {
          "type": "string"
        },
        "email": {
          "type": "string"
        }
      }
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "item_id": {
            "type": "integer"
          },
          "sku":  {
            "type": "string"
          },
          "quantity": {
            "type": "integer"
          },
          "type": {
            "type": "string"
          }
        }
      }
    }
  }
}

请求示例：

{
  "notification_type": "create_external_transaction",
  "order_id": 1,
  "project_id": 51336,
  "user": {
    "external_id": "user_id",
    "email": "public_email@test.com"
  },
  "items": [
    {
      "item_id": 101,
      "sku": "mithril_dagger",
      "quantity": 2,
      "type": "virtual_good"
    }
  ]
}

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

响应:

{
  "id": "validation_transaction_info_response.json",
 "$schema": "http://json-schema.org/draft-07/schema#",
 "description": "DDH Project Transaction Info Response",
 "type": "object",
 "additionalProperties": true,
 "properties": {
   "id": {
     "type": "string",
     "minLength": 1
   },
  "custom_parameters": {
     "type": "object",
     "additionalProperties": true,
     "minProperties": 1,
     "maxProperties": 200
   }
 }
}

响应示例：

{
    "id":"123"
}

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

购买通知

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

分发合作伙伴侧的集成

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

• geotype；
• project_id；
• distribution_hub_id和api_key。

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

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

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

1. 示例：

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

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

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

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

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

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

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

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

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

1. 在目录中指定商品数量的示例：

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

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

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

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

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

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

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

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

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

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