DeltaDNA Migration : Rest API

Overview

Unity Analytics supports a REST API for analytics data ingestion, it is very similar to the deltaDNA REST API. This document highlights the differences to help you migrate any existing deltaDNA REST API usage to Unity Analytics.

Timescale

The deltaDNA platform is being sunset on March 3rd, 2024, after this point it will not be possible to login to the deltadna.net portal. However, if you have followed the DELTADNA TO UNITY DASHBOARD MAPPING FLOW before 3rd March 2023, you will be able to login to Unity Cloud and work with your data in Unity Analytics.

The deltaDNA data collection endpoints will remain active for the remainder of 2024, so any Analytics data sent to them will continue to be processed and accessed through the Unity Analytics dashboard if project mapping has been undertaken. However, we would advise updating to the Unity Analytics SDK & REST API as early as possible, preferably before March 3rd whilst the deltaDNA Portal is still accessible.

Documentation

deltaDNA REST API
Unity Analytics REST API

Endpoints

The endpoints and formatting differ slightly between deltaDNA and Unity Analytics REST API.
Please note that Unity Analytics does not support the event hashing functionality that was available on deltaDNA.

deltaDNA

Each game project on deltaDNA has its own unique Collect API URL, this can be found on the Game Details page for each game. The Environment Keys for the Dev and Live environments can also be found on this page.

The Collect URL is: < COLLECT API URL>/collect/api/<Environment Key>/

So, on the deltaDNA Demo Account, the REST API Endpoint for the Live environment on the demo Game is : https://collect16056nwdmf.deltadna.net/collect/api/48380039933716137740673070315743/

Unity Analytics

Unity Analytics uses a single data collection endpoint that is common to all game projects

https://<COLLECT API URL>/api/analytics/collect/v1/projects/<PROJECT ID>/environments/<ENVIRONMENT NAME>

The Collect API URL is always https://collect.analytics.unity3d.com
The ProjectID can be found by navigating to the Project Settings page on your Unity Cloud Dashboard for the current project.
The Environment Name can be found on the Environments page on your Unity Cloud Dashboard for the current project.

The Unity Analytics endpoint for the production environment on the Demo Account, Demo Game would be.

https://collect.analytics.unity3d.com/api/analytics/collect/v1/projects/25088b95-5df2-4352-9d7b-e72d48d9e5fe/environments/production

Headers

deltaDNA

The only header required on deltaDNA REST API POST requests is

Content-Type: application/json

Unity Analytics

Unity Analytics also expects the POST request to be a UTF-8 encoded JSON string, but it also supports two additional parameters to support China Privacy Protection. These two additional parameters are only required for events from players in China. Please refer to the Submit Events section of the Unity Analytics REST API documentation for more info.

Content-Type: application/json
PIPL_CONSENT : 1
PIPL_EXPORT : 1
POST Body

The post body on deltaDNA and Unity Analytics requests are the same. Both can accept multiple events in an eventList array up to a maximum post size of 5Mb.

{
    "eventList": [
        {
            "eventName": "skillUsed",
            "userID": "D_098987AY127FAFS1192",
            "sessionID": "d32f4a04-e75b-42f0-a2a9-18c0805f09b1",
            "eventUUID": "dbf50615-30cc-4417-bb7b-e4a0451be8b7",
            "eventTimestamp": "2023-12-13 10:15:00.123",
            "eventParams": {
                "platform": "IOS",
                "skillID": "SKL_FIREB",
                "skillName": "Fireball",
                "success": false
            }
        },
        {
            "eventName": "missionFailed",
            "userID": "D_098987AY127FAFS1192",
            "sessionID": "d32f4a04-e75b-42f0-a2a9-18c0805f09b1",
            "eventUUID": "d5263bd4-d280-4fe5-97b9-265ed1885c77",
            "eventTimestamp": "2023-12-13 10:15:00.987",
            "eventParams": {
                "platform": "IOS",
                "missionID": "MIS_014",
                "missionName": "The bridge of death",
                "livesBalance": 2
            }
        }
    ]
}

{

"eventList": [

{

"eventName": "skillUsed",

"userID": "D_098987AY127FAFS1192",

"sessionID": "d32f4a04-e75b-42f0-a2a9-18c0805f09b1",

"eventUUID": "dbf50615-30cc-4417-bb7b-e4a0451be8b7",

"eventTimestamp": "2023-12-13 10:15:00.123",

"eventParams": {

"platform": "IOS",

"skillID": "SKL_FIREB",

"skillName": "Fireball",

"success": false

}

{

"eventName": "missionFailed",

"userID": "D_098987AY127FAFS1192",

"sessionID": "d32f4a04-e75b-42f0-a2a9-18c0805f09b1",

"eventUUID": "d5263bd4-d280-4fe5-97b9-265ed1885c77",

"eventTimestamp": "2023-12-13 10:15:00.987",

"eventParams": {

"platform": "IOS",

"missionID": "MIS_014",

"missionName": "The bridge of death",

"livesBalance": 2

}

]

}

Testing

The Unity Analytics Event Browser tool functions in just the same way as its equivalent on deltaDNA. It can be used to validate that events sent from the REST API are received correctly. It will display events received from the deltaDNA REST API and the Unity Analytics REST API.

You should also keep in mind that:

The optional eventUUID parameter is used to de-duplicate events, so make sure you generate a unique value for each event.
The optional eventTimestamp parameter will be populated with the value you provide, or with the UTC timestamp on the server when the event was received. Keep in mind that this can cause events received together in a batch to all have the same timestamp. So be sure to provide your own eventTimestamp if you intend to look at the sequence of events or the time between them.
If you provide a value for the userCountry parameter on newPlayer events it will be used in your event. If not, the userCountry will be set to the geo-location of the server that sent the event.