UDP package reference
Editor UI
UDP Settings
The UDP Settings inspector manages the connection between your Unity project and the UDP client. To enable the UDP Settings window, you must install the UDP package and link your Unity project to a UDP client.
To access the UDP Settings window in the Unity Editor, select Window > Unity Distribution Portal > Settings.
| UDP Settings | Description |
|---|---|
| Pull | Retrieves (pulls) the information you last saved on the UDP server into the Editor. The following information is synced: - Game Title - Settings - UDP Sandbox Test Accounts - IAP Catalog (if using the UDP package only) This overrides any unsaved changes in the Editor. |
| Push | Saves (pushes) your changes to the UDP server. The following information is synced: - Game Title - Settings - UDP Sandbox Test Accounts - IAP Catalog (if you defined the IAP Catalog directly in the UDP Settings window) |
| Game Title | Input the title of your game, and press Push to save. This field syncs with the UDP console. By default and on first load, Game Title is populated with Game ID (see Settings). |
| Unity Project ID | Your Unity project ID, which is now linked to your UDP client ID. This field is not editable. |
| IAP Catalog | For UDP package implementations, the IAP catalog fields are displayed. For Unity IAP implementations, the Open Catalog button is displayed. From Unity Editor version 2020.1, the IAP Catalog is available in a separate window. |
| Settings | Contains additional game settings. |
| UDP Sandbox Test Accounts | Contains settings for UDP Sandbox Test Accounts. |
IAP Catalog
The IAP Catalog section lets you define IAP products for UDP. To add a new item, select Add new IAP. The image below shows the IAP Catalog section if using the UDP package.
The table below describes the fields of the IAP Catalog section.
| Field | Description |
|---|---|
| Product ID | The unique ID used to identify the IAP product. Product IDs must follow these requirements: - Start with a letter or a digit - Contain only letters, digits, dots (.) and underscores (_) - Must not use capitalized letters |
| Name | The name of the IAP product. |
| Type | Indicates whether the IAP product is consumable or not. |
| Price | The price of the IAP product in USD. You can set prices for additional currencies in the UDP console. You must specify a price to enable players to purchase products in your game. |
| Description | A short description of the IAP product. This field only supports a description in a single language (English). You can add further languages in the UDP console. |
If you have any unsaved changes for your IAP products, an edited label is displayed. This disappears when you sync the IAP product.
Note: If you use the separate Unity IAP package, select Window > Unity Distribution Portal > IAP Catalog and define your IAP products in the separate IAP Catalog window.
Settings
The Settings section contains additional settings that are synced from the UDP console. Callback URL is the only editable setting. Press Push to save any changes.
| Field | Function | Editable |
|---|---|---|
| Game ID | The identifier for the game | No |
| Client ID | The UDP client identifier | No |
| Client Key | Used when initializing the UDP SDK | No |
| Client RSA Public Key | Used to verify the callback notification | No |
| Client Secret | A Unity key to sign your request that your game sends to the UDP server | No |
| Callback URL | Specifies the URL for the server that receives the callback notification | Yes |
UDP Sandbox Test Accounts
The UDP Sandbox Test Accounts section lets you add login credentials for the UDP sandbox. This is required to test your game in the UDP sandbox environment. You can also set these credentials in the UDP console.
| Field | Function | Editable |
|---|---|---|
| The email address for the sandbox test account. It is used as the login name. | Yes | |
| Password | The password for the test account. | Yes |
UDP SDK
UDP SDK data structure
This section describes the classes of the UDP SDK.
UserInfo
| field name | type | desc |
|---|---|---|
| Channel | string | PartnerStore name, generated by UDP |
| UserId | string | optional, user ID returned from PartnerStore |
| UserLoginToken | string | optional, user login token returned from PartnerStore |
Inventory
| public function | returns | desc |
|---|---|---|
| GetPurchaseInfo(string productId) | PurchaseInfo | get PurchaseInfo of given productId |
| GetProductInfo(string productId) | ProductInfo | get ProductInfo of given productId |
| HasPurchase(string productId) | bool | check if any unconsumed purchase exists for given productId |
| HasProduct(string productId) | bool | check if product exists for given productId |
| GetPurchaseDictionary() | Dictionary<string, PurchaseInfo> | get purchases as productId - PurchaseInfo dictionary |
| GetPurchaseList() | List<PurchaseInfo> | get purchases as list |
| GetProductDictionary() | Dictionary<string, ProductInfo> | get products as productId - ProductInfo dictionary |
| GetProductList() | List<ProductInfo> | get products as list |
PurchaseInfo
| field name | type | desc |
|---|---|---|
| ItemType | string | fixed value “inapp” |
| ProductId | string | product ID of IAP item |
| GameOrderId | string | cpOrderId provided by UDP |
| OrderQueryToken | string | token to query UDP server, generated by UDP |
| DeveloperPayload | string | Any string provided by the developer. UDP will pass this to PartnerStore in the ‘Purchase’ method. |
| StorePurchaseJsonString | string | any other additional info provided by PartnerStore |
ProductInfo
| field name | type | desc |
|---|---|---|
| ItemType | string | fixed value “inapp” |
| ProductId | string | product ID of IAP item |
| Consumable | bool | can be consumed or not |
| Price | string | formatted price of the item, including its currency sign. |
| PriceAmountMicros | long | price of IAP item in micros |
| Currency | string | currency of IAP item |
| Title | string | IAP item name |
| Description | string | IAP item description |
IPurchaseListener
IPurchaseListener provides the following listeners that tell you the result of all purchase-related events:
| Event | Description |
|---|---|
| OnPurchase | The purchase succeeded. |
| OnPurchaseFailed | The purchase failed. |
| OnPurchaseRepeated | Used when a player buys a non-consumable product several times. You can implement this listener when the partner store doesn’t support QueryInventory. |
| OnPurchaseConsume | The consumption succeeded. |
| OnPurchaseConsumeFailed | The consumption failed. |
| OnQueryInventory | The query succeeded. |
| OnQueryInventoryFailed | The query failed. |
QueryOrder parameters
To query UDP about orders, call an HTTP GET request. The table below describes the parameters in the QueryOrder request:
| Attribute name | Format | Required/Optional | Description | Example |
| orderQueryToken | String | Required | The order query token returned by the client SDK when finishing a purchase. The token is Base64 encoded. (UDP SDK will return PurchaseInfo.OrderQueryToken) | eyJjaGFubmVsUHJvZHVjdElkIjoiaWFwLl9mM2YzZiIsImNoYW5uZWxUeXBlIjoiQVBUT0lERSIsImNsaWVudElkIjoiQUFJZ3g5VmNGaDJZQ1ZxbUs2VWNDUSIsImNwT3JkZXJJZCI6IjJhNGQ5MWY4NDgzZjQ3YjlhYzFhNGY5MDAwZDVhNTRhIiwicGFja2FnZU5hbWUiOiJjb20udW5pdHkudW5pdHl0ZXN0Z2FtZV9mZWZ3In0= |
| orderId | String | Required | The orderId returned by the client SDK when finishing a purchase. (UDP SDK will return PurchaseInfo.GameOrderId) | 2a4d91f8483f47b9ac1a4f9000d5a54a |
| clientId | String | Required | The clientId can be found in the Game info - integration information of UDP console. | AAIgx9VcFh2YCVqmK6UcCQ |
| sign | String | Required | Generate signature with orderQueryToken and client secret, MD5.hash(orderQueryToken + clientSecret). Client Secret can also been found in the Game info - integration information of UDP console. | Client Secret: KKcCyAgej06MxjKX31WuFNeHSaTJAjLDlgoDWsPJDAM Sign: 90a4e440897623c7cd0b2b80a97c267e |
The store where your game is published returns the QueryOrder response to UDP. UDP forwards these parameters to your game. The table below describes the parameters in the QueryOrder response：
| Attribute name | Format | Required /optional | Description | Example |
| clientId | String | Required | The clientId that Unity returns after the game has created a client in the Unity IAP. | Q4AnJDW2-rxLAPujqrk1zQ |
| cpOrderId | String | Required | The order ID assigned by your game, or Unity if the game does not generate it. | 66mea52wne |
| storeOrderId | String | Optional | The order ID that the store returns. | Stores have their own Order ID format |
| channelType | String | Required | Channel type. | APTOIDE, CLOUDMOOLAH |
| status | String | Required | Indicates the status of the order. | SUCCESS, FAILED, UNCONFIRMED, STORE_NOT_SUPPORT |
| productId | String | Required | The product ID associated with the order. | product_1 |
| amount | String | Required | The payment amount of the order. | 1 |
| quantity | Integer | Required | Indicates the quantity of the product. | 1 |
| currency | ISO 4217 | Required | The currency used to purchase the product. | CNY |
| country | ISO 3166-2 | Required | The country or geographic region in which the user is located. | CN |
| paidTime | ISO8601 yyyy-MM-ddThh:mm:ssXXX， UTC timezone | Optional | Specifies the time when the order is paid. | 2017-03-08T06:43:20Z |
| rev | String | Required | The revision of the order (only for update). | 0 |
| extension | Json String | Optional | The developer payload used to add reference information. | {"abc" : "123"} |
Here is an example request from your game server to the UDP server and response from the UDP server back to your game server：
The content of the orderQueryToken:
{"channelProductId":“iap._f3f3f”,“channelType”:“APTOIDE”,“clientId”:“AAIgx9VcFh2YCVqmK6UcCQ”,“cpOrderId”:“2a4d91f8483f47b9ac1a4f9000d5a54a”,“packageName”:“com.unity.unitytestgame_fefw”}
orderQueryToken (encoded as Base64):
eyJjaGFubmVsUHJvZHVjdElkIjoiaWFwLl9mM2YzZiIsImNoYW5uZWxUeXBlIjoiQVBUT0lERSIsImNsaWVudElkIjoiQUFJZ3g5VmNGaDJZQ1ZxbUs2VWNDUSIsImNwT3JkZXJJZCI6IjJhNGQ5MWY4NDgzZjQ3YjlhYzFhNGY5MDAwZDVhNTRhIiwicGFja2FnZU5hbWUiOiJjb20udW5pdHkudW5pdHl0ZXN0Z2FtZV9mZWZ3In0=
Order ID:
2a4d91f8483f47b9ac1a4f9000d5a54a
Client ID:
AAIgx9VcFh2YCVqmK6UcCQ
Client Secret:
KKcCyAgej06MxjKX31WuFNeHSaTJAjLDlgoDWsPJDAM
Sign:
90a4e440897623c7cd0b2b80a97c267e
Request:
GET
https://distribute.dashboard.unity.com/udp/developer/api/order?orderQueryToken=eyJjaGFubmVsUHJvZHVjdElkIjoiaWFwLl9mM2YzZiIsImNoYW5uZWxUeXBlIjoiQVBUT0lERSIsImNsaWVudElkIjoiQUFJZ3g5VmNGaDJZQ1ZxbUs2VWNDUSIsImNwT3JkZXJJZCI6IjJhNGQ5MWY4NDgzZjQ3YjlhYzFhNGY5MDAwZDVhNTRhIiwicGFja2FnZU5hbWUiOiJjb20udW5pdHkudW5pdHl0ZXN0Z2FtZV9mZWZ3In0%3D&orderId=2a4d91f8483f47b9ac1a4f9000d5a54a&clientId=AAIgx9VcFh2YCVqmK6UcCQ&sign=90a4e440897623c7cd0b2b80a97c267e
Response:
{"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 payload
Here is the content of a JSON payload:
| Attribute Name | Format | Required/Optional | Description | Example |
| cpOrderId | String | Required | The unique order identifier assigned by your game. | 0bckmoqhel5yd13f |
| status | String | Required | Indicates the status of the order. | SUCCESS |
| amount | String | Required | Specifies the amount of money that the order cost. | 1.01 |
| productId | String | Required | Specifies the unique identifiers of the products that belong to the order. | com.mystudio.mygame.productid1 |
| paidTime | ISO8601 yyyy-MM-ddThh:mm:ssZ, UTC timezone | Optional | The time when the order was paid. This is also returned in sandbox mode, even though no actual payment is made in the sandbox environment. | 2018-09-28T06:43:20Z |
| country | ISO 3166-2 | Required | The country where the order was paid. | CHINA |
| currency | ISO 4217 or cryptocurrency type | Required | The currency of the country where the order was placed. | CNY |
| quantity | Integer | Required | The number of products in the order. | 1 |
| clientId | String | Required | The unique client identifier that is returned after your game generates a client in Unity IAP. | Q_sX9CXfn-rTcWmpP9VEfw |
| extension | String | Optional | The developer payload which is used to contain reference information for developers. | "{"key":"value"}" |