Limitations
These are the technical limitations currently for sending events.
- size of POST request
- event field validation
- frequency of unique values
Size of POST request
The collector has a POST size limit of 1MB in the request body. Read more in the troubleshooting section on 413 status codes.
Event field validation
When events are submitted they will each be validated. These validation rules are listed by each event in this documentation. Read more in the troubleshooting section on 400 status code.
Frequency of unique values
GameAnalytics have some additional limitation regarding the frequency of unique values for certain events. If these thresholds are exceeded during the day then the GameAnalytics servers will start to throttle the game.
Throttle
When a game is being throttled it means that certain processing of the raw data has stopped. This is often due to events containing too many unique values that result in aggregation being hard/impossible.
It is worth specifying that the collection of events is not suspended.
The result in the tool will be metrics flatlining. Many core metrics will still be there; like DAU etc. But event types (design, progression etc.) will not be updated.
How to solve it?
This happens rarely. Contact support and get information about why the throttle was activated and how to fix the implementation to avoid it.
Limitations
These are the recommended unique value limitations.
Default annotations
| Field | Unique Limit |
|---|---|
| build | 100 |
| platform | 30 |
| device | 500 |
| os_version | 255 |
| progression | 100 pr. event part |
| custom_01 | 50 |
| custom_02 | 50 |
| custom_03 | 50 |
Business Event
Field Unique Limit event_id (itemType) 100 event_id (itemId) 100 cart_type 10
Resource Event
| Field | Unique Limit |
|---|---|
| event_id (virtualCurrency) | 100 |
| event_id (itemType) | 100 |
| event_id (itemId) | 100 |
Design Event
| Field | Unique Limit |
|---|---|
| event_id (entire string) | 50000* |
* This is a very large threshold. The amount of tree-nodes generated will also affect if the game will be throttled. Having this many is not recommended and it can affect the GameAnalytics tool experience (downloading that much information to the browser).
Troubleshooting
The servers validate fields and reject events that do not pass. Therefore it is valuable to know which field(s) did not pass validation and the reason why.
The most common HTTP response status codes 200, 401, 400.
200 : OK
The request went well. All possible events sent were collected successfully.
401 : UNAUTHORIZED
Authorization could not be verified. Either the game keys are not correct or the implementation is not done properly for calculating the HMAC hash for the Authentication header.
413 : REQUEST ENTITY TOO LARGE
The collector has a size limit of 1MB in the request body. If the post body is less than 2 times the max limit (between 1M and 2MB) you get a 413 response code. If it is bigger than that you will get a closed connection from the collector.
Therefore when submitting a large amount of events the code should split them up. Use multiple requests one after the other. Again it is highly recommended to use gzip as this will reduce the size significantly.
400 : BAD REQUEST
This can happen in the following scenarios.
the data sent was not valid JSON (unable to decode) the JSON data sent was not a list the JSON contents (events) failed validation
In the first 2 cases there will be very little information in the response.
The last case will happen when one or more events fail to match it’s validation schema.
The servers will then not collect the failed events but still collect the valid events. Then reply with a JSON string containing a list of objects for each event that failed. Each error object will contain information about all the fields that might have failed validation for that specific event and also include the event fields that were submitted.
When receiving a 400 status code during implementation please review the response JSON to ascertain if it’s valid and a list. Then review what fields did not pass validation and fix.
If a batch contains two events (A and B) and A fails validation but B passes then A will be rejected and B collected.
Due to this – do not resubmit event data when a 400 response is received.
Look at the following 400 response error reply snippet example in JSON:
[
"event": {
"connection_type": "wifi",
"session_num": 1,
"session_id": "b887216b-3cfa-11e5-b8a9-a8206618c53b",
"device": "iPhone6.1",
"manufacturer": "apple",
"category": "user",
"user_id": "AEBE52E7-03EE-455A-B3C4-E57283966239",
"client_ts": 1438948324,
"os_version": "ios 8.2",
"custom_01": "ninja",
"engine_version": "unity 5.1.0",
"platform": "ios",
"sdk_version": "rest api v2",
"build": "alpha 0.0.1",
"v": 2
}
]
Re-submitting events
When queued events are sent to the collector servers they should each be marked locally as being submitted.
If the attempt failed due to no connection (no network etc.) or 413 (body too large) then the being submitted events should be put into queue again. If you get a 413 then try to split the events into even smaller batches and then submit. For all other responses (200, 401, 400 etc.) these events should be wiped.
Do not keep events and resubmit based on other reasons than offline or the 413 response.
In production a 400 response should be logged and the implementation fixed for the next time the game is released.
Character Encoding
Make sure your character encoding is UTF-8 for strings. Certain event_id strings require specific characters validated by matching a regex.
An example is the progression event_id string. This requires a match for this regex: ^(Start|Fail|Complete):[A-Za-z0-9\s-.()!?]64(:[A-Za-z0-9\s-.()!?]64)2$
The validation for this event_id can fail if using UTF-8 strings dynamically (like level names). These might contain other characters then just a-Z and numbers. Make sure to encode strings to support the requirements.
Users are reporting issues with failing authentication using the UTF-8 standard in Java. In this case make sure you encode to the ISO-8859-1 standard instead.