UDP 包参考
编辑器 UI
UDP Settings
UDP Settings Inspector 管理 Unity 项目和 UDP 客户端之间的连接。要启用 UDP Settings 窗口，必须安装 UDP 包并将 Unity 项目链接到 UDP 客户端。
要在 Unity 编辑器中访问 UDP Settings 窗口，选择 Window > Unity Distribution Portal > Settings。
| UDP 设置 | 描述 |
|---|---|
| Pull | 将上次保存在 UDP 服务器上的信息找回（拉取）到编辑器中。 以下信息将同步： - 游戏名称 - 设置 - UDP 沙盒测试帐户 - IAP 目录（如果仅使用 UDP 包） 这将覆盖编辑器中所有未保存的更改。 |
| Push | 将更改保存（推送）到 UDP 服务器。 以下信息将同步： - 游戏名称 - 设置 - UDP 沙盒测试帐户 - IAP 目录（如果你直接在 UDP Settings 窗口中定义了 IAP 目录） |
| Game Title | 输入游戏名称，然后按 Push 进行保存。该字段会与 UDP 控制台同步。 默认情况下以及在首次加载游戏时，Game Title 字段中会填充游戏 ID（请参阅设置）。 |
| Unity Project ID | 这是你的 Unity 项目 ID，现在已链接到 UDP 客户端 ID。此字段不可编辑。 |
| IAP Catalog | 对于 UDP 包实现，此处将显示 IAP 目录字段。 对于 Unity IAP 实现，此处将显示 Open Catalog 按钮。 从 Unity 编辑器 2020.1 版开始，IAP 目录在单独的窗口中显示。 |
| Settings | 包含其他游戏设置。 |
| UDP Sandbox Test Accounts | 包含 UDP 沙盒测试帐户的设置。 |
IAP Catalog
在 IAP Catalog 部分中可以为 UDP 定义 IAP 商品。要添加新商品，请选择 Add new IAP。 下图显示了在使用 UDP 包时的 IAP Catalog 部分。
下表介绍了 IAP Catalog 部分的字段。
| 字段 | 描述 |
|---|---|
| Product ID | 用于标识 IAP 商品的唯一 ID。 Product ID 必须满足以下要求： - 以字母或数字开头 - 仅包含字母、数字、点 (.) 和下划线 (_) - 不得使用大写字母 |
| Name | IAP 商品的名称。 |
| Type | 指示 IAP 商品是否为消耗品。 |
| Price | IAP 商品的价格（美元 USD）。可在 UDP 控制台中设置其他货币的价格。 必须指定一个价格，才能让玩家在游戏中购买商品。 |
| Description | IAP 商品的简短描述。 该字段仅支持单一语言（英语）的描述。可在 UDP 控制台中添加更多语言。 |
如果 IAP 商品有任何未保存的更改，则会显示 edited 标签。同步 IAP 商品后，此标签会消失。
注意：如果使用单独的 Unity IAP 包，请选择 Window > Unity Distribution Portal > IAP Catalog，然后在单独的 IAP Catalog 窗口中定义 IAP 商品。
Settings
Settings 部分包含从 UDP 控制台同步的其他设置。 Callback URL 是唯一可编辑的设置。按 Push 保存所有更改。
| 字段 | 功能 | 可编辑 |
|---|---|---|
| Game ID | 游戏的标识符 | 否 |
| Client ID | UDP 客户端标识符 | 否 |
| Client Key | 在初始化 UDP SDK 时使用 | 否 |
| Client RSA Public Key | 用于验证回调通知 | 否 |
| Client Secret | 这是 Unity 密钥，用于为游戏发送到 UDP 服务器的请求进行签名 | 否 |
| Callback URL | 指定接收回调通知的服务器的 URL | 是 |
UDP Sandbox Test Accounts
在 UDP Sandbox Test Accounts 部分中可以添加 UDP 沙盒的登录凭据。这是在 UDP 沙盒环境中测试游戏所必需的信息。也可以在 UDP 控制台中设置这些凭据。
| 字段 | 功能 | 可编辑 |
|---|---|---|
| 沙盒测试帐户的电子邮件地址。用作登录名。 | 是 | |
| Password | 测试帐户的密码。 | 是 |
UDP SDK
UDP SDK 数据结构
本节将介绍 UDP SDK 的类。
UserInfo
| 字段名称 | 类型 | 描述 |
|---|---|---|
| Channel | string | PartnerStore 名称，由 UDP 生成 |
| UserId | string | 从 PartnerStore 返回的用户 ID（可选） |
| UserLoginToken | string | 从 PartnerStore 返回的用户登录令牌（可选） |
Inventory
| public function | 返回 | 描述 |
|---|---|---|
| GetPurchaseInfo(string productId) | PurchaseInfo | 获取给定 productId 的 PurchaseInfo |
| GetProductInfo(string productId) | ProductInfo | 获取给定 productId 的 ProductInfo |
| HasPurchase(string productId) | bool | 检查给定 productId 是否存在未消耗的购买商品 |
| HasProduct(string productId) | bool | 检查给定 productId 是否存在商品 |
| GetPurchaseDictionary() | Dictionary<string, PurchaseInfo> | 以 productId 形式获取购买信息 - PurchaseInfo 字典 |
| GetPurchaseList() | List<PurchaseInfo> | 以列表形式获取购买信息 |
| GetProductDictionary() | Dictionary<string, ProductInfo> | 以 productId 形式获取商品信息 - ProductInfo 字典 |
| GetProductList() | List<ProductInfo> | 以列表形式获取商品信息 |
PurchaseInfo
| 字段名称 | 类型 | 描述 |
|---|---|---|
| ItemType | string | 固定值“inapp” |
| ProductId | string | IAP 商品的商品 ID |
| GameOrderId | string | UDP 提供的 cpOrderId |
| OrderQueryToken | string | 用于查询 UDP 服务器的令牌，由 UDP 生成 |
| DeveloperPayload | string | 开发者提供的任何字符串。UDP 将在 ‘Purchase’ 方法中将此信息传递给 PartnerStore。 |
| StorePurchaseJsonString | string | PartnerStore 提供的任何其他附加信息 |
ProductInfo
| 字段名称 | 类型 | 描述 |
|---|---|---|
| ItemType | string | 固定值“inapp” |
| ProductId | string | IAP 商品的商品 ID |
| Consumable | bool | 是否为消耗品 |
| Price | string | 格式化的商品价格，包括货币符号。 |
| PriceAmountMicros | long | 以 micro 单位表示的 IAP 商品价格 |
| Currency | string | IAP 商品货币 |
| Title | string | IAP 商品名称 |
| 描述 | string | IAP 商品描述 |
IPurchaseListener
IPurchaseListener 提供以下监听器，可告知你所有与购买有关的事件的结果：
| 事件 | 描述 |
|---|---|
| OnPurchase | 购买成功。 |
| OnPurchaseFailed | 购买失败。 |
| OnPurchaseRepeated | 在玩家多次购买非消耗品时使用。当合作伙伴商店不支持 QueryInventory 时，你可以实现此监听器。 |
| OnPurchaseConsume | 消耗成功。 |
| OnPurchaseConsumeFailed | 消耗失败。 |
| OnQueryInventory | 查询成功。 |
| OnQueryInventoryFailed | 查询失败。 |
订单查询参数
请求中的参数：
| 属性名称 | 格式 | 必需/可选 | 描述 | 示例 |
| orderQueryToken | 字符串 | 必需 | 完成购买时由客户端 SDK 返回的订单查询令牌。此令牌采用 Base64 编码。（UDP SDK 将返回 PurchaseInfo.OrderQueryToken） | eyJjaGFubmVsUHJvZHVjdElkIjoiaWFwLl9mM2YzZiIsImNoYW5uZWxUeXBlIjoiQVBUT0lERSIsImNsaWVudElkIjoiQUFJZ3g5VmNGaDJZQ1ZxbUs2VWNDUSIsImNwT3JkZXJJZCI6IjJhNGQ5MWY4NDgzZjQ3YjlhYzFhNGY5MDAwZDVhNTRhIiwicGFja2FnZU5hbWUiOiJjb20udW5pdHkudW5pdHl0ZXN0Z2FtZV9mZWZ3In0= |
| orderId | 字符串 | 必需 | 完成购买时由客户端 SDK 返回的 orderId。（UDP SDK 将返回 PurchaseInfo.GameOrderId） | 2a4d91f8483f47b9ac1a4f9000d5a54a |
| clientId | 字符串 | 必需 | 可在游戏信息（UDP 控制台的集成信息）中找到 clientId。 | AAIgx9VcFh2YCVqmK6UcCQ |
| sign | 字符串 | 必需 | 使用 orderQueryToken 和客户端密码 MD5.hash(orderQueryToken + clientSecret) 生成签名。 也可在游戏信息（UDP 控制台的集成信息）中找到客户端密码。 | 客户端密码：KKcCyAgej06MxjKX31WuFNeHSaTJAjLDlgoDWsPJDAM 签名： 90a4e440897623c7cd0b2b80a97c267e |
响应中的参数：
| 属性名称 | 格式 | 必需/可选 | 描述 | 示例 |
| clientId | 字符串 | 必需 | 游戏在 Unity IAP 中创建客户端后由 Unity 返回的 clientId。 | Q4AnJDW2-rxLAPujqrk1zQ |
| cpOrderId | 字符串 | 必需 | 由游戏分配的订单 ID（如果游戏未生成，则由 Unity 分配）。 | 66mea52wne |
| channelType | 字符串 | 必需 | 通道类型。 | APTOIDE, CLOUDMOOLAH |
| status | 字符串 | 必需 | 指示订单状态。 | SUCCESS, FAILED, UNCONFIRMED, STORE_NOT_SUPPORT |
| productId | 字符串 | 必需 | 与订单关联的商品 ID。 | product_1 |
| amount | 字符串 | 必需 | 订单的付款金额。 | 1 |
| quantity | 整数 | 必需 | 指示商品的数量。 | 1 |
| currency | ISO 4217 | 必需 | 用于购买商品的货币。 | CNY |
| country | ISO 3166-2 | 必需 | 用户所在的国家或地区。 | CN |
| paidTime | ISO8601 yyyy-MM-ddThh:mm:ssXXX，UTC 时区 | 可选 | 指定支付订单的时间。 | 2017-03-08T06:43:20Z |
| rev | 字符串 | 必需 | 订单的修订（仅用于更新）。 | 0 |
| extension | Json 字符串 | 可选 | 开发者有效负载，用于添加参考信息。 | {"abc" : "123"} |
以下示例说明了从游戏服务器向 UDP 服务器发出的请求，以及从 UDP 服务器返回到游戏服务器的响应：
orderQueryToken 的内容：
{"channelProductId":“iap._f3f3f”,“channelType”:“APTOIDE”,“clientId”:“AAIgx9VcFh2YCVqmK6UcCQ”,“cpOrderId”:“2a4d91f8483f47b9ac1a4f9000d5a54a”,“packageName”:“com.unity.unitytestgame_fefw”}
orderQueryToken（采用 Base64 编码）：
eyJjaGFubmVsUHJvZHVjdElkIjoiaWFwLl9mM2YzZiIsImNoYW5uZWxUeXBlIjoiQVBUT0lERSIsImNsaWVudElkIjoiQUFJZ3g5VmNGaDJZQ1ZxbUs2VWNDUSIsImNwT3JkZXJJZCI6IjJhNGQ5MWY4NDgzZjQ3YjlhYzFhNGY5MDAwZDVhNTRhIiwicGFja2FnZU5hbWUiOiJjb20udW5pdHkudW5pdHl0ZXN0Z2FtZV9mZWZ3In0=
订单 ID：
2a4d91f8483f47b9ac1a4f9000d5a54a
客户端 ID：
AAIgx9VcFh2YCVqmK6UcCQ
客户端密码：
KKcCyAgej06MxjKX31WuFNeHSaTJAjLDlgoDWsPJDAM
签名：
90a4e440897623c7cd0b2b80a97c267e
请求：
GET
https://distribute.dashboard.unity.com/udp/developer/api/order?orderQueryToken=eyJjaGFubmVsUHJvZHVjdElkIjoiaWFwLl9mM2YzZiIsImNoYW5uZWxUeXBlIjoiQVBUT0lERSIsImNsaWVudElkIjoiQUFJZ3g5VmNGaDJZQ1ZxbUs2VWNDUSIsImNwT3JkZXJJZCI6IjJhNGQ5MWY4NDgzZjQ3YjlhYzFhNGY5MDAwZDVhNTRhIiwicGFja2FnZU5hbWUiOiJjb20udW5pdHkudW5pdHl0ZXN0Z2FtZV9mZWZ3In0%3D&orderId=2a4d91f8483f47b9ac1a4f9000d5a54a&clientId=AAIgx9VcFh2YCVqmK6UcCQ&sign=90a4e440897623c7cd0b2b80a97c267e
响应：
{"ClientId":"AAIgx9VcFh2YCVqmK6UcCQ","CpOrderId":"2a4d91f8483f47b9ac1a4f9000d5a54a","ProductId":"iap._f3f3f","ChannelType":"APTOIDE","Currency":"APPC","Amount":"0.1","Country":"HK","Quantity":1,"Rev":"0","Status":"SUCCESS","PaidTime":"2019-06-12T03:59:42Z","Extension":"unity://unity3d.com?cpOrderId=2a4d91f8483f47b9ac1a4f9000d5a54a\u0026payload=payload2"}
JSON 有效负载
下面是一个 JSON 有效负载的内容：
| 属性名称 | 格式 | 必需/可选 | 描述 | 示例 |
| cpOrderId | 字符串 | 必需 | 游戏分配的唯一订单标识符。 | 0bckmoqhel5yd13f |
| status | 字符串 | 必需 | 指示订单状态。 | SUCCESS |
| amount | 字符串 | 必需 | 指定订单费用的金额。 | 1.01 |
| productId | 字符串 | 必需 | 指定订单所含商品的唯一标识符。 | com.mystudio.mygame.productid1 |
| paidTime | ISO8601 yyyy-MM-ddThh:mm:ssZ，UTC 时区 | 可选 | 订单付款时间。即使在沙盒环境中未实际付款，也将在沙盒模式下返回此信息。 | 2018-09-28T06:43:20Z |
| country | ISO 3166-2 | 必需 | 订单付款所在的国家/地区。 | CHINA |
| currency | ISO 4217 或加密货币类型 | 必需 | 下订单所在国家/地区的货币。 | CNY |
| quantity | 整数 | 必需 | 订单中的商品数量。 | 1 |
| clientId | 字符串 | 必需 | 游戏在 Unity IAP 中生成客户端后返回的唯一客户端标识符。 | Q_sX9CXfn-rTcWmpP9VEfw |
| extension | 字符串 | 可选 | 开发者有效负载，用于包含开发者的参考信息。 | "{"key":"value"}" |