REST API Version 3.0
Overview
The Collect API records events from a game, these events can be tracked using the deltaDNA online dashboard Measure and are used Analyze player behaviour and personalize the player experience with Engage A/B tests and targeted interventions. The API offers two operations. One generates the Unique User ID and the other records all the event triggered from the game.
Generating a Unique User ID
A userId is an ID that is unique to a user. When you don’t have your own userID in your game, generating a UUID is the preferred way of creating one. You would then be required to store the returned value locally on the client and reuse if for all future Collect calls from that specific client. The deltaDNA REST API has a method for generating a random unique userID that can be used for his purpose.
<COLLECT API URL>/collect/api/uuid
When you already have an ID the user can be identified by you can use this value. However more often than not there are either legal restrictions or limitations due to licensing restrictions that prevent storing the apparent userID at a third party. Creating a hash of this id and using that as a userID for the integration will in most cases be a workaround to this problem, this prevents having to store the userID again.
COLLECT : Recording Events
Make an HTTP POST to the Collect API to record an event, your POST should be UTF-8 encoded. Set the HTTP request header to “Content-Type: application/json” and use one of the following URL formats:
An Environment Key is set for each new application that is created and set of Custom Events can be configured per application. Initially you will be accessing our Test Server and once integration and testing is completed your application will be enabled on our live servers and a new URL and Application Identifier will be provided to you.
In the body of the request specify a JSON document corresponding to the event type, as described in the following section.
Two URLs give us two options to receive the events. First one is a simple one (recommended for testing) and the second one more complex using hashing. The latter one is to verify the authenticity and the integrity of the event and is advised for production. Hash is a 32-digit MD5 hash created from the JSON event string with appended a Secret Key (known only by the customer and deltaDNA).
If the status code is 204 No Content, the event has been successfully received by the server and there is nothing that the server wants to send back.
If the status code is other than 204 No Content, there was an error serving the request. The status code and the message will describe the problem encountered. For example:
400 Bad Request – “Custom Event Code not recognised”
Events Format
All events should be sent to the server in the body of the request as a JSON document. The document will be different for every event type, but all of them should adhere to the following format:
|
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", "eventUUID": "374cc674-9785-4772-8cca-d7cdf517a590", "eventTimestamp": "yyyy-mm-dd hh:mm:ss.SSS", "eventParams": { "platform": "WEB", "param1": "stringParam", "param2": true, "param3": 1234, "param4": ["a", "b", "c"] } } |
userID : Every event must contain a userID, this is simply a unique string that identifies the player and is consistent across their subsequent play sessions. Please see the paragraph above on generating a unique userID.
sessionID: The sessionID is an optional parameter on all events. It should contain a unique string value that is persisted for the duration of player gameplay session and regenerated with each new gameplay session. The sessionID should be sent with every event the player triggers in their session. The deltaDNA platform will then use the sessionID to calculate the number of sessions each player plays, the length of each session etc..
There may be occasions when you wish to send events containing valuable player information outside a player session and don’t have access to a sessionID. These are called GHOST events and you should omit the sessionID parameter and value on these events to ensure that they are not included in any player session calculations. Typical examples of GHOST events would be attribution events or transactional information originating from 3rd party services.
eventUUID is an optional parameter which should be unique for each event. Adding the eventUUID will prevent the event being inserted twice within a 24 hour period. This would be the case when for example a network time-out occurs even though the event has been processed. Using a unique eventUUID for each event will prevent this from resulting in multiple events within the platform.
eventTimestamp is optional (however, it will be set automatically by the mobile SDKs). If the eventTimestamp is missing, the server upon receipt of the event will create its own timestamp. The date format should like this:
yyyy-MM-dd HH:mm:ss.SSS ±[hh]:[mm] where the ±[hh]:[mm] can be included to indicate a timezone offset from UTC.
E.g. “2013-12-30 16:55:00.321” or “2013-12-30 16:55:00.321 -08:00”
Note that the order of the parameters doesn’t matter for JSON
Parameters which are not required don’t have to be included in the document. They can be omitted all together rather than sending empty or null parameters.
Bulk Events
It is possible to send multiple events in a single POST, indeed this approach is preferable due to efficiencies in connection pooling etc.. Please keep the POST length below 5MB, anything above may be rejected.
The format of each individual event remains the same, however they are represented in an eventList array containing individual events.
e.g.
|
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 |
{ "eventList": [{ "eventName": "newPlayer", "userID": "GA_098987AY127FAFS1192", "sessionID": "f32f4a04-e75b-42f0-a2a9-18c0805f09b1", "eventUUID": "ebf50615-30cc-4417-bb7b-e4a0451be8b4", "eventParams": { "platform": "IOS_MOBILE" } }, { "eventName": "clientDevice", "userID": "GA_098987AY127FAFS1192", "sessionID": "f32f4a04-e75b-42f0-a2a9-18c0805f09b1", "eventUUID": "e5263bd4-5280-4fe5-97b9-265ed1885c76", "eventParams": { "deviceName": "Bobs IPHONE", "deviceType": "iPhone5", "hardwareVersion": "v100.2442", "manufacturer": "APPLE", "operatingSystem": "iOS6", "operatingSystemVersion": "0.5", "browserName": "Safari", "browserVersion": "10" } }] } |
Bulk events should be POSTED to a different URL than single events,
- If Security Hashing is Disabled : <COLLECT API URL>/collect/api/<ENVIRONMENT KEY>/bulk
- If Security Hashing is Enabled : <COLLECT API URL>/collect/api/<ENVIRONMENT KEY>/bulk/hash/<hash value>
Please note, the events inside a bulk event list should be ordered in the order they occurred.
Transaction Events
The transaction event contain arrays and some special product objects that you will encounter when the player buys, trades, wins, exchanges currency and items with the game or other players. The good news is, the structure for this is fairly standard and the following event is as complex as it gets.
The following transaction event records the player using some real world currency to purchase a treasure chest containing some virtual currency and multiple items. We will also take advantage of deltaDNA revenue validation with the Apple store and Google Play store to check that the transaction is valid. For more information on Apple receipt validation please see the iOS SDK documentation and for Google see the Android SDK documentation page.
As you can see the structure of the transaction event is a bit more complex. It contains a couple of Product objects for recording productsSpent and productsReceived.
Our JSON event will end up looking like
|
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 |
{ "eventName": "transaction", "userID": "4c1e9486-5477-42e4-8b0e-d3df9d173e60", "sessionID": "d03fa7a4-b87e-43c8-8130-4c6aead89c4c", "eventUUID": "ff21799e-ca69-429d-bebd-c5a76c7f7725", "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" } } |
It is also worth noting that the currency value is always sent as an integer in the minor currency unit and the realCurrencyType is an ISO-4217, 3 character currency code.
|
1 2 3 4 |
"realCurrency": { "realCurrencyType": "USD", "realCurrencyAmount": 499 } |
The above snippet is $4.99 USD
This event may be more complex but the structure is logical, flexible and provides a mechanism for players spending or receiving any combination of currencies and items.
ENGAGE : In-game Campaign requests
Make an HTTP POST to the Engage API to find out if there are any Engage campaigns that might influence the game at this point. Set the HTTP request header to “Content-Type: application/json” and use the following URL format:
In the body of the request specify a JSON document corresponding to the test request for this decision point.
|
1 2 3 4 5 6 7 8 9 10 11 |
{ "decisionPoint": "missionReward", "userID": "tester2", "sessionID" : "<Optional SessionID>", "platform": "IOS_MOBILE", "locale": "en_GB", "version": "4", "parameters": { "missionName": "First Time User Forest #2" } } |
Providing a locale parameter in your Engage Request will allow you to take advantage of game parameter and image message localisation features. The locale parameter should contain a lowercase two-character language code and an uppercase two-character country code, separated by an underscore. e.g. “en_GB”, “fr_FR” either element can be replaced with ZZ if unknown e.g. “en_ZZ”, “zz_GB”
When using event hashing also the engage calls should be hashed, this is done by taking the MD5 hash of the body with the secret key provided in the platform appended to it. Then the url will have the following format:
Hybrid integration
It is possible to have events and engage coming from both the client and a server. In this case traffic from the server probably should not be considered as real gameplay and by omitting the SessionID the engage call will not be considered player activity when it comes to analytics. This prevents retention and DAU charts to be influenced by calls from the server.
Please Note:
- The platform parameter is optional, and in a hybrid integration it is advised to only set the platform on the client.
- SessionID is optional.
- The parameters object is required even if no parameters are configured.
A/B Test Response
The following error codes will indicate any problems with your A/B Test request.
- 400 – Inputs malformed or missing in some way or you are sending real-time parameters that haven’t been added to your game parameters list or are being sent as a different parameter type than specified in the Game Parameters manager.
- 403 – secret hash key incorrect or Engage is not enabled on your account.
Please check that you have the “On-Demand” package enabled on your Game -> Packages page, you may need to get the Account Owner for your deltaDNA account to do this for you. - 404 – Unknown environment key
- 200 – Success
A successful response will contain a JSON document with a transactionID, an eventParams object containing the campaign details and a parameters object that contains any parameter keys and values specified in your campaign action.
Test Variant A – Control group (or anybody with an unknown userID), contains an empty parameters block.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
{ "transactionID": 2348266267646697500, "eventParams": { "platform": "IOS_MOBILE", "responseTransactionID": 2348266267646697500, "responseDecisionpointName": "missionReward", "responseEngagementID": 3656, "responseEngagementName": "Power Up Gift AB Test", "responseEngagementType": "ABTEST", "responseVariantName": "A - Control" }, "parameters": {} } |
Test Variant B – Contains a parameter object with parameter keys and values that the game can use to personalize the game play experience for this player.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
{ "transactionID": 2348266415413395500, "eventParams": { "platform": "IOS_MOBILE", "responseTransactionID": 2348266415413395500, "responseDecisionpointName": "missionReward", "responseEngagementID": 3656, "responseEngagementName": "Power Up Gift AB Test", "responseEngagementType": "ABTEST", "responseVariantName": "B - Gift MoHawk", "responseMessageSequence": 0 }, "parameters": { "itemName": "Super MoHawk", "itemType": "Powerup", "bonusName": "MoHawk", "itemAmount": 1 } } |
Image Messages
If the action delivered by Engage is an Image Message action the JSON response will contain an additional image object that contains all the information that SDK, or your own custom display code, needs to draw the image pop up and handle the various buttons
|
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 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 |
{ "transactionID": 2348266415413395500, "image": { "layout": { "landscape": { "buttons": [ { "y": 147, "x": 159, "action": { "type": "action", "value": "bonusgift" } } ], "background": { "action": { "type": "dismiss", "value": "" }, "contain": { "right": "20%", "bottom": "0px", "top": "0px", "halign": "center", "valign": "center", "left": "20%" } } } }, "shim": { "action": { "type": "dismiss" }, "mask": "dimmed" }, "url": "http://download.deltadna.net/engagements/69675be8b66445dca0704d8cd209222e.png", "format": "png", "height": 34, "width": 160, "spritemap": { "buttons": [ { "y": 0, "x": 0, "height": 34, "width": 160 } ], "background": { "y": 0, "x": 0, "height": 34, "width": 160 } } }, "eventParams": { "platform": "IOS_MOBILE", "responseTransactionID": 2348266415413395500, "responseDecisionpointName": "missionReward", "responseEngagementID": 3656, "responseEngagementName": "Power Up Gift AB Test", "responseEngagementType": "ABTEST", "responseVariantName": "B - Gift MoHawk", "responseMessageSequence": 0 }, "parameters": { "itemName": "Super MoHawk", "itemType": "Powerup", "bonusName": "MoHawk", "itemAmount": 1 } } |
The game should be able to resort to a default value if no response is received from Engage within an acceptable time. Requests should be made to Engage in an non-blocking manner in case the service is unavailable.
China Personal Information Protection Law
China’s National People’s Congress has passed the Personal Information Protection Law (PIPL), to protect the data privacy of Chinese citizens. It is effective starting November 1st, 2021 and requires players in China to provide Opt-In consent to their data being collected and Opt-In consent to their data being stored outside of China.
You must receive consent from the player and populate two headers on all Collect and Engage REST API Posts originating from China. Any requests received from China without these headers will be rejected.
| Header | Description |
| PIPL_CONSENT | The presence of this header will indicate the player has granted consent to data collection. Players who do not consent should not have this header set on requests. The value of the header does not matter. |
| PIPL_EXPORT | The presence of this header will indicate the player has granted consent to their data being sent out of China for processing. Players who do not consent should not have this header set on requests. The value of the header does not matter. |
Please refer to the China Personal Information Protection Law page for further information and FAQ
Push Notifications
DeltaDNA supports sending push notifications for both iOS and Android. The Android and iOS SDK will help to send back the required token/registration but when using the REST API you will have to send this back yourself. When you’ve retrieved the token on the device or on your back end server then this should be reported back to DeltaDNA in the notificationServices event. For iOS you will have to make sure the pushNotificationToken is populated and for Android the AndroidRegistrationID.
Example in JavaScript
On the following page we have an example implementation of the Rest API in JavaScript, this can be used as a reference when implementing the REST API yourself.
