Recording Events for non-Unity games#

If you have a non-Unity game, the Collect REST API records and sends Events directly to Unity.

Analytics REST API#

To record an Event, make a 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:

https://collect.analytics.unity3d.com/collect/api/project/<Unity ProjectID>/<EnvironmentName>

A set of Custom Events can be configured per environment. In the request body, specify a JSON document corresponding to the event type, as described later.

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 recognized”.

Event 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 should adhere to the following format:

{
    "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, which is a unique string that identifies the player and is consistent across their subsequent play sessions. 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 persists for the duration of each player gameplay session and regenerates 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, and so on.

There might be occasions when you want 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’re not included in any player session calculations. Typical examples of GHOST events would be attribution events or transactional information originating from third party services.

eventUUID is an optional parameter which should be unique for each event. Adding the eventUUID will prevent the event being inserted twice. 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. If the eventTimestamp is missing, the server upon receipt of the event will infer the timestamp based on the time the event was received. The date format should like:

yyyy-MM-dd HH:mm:ss.SSS ±[hh]:[mm]

Where the ±[hh]:[mm] can be included to indicate a timezone offset from UTC.

For example:

"2021-12-30 16:55:00.321" or "2021-12-30 16:55:00.321 -08:00"

The order of the parameters doesn’t matter for JSON.

Parameters which aren’t required don’t have to be included in the document. They should be omitted altogether rather than sending empty or null parameters. Any event with a timestamp older than 31 days ago or newer than 24 hours in the future will be rejected as they are outside valid boundaries.

Sending bulk Events#

It’s possible to send multiple Events in a single POST. This approach is preferable due to efficiencies in connection pooling. Keep the POST length below 5MB; anything above might be rejected.

The format of each individual Event remains the same, but they’re represented in an eventList array containing individual Events. For example:

{
    "eventList": [
        {
            "eventName": "newPlayer",
            "userID": "GA_098987AY127FAFS1192",
            "sessionID": "f32f4a04-e75b-42f0-a2a9-18c0805f09b1",
            "eventUUID": "ebf50615-30cc-4417-bb7b-e4a0451be8b4",
            "eventTimestamp": "2021-03-30 16:55:00.321",
            "eventParams": {
                "platform": "IOS_MOBILE"
            }
        },
        {
            "eventName": "clientDevice",
            "userID": "GA_098987AY127FAFS1192",
            "sessionID": "f32f4a04-e75b-42f0-a2a9-18c0805f09b1",
            "eventUUID": "e5263bd4-5280-4fe5-97b9-265ed1885c76",
            "eventTimestamp": "2021-03-30 17:00:01.123",
            "eventParams": {
                "deviceName": "Bobs IPHONE",
                "deviceType": "iPhone5",
                "hardwareVersion": "v100.2442",
                "manufacturer": "APPLE",
                "operatingSystem": "iOS6",
                "operatingSystemVersion": "0.5",
                "browserName": "Safari",
                "browserVersion": "10"
            }
        }
    ]
}

Note: The Events inside a bulk Event list should be ordered in the order they occurred.