Data API 2.0
If, for some reason, you cannot use the devtodev SDK, or some events cannot be tracked on the client side, you can use the devtodev data API. Using the API, you can send a set of events that almost completely replicates the capabilities of the SDK. However, you will need to independently prepare data about the device/user and also independently track the start and duration of sessions.
Request format
URL:
https://api.devtodev.com/v2/analytics/report?appId=sampleApplicationId
Field | Required | Description |
---|---|---|
appId | Yes | devtodev application ID |
POST data is received by the server in compressed or text form, depending on the value of the "Content-type" field in the HTTP header.
All the transferred data must be in UTF8 encoding.
The archive must contain JSON with one or more events for one or several users.
The packet size cannot exceed 2 MB in its uncompressed state. Packages that exсeed this size can't be processed.
Headers:
Header | Type | Required | Description |
---|---|---|---|
Content-type | String | Yes | The possible values for the "Content-type" field are:
|
Example POST Data:
The reports
object contains:
Parameter | Type | Required | Description |
---|---|---|---|
deviceId | String (64) | Yes | Current (actual) Device ID |
previousDeviceId | String (64) | Should be sent if the Device ID is changed | Previous Device ID |
userId | String (64) | When accounting by User ID | Current (actual) User ID |
previousUserId | String (64) | Should be sent if the User ID is changed (renamed) | Previous User ID |
devtodevId | Long | No | Numeric user/device account ID in the devtodev database. We recommend using this identifier if you are using SDK and API at the same time. Get this identifier on the SDK side, save it on your server and use it to send data via API. Sending other identifiers is not necessary in this case. |
package | Array | Yes | Packets with events that happened to the user (see below) |
Each packet consists of the following fields:
Parameter | Type | Required | Description |
---|---|---|---|
language | String (3) | Yes | User/device language (ISO 639-1, ISO 639-2, ISO 639-3) |
country | String (2) | Yes | User/device country (ISO_3166-1_alpha-2). Only needed in the server-server protocol |
ip | String (15) | No | The IP address of the device. Only needed in the server-server protocol. Used to determine the user's country if country is not specified |
appVersion | String (64) | No | App version |
appBuildVersion | String | No | Application build version. A string value is used for compatibility across all platforms |
sdkVersion | String | No | Version of the integrated SDK |
bundle | String | No | Application bundle |
engine | String | No | Application platform/engine (Native, Unity, Unreal, Air) |
installationSource | String | No | Only for Android. The installer bundle is passed as the value. It determines where the application was installed from (apk, Google Play, Amazon, etc). Used to detect and prevent illegal apk installs |
events | Array | Yes | Events in the order they are generated (details below) |
Response
The server responds with code 200 if everything is OK.
HTTP Code | State |
---|---|
413 | Incorrect size of the data packet (exceeds the maximum) |
400 | devtodev App ID is absent |
401 | Incorrect devtodev App ID |
403 | Administrative restrictions on data received from a client |
400 | The error of data unpacking
|
400 | The error of JSON format
|
200 | OK. Data received |
Service Events
Device Info
Contains information about the user's device. It must be sent as the first event when a new user is created. Additionally, it is desirable to send an event at the beginning of each session.
Parameter | Platform | Required | Type | Description |
---|---|---|---|---|
code | Any | Yes | String | The unique ID of the event. Takes the value "di" |
timestamp | Any | Yes | Long | The date the event was generated. Unix timestamp in milliseconds |
osVersion | Any | No | String | Operating system version |
os | Any | No | String | OS family name (Android, iOS, Mac, Windows…) |
displayPpi | Any | No | Int | Screen pixel density |
displayResolution | Any | No | String | Screen resolution in pixels, sent as "longSide"x"shortSide" ("1024x768") |
displayDiagonal | Any | No | Double | Screen size (inches) |
manufacturer | Android, iOS, Mac | No | String | Device manufacturer (Apple, Samsung) |
model | Android, iOS, Mac | No | String | Device model. Value of the name (iOS), model (Android) |
deviceType | Any | No | Int | Device Type: 0 - Unknown 1 - Phone 2 - Tablet 3 - Desktop 4 - Watch 5 - TV 6 - Simulator |
timeZoneOffset | Any | No | Int | The UTC offset (or time offset) in seconds |
rooted | Any | No | Int | Is the device rooted |
isLimitAdTrackingEnabled | iOS, Android, Windows | No | Bool | Whether ad tracking restriction is enabled |
userAgent | Any | No | String | User-Agent header |
idfv | iOS, Mac | No | String | identifierForVendor |
idfa | iOS, Mac | No | String | advertisingIdentifier |
androidId | Android | No | String | Device SSAID. Not recommended for use |
advertisingId | Android, Windows | No | String | Advertising ID |
serialId | Android, Windows | No | String | Build.Serial (Android). Not recommended for use. |
uuid | Android, Windows, iOS, macOS | No | String | |
instanceId | Android | No | String | InstanceId.Get(); |
sandboxState | iOS | No | Int | Information about how the application is built: undefined (0) / sandbox (1) / production (2) |
Example
Session Start
Sends information about the start of a new session.
Parameter | Required | Type | Description |
---|---|---|---|
code | Yes | String | The unique ID of the event. Takes the value "ss" |
timestamp | Yes | Long | The date of the new session start. Unix timestamp in milliseconds |
level | Yes | Int | User (player) level at the time the event was generated |
sessionId | No | Long | The ID of the current session. This is a kind of key by which you can link all user events that occurred during one session. This can be a session start timestamp, or you can use some custom numeric ID, or the user's session sequence number if you have that data. |
Example
User Engagement
Sends information about the duration of user activity. This can be either the full length of the session or a part of the user's session while the application was in focus.
Parameter | Required | Type | Description |
---|---|---|---|
code | Yes | String | The unique ID of the event. Takes the value "ue" |
timestamp | Yes | Long | The date the event was generated. Unix timestamp in milliseconds |
level | Yes | Int | User (player) level at the time the event was generated |
length | Yes | Int | Full session duration or a part of a user session in seconds |
sessionId | No | Long | The ID of the current session |
Example
Setting User Tracking Status (GDPR)
This event denies/allows tracking of user data and also implements the right to be forgotten in accordance with the requirements of the GDPR.
A developer must use this event in case a user doesn’t want their data to be sent and processed in the devtodev system.
When calling the event with the parameter "trackingAllowed": false, it is a command to the server to delete all user’s personal data that has been collected by devtodev from this app and a command to block the collection of any data of this user in future.
The user will remain in the devtodev system only as an impersonal unit in the previously aggregated metrics.
If it is set to “true”, tracking can be enabled again. In this case, the user will be considered new.
Parameter | Required | Type | Description |
---|---|---|---|
code | Yes | String | The unique ID of the event. Takes the value "ts" |
trackingAllowed | Yes | Bool | Enable (true) or disable (false) user tracking |
timestamp | Yes | Long | The date the event was generated. Unix timestamp in milliseconds |
Example
Alive
Service event. Not obligatory. Ping event for the server. It is required to correctly display a player online if more than 5 minutes have passed since his last sent event.
Parameter | Required | Type | Description |
---|---|---|---|
code | Yes | String | The unique ID of the event. Takes the value "al" |
timestamp | Yes | Long | The date the event was generated. Unix timestamp in milliseconds |
sessionId | No | Long | The ID of the current session |
Example
User properties
People
Each devtodev project can have up to 30 custom user properties.
Attention! We strongly recommend that you do not use these properties to transfer and store data that fits the definition of personal data!
Parameter | Required | Type | Description |
---|---|---|---|
code | Yes | String | The unique ID of the event. Takes the value "pl" |
timestamp | Yes | Long | The date the event was generated. Unix timestamp in milliseconds |
level | Yes | Int | User (player) level at the time the event was generated |
parameters | Yes | Object<Key, Value> | User characteristics in key-value format. May contain predefined (tester, cheater, name, email, phone, photo, gender, age) and custom user propery names. User custom property values can be a number, a string (up to 500 symbols), or a boolean value |
sessionId | No | Long | The ID of the current session |
Predefined user properties (in addition to 30 custom user properties).
Property | Required | Type | Description |
---|---|---|---|
tester | No | bool | Set true if user is a tester. This user's data will not be used to calculate metrics. |
cheater | No | bool | Set true if user is a cheater. This user's data will not be used to calculate metrics. |
Example
Basic Events
Custom Event
If you want to track non-basic events (below), you can create custom events of your own. How you are going to apply them, depends solely on you.
devtodev supports not more than 300 custom event names in a single project. Events that exceed the limit of custom event names will be discarded. Try to integrate the tracked actions by type to the event name level, and move the characteristic tags to the parameters.
For example, if you need to track purchases of “Paper” and “Pen” items, you don’t need to create two events with the names “Paper Purchase” and “Pen Purchase”. Instead. create a single “Purchase” event and add an “Item” parameter with the appropriate value of “Paper” or “Pen”. This way, you can use just one event to track many items.
For a string parameter, you can use no more than 50,000 unique values for the entire history of events. If the number of unique values exceeds the limit, the parameter gets locked by the system and is discarded from the received data. Therefore, we don’t recommend using highly variable parameters like user IDs or time as string values (moreover, they are automatically added to the event).
We strongly recommend that you do not change the data type passed in the same parameter. If you change the data type in a parameter, it will be duplicated with the same name, which may cause issues while processing reports.
We strongly recommend that you do not use custom event properties to transfer and store data that fits the definition of personal data!
Parameter | Required | Type | Description |
---|---|---|---|
code | Yes | String | The unique ID of the event. Takes the value "ce" |
timestamp | Yes | Long | The date the event was generated. Unix timestamp in milliseconds |
level | Yes | Int | User (player) level at the time the event was generated |
name | Yes | String (72) | Custom event name |
parameters | No | Object<Key (32),Value> | Custom event parameters |
sessionId | No | Long | The ID of the current session |
Example
Real Payment
To track payments in a real currency, dispatch this event right after the system validates that the payment went through successfully. The event is fundamental and mandatory for all the app metrics related to monetization.
By default (easy to change in the app’s settings), the devtodev server invalidates transactions with previously-used identifiers. Additionally, the server performs identifier checks based on their outer appearance in order to avoid obvious fraud.
Parameter | Required | Type | Description |
---|---|---|---|
code | Yes | String | The unique ID of the event. Takes the value "rp" |
timestamp | Yes | Long | The date the event was generated. Unix timestamp in milliseconds |
level | Yes | Int | User (player) level at the time the event was generated |
productId | Yes | String (255) | Product name. We recommend using the product SKU |
orderId | Yes | String (64) | Unique transaction ID |
price | Yes | Double | Price in user currency |
currencyCode | Yes | String (3) | ISO 4217 alphabetic code of the user's currency |
sessionId | No | Long | The ID of the current session |
Example
Onboarding (tutorial)
Tracks the progress of the user's initial training (tutorial). The event is used to build a funnel through which users go through learning stages (steps). Each step is represented by an integer greater than 0. If you plan to add additional intermediate learning steps, you can number the steps initially, for example, in increments of 10. Additionally, three constants are used to describe the start of training, successful completion of training, and skipping the entire training process.
Recommended sequence for dispatching events:
Training started (-1).
Sequential sending of events at the entrance to the next learning step (1...N).
Completion of training after passing the last step of training (-2).
he tutorial skip logic assumes that a single event with a value of 0 is sent, replacing the entire sequence described above.
Parameter | Required | Type | Description |
---|---|---|---|
code | Yes | String | The unique ID of the event. Takes the value "tr" |
timestamp | Yes | Long | The date the event was generated. Unix timestamp in milliseconds |
level | Yes | Int | User (player) level at the time the event was generated |
step | Yes | Int | Tutorial step number or predefined values (0, -1, -2 see above) |
sessionId | No | Long | The ID of the current session |
Example
Virtual Currency Payment
This event is for games only.
Pass this event after every purchase if you want to track in-app (virtual) currency spends and items’ popularity. You can apply this event to both games and any apps with virtual currency.
Parameter | Required | Type | Description |
---|---|---|---|
code | Yes | String | The unique ID of the event. Takes the value "vp" ("ip" in the previous version of the API) |
timestamp | Yes | Long | The date the event was generated. Unix timestamp in milliseconds |
level | Yes | Int | User (player) level at the time the event was generated |
purchaseAmount | Yes | Int | Number of items purchased |
purchasePrice | Yes | Object<String (24), Number> | Currency and price of the purchased items (or currencies, if there are multiple) |
purchaseType | Yes | String (96) | The group to which the item belongs |
purchaseId | Yes | String (32) | Item ID or name |
sessionId | No | Long | The ID of the current session |
Example
Currency Accrual
This event is for games only.
The event involves the accumulation of in-game currency or resources. It contains data on the amount of in-game currency earned or purchased by the user. It is highly undesirable to send this data transactionally. Instead, please send aggregated data for a specific period, such as 5-10 minutes. Additionally, the accumulation of data must be interrupted, and an event should be sent if the user's level has changed.
Attention! The total number of tracked unique resources (virtual currencies) cannot exceed 30 items throughout the project's lifespan.
Furthermore, apart from grouping by type (earned/purchased), there is also a grouping by the source of income.
Parameter | Required | Type | Description |
---|---|---|---|
code | Yes | String | The unique ID of the event. Takes the value "ca" |
timestamp | Yes | Long | The date the event was generated. Unix timestamp in milliseconds |
level | Yes | Int | User (player) level at the time the event was generated |
bought | Yes one or both (bought and earned) | Object<String, Object<String (24), Number>> | Resources of the type "bought" (purchased) aggregated over a specific period by source and resource name |
earned | Yes one or both (bought and earned) | Object<String, Object<String (24), Number>> | Resources of type "earned" aggregated over a specific period by source and resource name |
sessionId | No | Long | The ID of the current session |
Current Balance
This event is for games only.
This event is used to generate a preset game report called Economy Balance (currency balance with grouping by days). This report shows the approximate amount of virtual currency on users' hands, which is useful for planning and checking the results of campaigns aimed at removing excess virtual currency from the application.
This event should not be sent more than once per day for a user.
Parameter | Required | Type | Description |
---|---|---|---|
code | Yes | String | The unique ID of the event. Takes the value "cb" |
balance | Yes | Object<String, Long> | User's balances of virtual currencies or resources at the time the event was generated |
timestamp | Yes | Long | The date the event was generated. Unix timestamp in milliseconds |
level | Yes | Int | User (player) level at the time the event was generated |
sessionId | No | Long | The ID of the current session |
Example
Level Up
This event is for games only.
Leveling up the user (player). The event is triggered when the user reaches a new level. In addition o the achieved level number, you can also include data on the balance of virtual currencies or resources at the time the new level was reached, as well as the total amount of currencies or resources spent, earned and purchased by the user during the previous level progression.
Attention! The total number of tracked unique resources (virtual currencies) cannot exceed 30 items throughout the entire life of the project.
Parameter | Required | Type | Description |
---|---|---|---|
code | Yes | String | The unique ID of the event. Takes the value "lu" |
timestamp | Yes | Long | The date the event was generated. Unix timestamp in milliseconds |
level | Yes | Int | User (player) level achieved by the user |
balance | No | Object<String (24), Number> | User's balances of virtual currencies or resources at the time of leveling up |
spent | No | Object<String (24), Number> | Total expenses of resources (virtual currency) by the user during level progression In the SDK, this data is aggregated from virtual currency payment events |
earned | No | Object<String (24), Number> | The total amount of resources (virtual currency) earned by the user during level progression In the SDK, this data is aggregated from CurrencyAccrual events with the "earned" type |
bought | No | Object<String (24), Number> | The total number of resources (virtual currency) purchased by the user for real currency during level progression In the SDK, data is aggregated from the CurrencyAccrual events with the "bought" type |
sessionId | No | Long | The ID of the current session |
Example
Progression Event
This event is for games only.
First of all, the progression event is used in games with short (within one game session) areas/game levels, for example, match 3 games. You can use the event to collect data on how well or how fast users complete levels, how difficult it is for them, how many resources they gained or spent, and other relevant parameters.
Parameter | Required | Type | Description |
---|---|---|---|
code | Yes | String | The unique ID of the event. Takes the value "pe" |
timestap | Yes | Long | The date the event was generated. Unix timestamp in milliseconds |
level | Yes | Int | User (player) level at the time the event was generated |
parameters | Yes | Object | Event parameters. See below |
spent | No | Object<String (24), Number> | Resources consumed during an area completion |
earned | No | Object<String (24), Number> | Resources earned during an area completion. |
name | Yes | String (40) | The name of the event. It is usually the number or the name of the area/location/level. |
sessionId | No | Long |
parameters object:
Parameter | Required | Type | Description |
---|---|---|---|
difficulty | No | Int | An optional difficulty value |
source | No | String (40) | The name of the previous progression event used for connecting events together. E.g. a previous area visited by the player |
success | Yes | Bool | The completion event result: “true” if successful, “false” if unsuccessful/lost |
duration | Yes | Long | Time in seconds taken to complete the area |
Example
All events generated during the passage of the location are recommended to be marked with the key "inProgress," the value of which indicates the name of the location (Progression event name).
Example
Secondary Events
Referral
Tracking the source of the application installation. Sent once per user. Does not need to be sent if ad trackers such as AppsFlyer are integrated in the project settings or the devtodev custom postback API is used.
Parameter | Required | Type | Description |
---|---|---|---|
code | Yes | String | The unique ID of the event. Takes the value "rf" |
timestamp | Yes | Long | The date the event was generated. Unix timestamp in milliseconds |
source | No | String | Ad network name |
campaign | No | String | Ad campaign name |
content | No | String | Campaign content (for example, for A/B testing of site elements or contextual ads) |
medium | No | String | Traffic type |
term | No | String | Campaign search term (for example, PPC keywords) |
sessionId | No | Long | The ID of the current session |
Example
Ad Impression
The event is used for individual tracking of ad revenue on user devices. This method is used if there are CPI data available on the client device (they can be obtained from the ad network SDK).
Do not apply this event if you use ad networks that utilize the server-server protocol for sending ad revenue data (ironSource, AppLovin MAX, and Fyber networks) and you already set up this method of data collection because if you use both data sources, your revenue data may be duplicated.
Parameter | Required | Type | Description |
---|---|---|---|
code | Yes | String | The unique ID of the event. Takes the value "adrv" |
timestamp | Yes | Long | The date the event was generated. Unix timestamp in milliseconds |
source | No | String (100) | Impression data source name |
ad_network | Yes | String (100) | The name of the ad network that delivered the impression |
placement | No | String (100) | Placement of the banner |
ad_unit | No | String (100) | Banner title |
revenue | Yes | Double | Reward for displaying a banner in USD |
sessionId | No | Long | The ID of the current session |
Example
Social Connect
The event tracks the user's connection to a social network. It is sent at the moment when the application receives information about the successful authorization of the user on the social network.
Parameter | Required | Type | Description |
---|---|---|---|
code | Yes | String | The unique ID of the event. Takes the value "sc" |
timestamp | Yes | Long | The date the event was generated. Unix timestamp in milliseconds |
level | Yes | Int | User (player) level at the time the event was generated |
socialNetwork | Yes | String | Code or name of the social network. May contain predefined values (see below) |
sessionId | No | Long | The ID of the current session |
Example
Preset social network codes
Social Network | Code |
---|---|
Vkontakte | vk |
tw | |
fb | |
Google Plus | gp |
wp | |
Viber | vb |
Evernote | en |
Google Mail | gm |
in | |
pi | |
Qzone | |
rt | |
Renren | rr |
Tumblr | tb |
Social Post
The event tracks the user's posts on the social network. It is dispatched when a success report is received from the network, if possible.
Parameter | Required | Type | Description |
---|---|---|---|
code | Yes | String | The unique ID of the event. Takes the value "sp" |
timestamp | Yes | Long | The date the event was generated. Unix timestamp in milliseconds |
level | Yes | Int | User (player) level at the time the event was generated |
socialNetwork | Yes | String | Code or name of the social network. May contain predefined values (see above) |
postReason | Yes | String | Reason for posting |
sessionId | No | Long | The ID of the current session |
Example
Example
An example of a package describing a single session of a single user.
Note: devtodev does not accept data that is older than 7 days and data that is more than 3 hours in the future. If you want to use this example, you will need to edit the timestamp
parameters.
Last updated