具象状态传输（REST）API 第3.0版
概述
收集（Collect）API记录游戏中的事件。这些事件可以通过deltaDNA在线平台的测量（Measure）功能被跟踪，并使用吸引（Engage）A/B测试和命中目标干预来分析（Analyze）玩家行为和为玩家提供个性化感受体验。这个API提供两个操作。一个生成了唯一的用户ID，另一个记录游戏中触发的所有事件。
生成一个唯一的用户ID
用户ID是一个用户的唯一ID。当你在你的游戏中没有用户ID时，生成一个UUID是创建一个的首选方式。这时你将被要求在客户端本地存储这个返回值，并为所有将要来自这个特定客户端的收集（Collect）调用重复使用。
如果你已经有了一个用户可以被你唯一识别的ID，你可以使用这个值。然而更常见的是存在禁止在第三方平台存储简单易懂的用户ID的法律限制或者许可约束的限制。为这个ID创建一个哈希值，并使用其作为这个整合的一个用户ID将在多数情况下成为解决此问题的方式。这防止了这个用户ID被不同用户重复使用。
记录事件
为这个收集（Collect）API创建一个HTTP POST来记录一个事件。将HTTP请求报头设置为“Content-Type: application/json”，并使用如下URL格式中的一个：
为每一个创建的新应用程序设置一个环境键（Environment Key），并且每一个应用程序的自定义事件（Custom Event）的集合可以被配置。最初你将访问我们的测试服务器（Test Server），并且当整合和测试完成时，你的应用程序将在我们实际运行的服务器上激活，一个新的URL和应用程序标识符将会提供给你。
这请求的主体指定了一个对应事件类型的JSON文件，这将在接下来的章节介绍。
两个URL给了我们两个接收事件的选择。第一个是一个简单的方式（推荐用于测试），第二个是一个使用了哈希法的更复杂的方式。后一个确保了可靠性和事件的完整性，并被建议用于产品。哈希值是一个由JSON事件字符串创建的并被附加了一个密钥（只有用户和deltaDNA知道）的32位的MD5哈希值。
如果状态代码是204 No Content（204无内容），这个事件就已经被服务器成功接收，并且服务器没有想要送回的任何信息。
如果状态代码是除了204 No Content（204无内容）的其他代码，这个请求的工作存在错误。状态代码和消息将描述遇到的问题。例如：
400错误的请求 – “自定义事件代码无法识别”
事件格式
所有的事件都应当在请求的主体以JSON文件发送到服务器。不同事件类型对应的文件将会各不相同，但是其所有的都应遵循如下格式：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
{ "eventName":"specific event code – eg. gameStarted", "userID":"ABCD1-4321a879b185fcb9c6ca27abc5387e914", "sessionID":"4879bf37-8566-46ce-9f3b-bd18d6ac614e", "eventTimestamp":"yyyy-mm-dd hh:mm:ss.SSS", "eventParams": { "platform":"WEB", "param1":"stringParam", "param2":true, "param3":1234, "param4":["a","b","c"] }, } |
会话ID（sessionID）：会话ID是一个针对所有事件的可选参数。其应当包括一个唯一的字符串值一直持续在玩家游戏任务进行的完整时期并在每个新的游戏任务时重新生成。会话ID应当由玩家在其任务中触发的每个事件中被发送。deltaDNA平台这时将使用这个会话ID来计算每个玩家玩过的任务次数，每个任务的长度等等。
可能存在你想要发送在一个玩家会话之外的包含有价值的玩家信息的事件，且没有使用会话ID。其被称为GHOST事件且你应当在这些事件中忽略会话ID参数和值以确保其不会被包含到任何玩家会话统计中。典型的GHOST事件案例包括归因事件（Attribution Events）或者源自第三方服务的交易信息。
eventUUID 是一个对任一事件唯一的可选参数。添加eventUUID将防止事件在24小时内被插入两次。这发生在当例如网络超时发生时即使这个事件已经被处理的情形。为每个事件使用一个唯一的eventUUID将防止在平台上生成多个事件。
eventTimestamp 是一个可选参数（然而，其将被移动SDK自动设置）。如果这个eventTimestamp丢失，接收这个事件的服务器将创建其自己的时间戳。日期格式应该是这样的：
yyyy-MM-dd HH:mm:ss.SSS ±[hh]:[mm] 其中的±[hh]:[mm]被用于表明一个时区针对UTC的偏移量。
例如：“2013-12-30 16:55:00.321”或“2013-12-30 16:55:00.321 -08:00”
注意，JSON中参数的顺序是无关紧要的
非必需的参数不必包含在文件中。其可以被一起省略，而不是发送空的或者零参数。
大批量事件
可以在一个POST中发送多个事件。这个方法确实是更好的，因为连接池更有效率等原因。
每个独立事件的格式都是一样的，然而其被用一个eventList数组表示包含多个独立事件。
例如
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
{ "eventList": [ { "eventName": "newPlayer", "userID": "GA_098987AY127FAFS1192", "sessionID": "f32f4a04-e75b-42f0-a2a9-18c0805f09b1", "eventParams": { "platform": "IOS_MOBILE", } }, { "eventName": "clientDevice", "userID": "GA_098987AY127FAFS1192", "sessionID": "f32f4a04-e75b-42f0-a2a9-18c0805f09b1", "eventParams": { "deviceName": "Bobs IPHONE", "deviceType": "iPhone5", "hardwareVersion": "v100.2442", "manufacturer": "APPLE", "operatingSystem": "iOS6", "operatingSystemVersion": "0.5", "browserName": "Safari", "browserVersion": "10" } } ] } |
大批量事件应当被推送到一个不同于单一事件的另一URL，
- 如果安全哈希法被禁用：http://<COLLECT API URL>/collect/api/<ENVIRONMENT KEY>/bulk
- 如果安全哈希法被启用：http://<COLLECT API URL>/collect/api/<ENVIRONMENT KEY>/bulk/hash/
请注意，大批量事件列表中的事件应当按照其发生的顺序排序。
交易事件
交易(Transaction)事件包括数组和一些你将遇到的特殊的产品对象，例如玩家与游戏或其他玩家之间购买、交易、获胜、交换货币和物品。好消息是，针对此的结构相当标准，下面的事件能够支持足够复杂的需求。
下面的交易事件记录了玩家使用一些真实货币购买一个含有一些虚拟货币和多个物品的宝箱。我们将利用deltaDNA可以与Apple商店和Google Play商店之间进行收入验证的优势来检查这个交易是否有效。关于Apple收据验证的更多信息请查看iOS SDK文档，关于Google的请查看Android SDK文档页面。
正如你所看到的交易事件的结构有一点儿复杂。它包括了一些产品对象来记录productsSpent和productsReceived。
我们的JSON事件最终看起来是这样的
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 |
{ "eventName": "transaction", "userID": "4c1e9486-5477-42e4-8b0e-d3df9d173e60", "sessionID": "d03fa7a4-b87e-43c8-8130-4c6aead89c4c", "eventTimestamp": "2014-07-04 20:07:04.994", "eventParams": { "transactionName": "IAP - Large Treasure Chest", "transactionID": "47891208312996456524019-178.149.115.237:51787", "transactorID": "62.212.91.84:15116", "productID": "4019", "transactionServer": "APPLE", "transactionReceipt": "ewok9Ja81............991KS==", "transactionType": "PURCHASE", "productsReceived": { "virtualCurrencies": [ { "virtualCurrency": { "virtualCurrencyName": "Gold", "virtualCurrencyType": "PREMIUM", "virtualCurrencyAmount": 100 } } ], "items": [ { "item": { "itemName": "Golden Battle Axe", "itemType": "Weapon", "itemAmount": 1 } }, { "item": { "itemName": "Mighty Flaming Sword of the First Age", "itemType": "Legendary Weapon", "itemAmount": 1 } }, { "item": { "itemName": "Jewel Encrusted Shield", "itemType": "Armour", "itemAmount": 1 } } ] }, "productsSpent": { "realCurrency": { "realCurrencyType": "USD", "realCurrencyAmount": 499 } }, "platform": "PC_CLIENT", "sdkVersion": "Unity SDK v3.1" } } |
还值得一提的是，货币币值总是被通过整数代表最小的货币单位传送。realCurrencyType是一个按照ISO-4217标准的3位字符的货币代码。
|
1 2 3 4 |
"realCurrency": { "realCurrencyType": "USD", "realCurrencyAmount": 499 } |
上述的代码片段代表的是4.99美元。
这个事件可能会更复杂，但是其结构是有逻辑的、灵活的，并为玩家支出和接收任何组合的货币和物品提供一个机制。
吸引（Engage）
发送一个HTTP POST到吸引（Engage）API以找出是否有一个可能在这一点影响游戏的吸引（Engage）活动。设置HTTP的请求报头为“Content-Type: application/json”，并使用下面的URL格式：
在请求的正文中，指定与这一决策点的测试请求相对应的一个JSON文件。
|
1 2 3 4 5 6 7 8 |
{ "decisionPoint": "gameStarted", "userID": "84a566f8-7a00-4a88-9cd5-1a20ea963141", "sessionID": "8388169699029497748", "platform": "PC_CLIENT", "parameters": { } } |
混合整合
可能有同时来自客户端和服务器的事件及吸引（Engage）。在这种情况下，来自服务器的流量可能不应被考虑为真实的游戏运行，且通过忽略会话ID，吸引（Engage）调用在分析时将不会考虑玩家活动。这防止了留存和DAU图表被来自服务器的调用影响。
请注意：
- 平台参数是可选的，且在混合整合中，推荐只在客户端设置平台。
- 会话ID是可选的。
- 即使未配置参数，也需要参数对象。
A/B测试响应
如下的错误代码将显示你的A/B测试请求的所有问题。
- 400 – 输入格式错误或以某种方式丢失，或者你正在发送的实时参数没有被添加到你的游戏参数列表或者以不同于游戏参数管理器中指定的参数发送。
- 403 – 私密哈希键错误或者吸引（Engage）在你的账户中未激活。
请检查你已经在你的“游戏->Package包”启用了“按需定制”版的包。为了执行这些，你可能需要为你的deltaDNA账户获得账号所有者权限。 - 404 – 未知的环境键
- 200 – 成功
一个成功的响应将包括一个含有交易ID和其他任一参数的JSON文件。
测试A – 对照组（或者未知用户ID的任何其他人）
|
1 2 3 4 |
{ "transactionID": 1704269028861673500, "parameters": {} } |
测试B – 每次游戏开始时弹出
|
1 2 3 4 5 6 |
{ "transactionID": 1704269028861673500, "parameters": { "popupDisplayFrequency": 1 } } |
测试C – 每第三次游戏开始时弹出
|
1 2 3 4 5 6 |
{ "transactionID": 1704269028861673500, "parameters": { "popupDisplayFrequency": 3 } } |
游戏应当能够在没有响应在可接受的时间内从吸引（Engage）接收时应用一个缺省值。请求应当用一种非闭塞的方式被创建给吸引（Engage），例如服务不可用时。
推送通知
deltaDNA支持从iOS和Android发送推送通知。Android和iOS SDK将有助于发回所需的令牌/注册（Token/Registration），但是在使用REST API时，你将不得不自己将其送回。当你已经从设备或你的后台服务器取回Token，这时其应当在notificationServices事件中报告回deltaDNA。对于iOS，你将必须确保pushNotificationToken已经生成，对于Android，是AndroidRegistrationID。
基于JavaScript的案例
在下面的页面我们有一个用JavaScript开发的具象状态传输（REST）API的案例。这可以用作你自己实现具象状态传输（REST）API时的参考。
