1 of 11

Server API

List of all devtodev APIs

Below you can find APIs for 3rd party services. You can use them in case devtodev does not provide an integration to a specific 3rd party service.

Check the list of available services for Ad Revenue .

Check the list of available Attribution trackers .

Subscription API

General provisions

Endpoint:

https://statgw.devtodev.com/subscriptions/api?apikey={project’s API key}

Query type: POST

The query body is a JSON object with fields described in the table below.

Fields

Notification types

Server response

If the notification is accepted, the response status is 200. If the query is incorrect, the response status is 400. In case of an internal error, the response status is 500.

In case the status is 400 or 500, the error description will be indicated in the query body as a JSON object:

{
  "title": "Bad request",
  "error": "Not set parameter api-key"
}

Notification types and corresponding fields

Available notification types for a trial (all postbacks should be flagged as ‘isTrial = true’):

purchase - trial subscription
cancellation - subscription cancellation before the end of that trial

2. Available notification types for subscription purchase:

purchase - subscription purchase
renewal - subscription renewal
cancellation - premature termination of a subscription and proportional refund
refund - money refund

Trial purchase

Trial cancellation

Subscription purchase

Subscription renewal

Subscription cancellation

Subscription refund

Query example

POST https://statgw.devtodev.com/subscriptions/api?apikey=ak-cDNRQl0Lypq4AOUrx8aGGMnmJT1FSebd
{
   "notificationType":"PURCHASE",
   "transactionId":"transactionId",
   "startDateMs":1640072573468,
   "expiresDateMs":1640245373468,
   "product":"com.demo.bundle.weekly",
   "price":90.9,
   "currency":"RUB",
   "isTrial":false,
   "devtodevId":4064192
}

Push API

To use Push API you need to have individual User API token, which can be found in the settings of space.

You’ll see the block with User API token on the space settings page only in case if your tariff plan and access rights allow to use devtodev API. You can reset User API token or create it again on the same page.

Please attend, if you use several spaces, in every space user has individual User API token.

Request format

The request of assignment should be sent to:

Where

user_token - individual User API token of a user. It could be sent with both GET and POST methods.
v1 - the current version of API

Request content is sent with POST method in JSON format.

The body of a request can contain the following properties:

An example of a request for sending a simple notification to an iOS device:

POST

Response format

If a request is formed correctly and there are no obstacles for sending a notification to users, an answer is JSON of the following type:

where

audience (number) - the number of users found
successful (number) - the number of successfully sent notifications
erroneous (number) - the number of notifications rejected by the delivery service
error_details (array) - a detailed description of reasons of a delivery fail

In case there is an error in a request, an answer is made in the following format:

where

status_code (number) - a general status of an error
errors (array) - an array of error descriptions
code (number) - the exact code of an error from the table of errors
msg (string) - a brief description of an error

The list of possible errors is given in a table.

List of possible errors

Besides the errors listed above, error_details field may contain errors from the connected notification services. You can find descriptions of such errors in documentation for these services:

IOS

User identifiers

In order to find a user to whom you need to send a notification, it is possible specify one or several available identifiers:

Notification settings

The object of a message for the iOS platform contains 2 fields:

payload (object) - describes the main content of a notification
options (object) - describes the optional settings of notification delivery

Notification content settings ("payload" object)

Notification delivery and display settings (“options” object)

Button templates

The text on the buttons, which are on the list of templates, is translated into N languages and displayed to users individually according to the location of a device.

Examples

Push

POST

Hidden push

POST

Android

User identifiers

In order to find a user to whom you need to send a notification, it is possible to specify one or several available identifiers:

Notification settings

The object of a message for the Android platform contains 2 fields:

payload (object) - describes the main content of a notification
options (object) - describes the optional settings of notification delivery

Notification content settings ("payload” object)

Notification delivery and display settings ("options" object)

Examples

Visible push notification

https://devtodev.com/api/v1/push/send

POST

{
    "user_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "campaign_tag": "campaign name",
    "pack_id": "uniqueid1234",
    "audience": [{
        "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "advertisingId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "androidId": "xxxxxxxxxxxxxxxxxxxxxxxxx",
        "userId": "xxxxxxxxxxxx"
    }],
    "android": {
        "payload": {
            "title": "Title of the notification",
            "text": "Notification content.",
            "data": {
                "key1": "value",
                "key2": "15"
            },
            "small_icon": "smallicon",
            "icon": "midicon",
            "image": "https://domain.com/pic.png",
            "sound": "bingbong",
            "vibration": true,
            "led_color": "#ff0000",
            "color": "#ff0000",
            "action": {
                "url": "http://www.domain.com"
            },
            "interactive": {
                "buttons": [{
                    "id": "accept",
                    "text": "Accept",
                    "handling": "foreground",
                    "action": {
                        "url": "http://www.domain.com/accept"
                    }
                }, {
                    "id": "decline",
                    "text": "Decline",
                    "handling": "background"
                }]
            }
        },
        "options": {
            "hidden": false,
            "priority": "normal",
            "expire": 36000,
            "collapse_key": "collapse1"
        }
    }
}

Hidden push notification

https://devtodev.com/api/v1/push/send

POST

{
    "user_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "campaign_tag": "campaign name",
    "pack_id": "uniqueid1234",
    "audience": [{
        "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "advertisingId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "androidId": "xxxxxxxxxxxxxxxxxxxxxxxxx",
        "userId": "xxxxxxxxxxxx"
    }],
    "android": {
        "payload": {
            "data": {
                "key1": "value",
                "key2": "15"
            }
        },
        "options": {
            "hidden": true,
            "priority": "normal",
            "expire": 36000
        }
    }
}

Windows UWP

devtodev Push API supports two different formats of notification sending to Windows operational systems:

UWP format described in this section can be used only for Windows 10 and Windows Phone 10. It is described by the "uwp" object.
works on a basis of Legacy tiles and toast schema. It can be used for Windows Phone 8.1, Windows Phone 10, Windows 8.1, Windows 10. It is described by the "windows" object.

Use this object (“uwp”) if your clients are users of OS Windows 10 and Windows Phone 10 only. With the help of this method it is possible to realize more opportunities offered by Windows 10.

User identifiers

In order to find an addressee to whom you need to send a notification, it is possible to specify one or several available identifiers:

Notification settings

Object "uwp" can contain 2 properties:

The property that describes a message can be represented by one of 4 possible objects: - toast (object) - the result of sending is the delivery of toast-notification - raw (object) - sends a hidden toast-notification - tile (object) - changes the tile content of an app - badge (object) - changes the value of a badge field displayed on a tile
The property that describes additional parameters of a message is represented by the object “options”. Optional.

Toast-notification content ("toast" object properties):

Example

Tile ("tile" object properties)

In UWP format every of tile’s size must be described separately, therefore, the object “tile” can contain up to 4 properties:

small
medium
wide
large (only for desktop)

Each of these sizes is described by an object with the following properties:

Example

Hidden notification ("raw" object properties):

Example

Badge ("badge" object properties):

Example

Windows

devtodev Push API supports two different formats of notification sending to Windows operational systems:

Universal format described in this section works on the basis of Legacy tiles and toast schema. It can be used on Windows Phone 8.1, Windows Phone 10, Windows 8.1, Windows 10. It is described by the "win" object.
UWP format - can be used only for Windows 10 and Windows Phone 10. It is described by the "uwp" object.

User identifiers

In order to find a user to whom you need to send a notification, you can specify one or several available identifiers:

Notification settings

Object "windows" can contain two properties :

The property that describes a message can be represented by one of 4 possible objects:

toast (object) - the result of sending is the delivery of toast-notification
raw (object) - sends a hidden toast-notification
tile (object) - changes tile content of an app
badge (object) - changes the value of a badge field displayed in a tile of an app

The property that describes additional parameters of a message represented by the object “options”. Optional.

Toast-notification content ("toast" object properties):

Example

{
    "user_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "campaign_tag": "campaign name",
    "pack_id": "uniqueid1234",
    "audience": [{
        "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "advertisingId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "serialId": "xxxxxxxxx",
        "customUid": "xxxxxxxxxxxx"
    }],
    "win": {
        "toast": {
            "title": "Toast title",
            "text": "Toast message",
            "data": {
                "key1": "value",
                "key2": "15"
            },
            "icon": "https://domain.com/pic.png",
            "sound": "default",
            "action": {
                "url": "http://www.domain.com"
            },
            "interactive": {
                "buttons": [{
                    "id": "accept",
                    "text": "Accept",
                    "handling": "foreground",
                    "action": {
                        "url": "http://www.domain.com/accept"
                    }
                }, {
                    "id": "decline",
                    "text": "Decline",
                    "handling": "background"
                }]
            }

        },
        "options": {
            "expire": 36000
        }
    }
}

Hidden notification ("raw" object):

Example

{
    "user_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "campaign_tag": "campaign name",
    "pack_id": "uniqueid1234",
    "audience": [{
        "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "advertisingId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "serialId": "xxxxxxxxx",
        "customUid": "xxxxxxxxxxxx"
    }],
    "win": {
        "raw": {
            "data": {
                "key1": "value",
                "key2": "15"
            },
            "badge": "+1"
        }
    }
}

Tile-notification content ("tile" object):

Example

{
    "user_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "campaign_tag": "campaign name",
    "pack_id": "uniqueid1234",
    "audience": [{
        "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "advertisingId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "serialId": "xxxxxxxxx",
        "customUid": "xxxxxxxxxxxx"
    }],
    "win": {
        "tile": {
            "text1": "Text 1",
            "text2": "Text 2",
            "text3": "Text 3",
            "text4": "Text 4",
            "with_header": "true",
            "image": "https://domain.com/pic.png"
        },
        "options": {
            "expire": 36000
        }
    }
}

Badge ("badge" object):

Example

{
	"user_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
	"app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
	"campaign_tag": "campaign name",
	"pack_id": "uniqueid1234",
	"audience": [{
		"token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
		"advertisingId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
		"serialId": "xxxxxxxxx",
		"customUid": "xxxxxxxxxxxx"
	}],
	"win": {
		"badge": {
			"badge": "99"
		}
	}
}

Additional settings of notification delivery and display ("options" object)

Raw Export

devtodev RAW export API

To use RAW data export API you need to have an individual User API token, which can be found in the settings of space.

If some applications of the space are inaccessible to the owner of User API token, then the owner can’t get access to the export of data of these applications. But the access to specific metrics it not extended to the access of raw data.

Please attend, if you use several spaces, in every space user has an individual User API token.

The pattern of communication with devtodev RAW data export API

The process of getting data consists of three steps:

job assignment
getting the status of performance
getting the report file by link

Let’s have a look at these steps.

Job assignment

This step is the most important, and its description is the longest one.

The request of assignment should be sent to:

https://devtodev.com/api/v1/rawexport/setjob?user_token=USER_API_TOKEN

Where

user_token - individual User API token of the user. It could be sent with both GET and POST methods.
v1 - current version of API

The request content is sent with POST method in JSON format.

The body of the request contains the following properties:

List of available events and their identificators

Every standard event in devtodev SDK corresponds with two-letters identificator. In case of custom events, the name of the event is the identificator. Also you can use group identificators (start with @).

Custom events filtering

If you’re interested in the export of custom events according to some specific conditions, you should set the objects with the following properties in the array of the event list:

User card filtering

If you want to export events from a specific audience, you can filter them by the properties of the user card. Only the events that occurred with the filtered users will be included in the exported data.

Caution! Filtering uses the property values of the user card at the time of the data export request.

The names of the properties are the same as the column names in the "users" table of the project, which you can find in the SQL report.

The table shows the fields by which filtering is possible:

List of comparison operators which can be applied in filter

The filter can be described with an object, where the following comparison operators can be the properties:

The empty object describes the filter which selects all the events where the parameter value is not null or empty string.

Examples

https://devtodev.com/api/v1/rawexport/setjob

POST

{
	"user_token": "USER_API_TOKEN", // It is obligatory, if it’s not sent with GET.
	"app_id": "af0606ed-bbdc-065a-952c-0d92561f107c",  // Obligatory. Application identificator.
	"start_date": 1464709200,  // Obligatory. Unix time of export start date.
	"end_date": 1464739200,  // Obligatory. Unix time of export end date.
	"events": [ //Not obligatory. List of events to export.
		"tr", // Export all  Tutorial step events
		"customEvent1Name",  // Export all customEvent1Name events
        //{"name": "customEvent1Name"} - alternative way with the same result
		{
			"name": "customEvent2Name",
			"filters": {  // Object with filter conditions
				"paramName1": {
					// 5<paramName1<=10 and paramName1!=8
					"lte": 10,
					"gt": 5,
					"neq": 8
				},
				"paramName2": {
					//Parameter paramName2 is equal to the one of elements.
					"eq": ["a","b","c"] 
				},
				"paramName3": {} // paramName3 is not empty.
			}
		}
	],
	"user_card_filter": { //user card properties filter object
		"paramName1": { //name of preset or custom user card parameter
			"lte": 10,
			"gt": 5,
			"neq": 8
		},
		"paramName2": { //name of preset or custom user card parameter
			"eq": ["a", "b", "c"]
		}
	}
}

Or another way with event group identificator.

{
	"user_token": "USER_API_TOKEN",
	"app_id": "af0606ed-bbdc-065a-952c-0d92561f107c",
	"start_date": 1464709200,
	"end_date": 1464739200,
	"events": ["@custom_events"] //Export all custom events
}

The format of the response to the job assignment

The response in case of successful start execution:

{
	"status_code": 200,
	"data": "JOB_ID"
}

Where

status_code - is the HTTP status code
data - an identificator which is assigned to the job

If you get this response, you can go to the next stage - request of job status (else go to Error handling).

Getting the status of performance

With the job identificator, you can request its current status, using the following request:

https://devtodev.com/api/v1/rawexport/getprogress?user_token=USER_API_TOKEN

The body of request can contain the following properties:

The format of the response to the request of status

The response to the request of status can be one of the following:

The job is in the queue
The job is in progress
The job is done
Error of job performance

Let’s explore every variant.

The job is in the queue

{  
	"status_code":202,
	"data":{  
		"status":"pending",
		"percent_complete":0
	}
}

The job is in progress

{  
	"status_code":200,
	"data":{  
		"status":"running",
		"percent_complete":10
	}
}

The job is done

{  
	"status_code":201,
	"data":{  
		"status":"complete",
		"percent_complete":100,
		"result":{  
			"msg":"Report file is ready",
			"format":"csv",  // Format of report files in archive
			"url":"https://devtodev.com/api/v1/rawexport/download/?job_id=JOB_ID&user_token=USER_API_TOKEN",
			"ttl": 100500, // Report lifetime from the end of the performance to the removal
			"expire":123434534534  // Date when the report will be removed (in UNIX-time format)
		}
	}
}

To get the report use the link in the URL property.

The report file is zip-archive with files in .CSV format. Every file contains data about one event and/or alias (which was set in the filter in job assignment).

If there are no events according to the query conditions, the response will be the following:

{  
	"status_code":200,
	"data":{  
		"status":"complete",
		"percent_complete":100,
		"result":{  
			"msg":"Unfortunately the result of your request is empty. Please try to change the report conditions."
		}
	}
}

Error handling

The error can raise either at the moment of job assignment or at the moment of checking the status. The format of response in case of error is the same: In case there is an error, a response is made in the following format:

{
    "status_code": 400,
    "errors": [{
        "code": 3,
        "msg": "Error description"
    }]
}

where

status_code (number) - a general status of an error
errors (array) - an array of error descriptions
code (number) - the exact code of an error from the table of errors
msg (string) - a brief description of an error

The list of possible errors is given in a table.

Limitations

There are the following limitations to devtodev RAW data export API:

List of available events

Below you can find the description of each table for events available for export.

Users

This file is always attached to the exported file. The table contains a list of users who performed the exported events. It also contains their characteristics available at the time of the export.

GameSessions

This file contains entries on session starts and user activity times for the selected export period. The table contains session starts (rows with filled session_starts field) and time when the app was in focus (rows with filled activity_duration field).

IngamePurchase

This file contains entries on virtual purchases in the app.

Install

A user registration event used in the devtodev database. Usually, the registration date is the same as the date of the first launch of the app.

LevelUp

Event for when the user reaches a certain game level.

NewUserUpdate

Some user properties updates for the selected export period. (devtodev ID, logged IP, os_version).

Payments

List of user transactions. Purchases for real currency.

Progression

This file contains a list of triggered Progression events.

SocialNetworkConnects

Social media connection events.

SocialNetworkPosts

Social media publication events.

SubscriptionPayments

Subscription events: buying, renewal, and refund. This file contains only subscription events that impact revenue.

Subscriptions

All subscription events.

Tutor

Tutorial steps events.

UDIDs

This file contains information about changes of user and device identifiers during the selected export period.

UserUpdate

This file contains data on user characteristics and devices updates for the selected export period.

AdImpression

This file contains app’s ad impression events. Data from ad networks or the Ad Impression event.

CustomEvent.{EventName}

This file contains custom events with {EventName} name.

Labels API

Obtaining the User API token

In order to be able to use Labels API you must have an individual User API token, which can be found in space settings in devtodev system.

You will be able to see the interface unit with User API token in space settings only in case your price plan and access rights (role) allow you to use devtodev API. You can discard User API token or create it again on the same page.

Pay your attention that if you use several spaces, each of them will have an individual User API token.

Obtaining the list of categories

The result of the request is the obtaining of the list of all existing labels categories for the app.

Request:

https://www.devtodev.com/api/v1/labels/categories/get

POST

{
	"user_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", // devtodev user API token
	"app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"  // devtodev App ID
}

Response:

{
	"status_code": 200,
	"data": {
		"status": "complete",
		"categories": [
			"category name",
			"category name 2"
		]
	}
}

Removing categories

The request is used to remove or rename a category. The category can be removed only if its full name is specified. One request can remove only one category. In case the parameter move_labels_to_category is specified, labels that belong to the category that is going to be removed will be transfered to the specified category. If the specified category doesn't exist, it will be created. If move_labels_to_category is not specified, all the labels that belong to the category will be removed.

Request:

https://www.devtodev.com/api/v1/labels/categories/delete

POST

{
	"user_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
	"app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
	"category": "category to be removed",
	"move_labels_to_category": "category to which the labels will be moved"
}

Response:

{
	"status_code": 200,
	"data": {
		"status": "deleted",
		"category": "category to be removed"
	}
}

Obtaining the list of labels

The result of the request is the obtaining of the list of labels that are presented as objects.

You can use filters to get some specific labels you need. In case no filter is specified, you will receive the whole list of labels. It is possible to use any combination of fields in a filter.

Request:

https://www.devtodev.com/api/v1/labels/get

POST

{
	"user_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
	"app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
	"filters": {
		"id": {
			"in": [100500, 100501]
		},
		"category": {
			"in": ["category name", "category name 2"]
		},
		"start_date": {
			"gte": 1478625206
		},
		"end_date": {
			"lte": 1478625206
		}
	}
}

Response:

{
	"status_code": 200,
	"data": {
		"status": "complete",
		"labels": [{
			"id": 100500,
			"name": "label name",
			"description": "short label description",
			"category": "category name",
			"start_date": 1478625206,
			"end_date": 1478625206
		}]
	}
}

List of comparison operators that can be applied in a filter

The filter can be described with an object, where the following comparison operators can be the properties:

The empty object describes the filter that selects all the events in which the parameter value is not null or empty string.

Adding labels

In case the specified category doesn't exist, it will be created. If string values of fields exceed the maximum, they will be cut off.

If you need to specify an event without time length, start_date must be equal to end_date or end_date must not be specified.

Request:

https://www.devtodev.com/api/v1/labels/add

POST

{
	"user_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
	"app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
	"labels": [{
		"name": "label name",
		"description": "short label description",
		"category": "category name",
		"start_date": 1478625206,
		"end_date": 1478625206
	}]
}

Response:

{
	"status_code": 201,
	"data": {
		"status": "created",
		"labels": [{
			"id": 100500,
			"name": "label name",
			"description": "short label description",
			"category": "category name",
			"start_date": 1478625206,
			"end_date": 1478625206
		}]
	}
}

Editing labels

To edit a label you need to specify its identifier (id). All the specified fields for the label will be replaced. In case the specified category doesn't exist, it will be created.

If it is necessary to change the dates of an event, you must specify start_date. It is impossible to specify end_date without specifying start_date. If the label is used in relation to a continuous event (start_data and end_date are different timestamps), but in an edited version only the start_date is received, the label becomes a point that characterizes an instant event.

Request:

https://www.devtodev.com/api/v1/labels/edit

POST

{
	"user_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
	"app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
	"id": 100500,
	"name": "label name",
	"description": "short label description",
	"category": "category name",
	"start_date": 1478625206,
	"end_date": 1478625206
}

Response:

{
	"status_code": 200,
	"data": {
		"status": "complete",
		"labels": [{
			"id": 100500,
			"name": "label name",
			"description": "short label description",
			"category": "category name",
			"start_date": 1478625206,
			"end_date": 1478625206
		}]
	}
}

Deleting labels

The request is used to delete one or several labels. To delete a label its identifier is required. The request without specified identifiers is not valid.

Request:

https://www.devtodev.com/api/v1/labels/delete

POST

{
	"user_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
	"app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
	"ids": [100500, 100501]
}

Response:

{
	"status_code": 200,
	"data": {
		"status": "deleted",
		"labels": [{
			"id": 100500,
			"name": "label name",
			"description": "short label description",
			"category": "category name",
			"start_date": 1478625206,
			"end_date": 1478625206
		}]
	}
}

Error handling

In case there is an error in a request, the response is made in the following format:

{
	"status_code": 500,
	"errors": [{
		"code": 3,
		"msg": "Malformed json"
	}]
}

where

status_code (number) - the general status of an error
errors (array) - an array of error descriptions
code (number) - the exact code of an error from the table of errors
msg (string) - a brief description of an error

The list of possible errors is given in a table.

List of possible errors

Limitations

Limitations on the lenght of values

Limitations on the number of actions

Not more than 30 labels in one request on labels creation
Not more than 500 labels to be created in a calendar day for User API token
Not more than 200 labels to be created in a calendar day for an app

Data API

Server API integration manual

This API version is deprecated, please use the latest version.

Request format

The request should be sent to: https://api.devtodev.com/stat/v1/?api=ak-cDNRQl0Lypq4AOUrx8aGGMnmJT1FSebd where:

api - individual devtodev API app key, which can be found on the page of app integration;
v1 - the current version of the API aggregator.

All the transferred data must be in UTF8 encoding.

Contents must be sent as POST in gzip. The archive must contain JSON with one or more events for one or several users.

The size of a package can't exсeed 1 MB before compression. Packages that exсeed this size can't be processed.

If there are several events they must be formed inside a user object by type (name).

{

    "abcd1234abcd" : {              // Main identifier (device or user ID)
        "prev" : "asdf2345234asdf", // Previous main identifier (device or user ID)
                                    // in case it has been changed 
        "userId":"",                // Additional identifier (it is used if there is an identifier
                                    // that is different from the main identifier.
                                    // For example, a cross-platform user identifier)
        "prevUserId":"";            // Previous additional identifier in case it has been changed
        "sc" :[                     // Event name
            {},                     // Parameters of the first event
            {},                     // Parameters of the second event
            …
        ],
        "gs" :[                     // Event name 
            {}                      // Event parameters
        ],
        …
    },
    "1234abc1234" : {               // Unique user ID
        "userID":"",                // Additional identifier (it is used if there is an identifier
                                    // that is different from the main identifier.
        "sc" :[                     // Event name
            {},                     // Parameters of the first event
            {},                     // Parameters of the second event
            …
        ],
        "gs" :[                     // Event name 
            {}                      // Event parameters
        ],
    },
}

Response format

The list of events

Information about a source of user appearance

(traffic source, referral) It is used when it is necessary to track data about a source of user appearance. The event is sent when an app is first launched by a user if a user came from a tracked source. Maximum of the fields from the following accessible data must be transferred.

"rf" : [
    {
        "timestamp" : 1386259227,   // Required field! The date of registration
        "publisher" : "",           // Required field! The source from which a user came - the name of 
                                    // An advertising platform (advertising network)
        "subpublisher" : "",        // In case a platform is an aggregator - the name of a platform 
                                    // From which a user was resold 
        "subad" : "",               // Specific banner from which a user came (for Facebook)
        "subadgroup" : "",          // The group of ads(for Facebook)
        "subcampaign" : "",         // The name of a campaign from which a user came 
        "subplacement" : "",        // Banner placement - its position on a page 
        "subsite" : "",             // Who placed a banner (an app/ a website where a banner is placed)
        "country" : "US",           // Required field! The country of a user (format ISO 3166-1 alpha-2)
        "currencyCode" : "USD",     // The currency of referral's cost (format ISO 4217)
        "cost" : 9.99,              // The cost of a referral in a specified currency 
    }
]

Information about a user

It is not sent in case there is some data missing. The event can't be submitted as a package.

Attention! We strongly recommend that you do not use these properties to transfer and store data that fits the definition of personal data!

"ui": [{
	"timestamp": 1386259227,
	"country": "GB", // The country of a user (format ISO 3166-1 alpha-2)
	"language": "en", // The language of a user (format ISO 639-1 (1998)
	"crossUid": "customuserid", // Custom user ID
	"ip": "127.0.0.1", // IP
	"carrier": "Beeline", // The name of a network operator
	"isRooted": 0, // Rooted (jailbroken) device (1 - rooted)
	"userAgent": "a lot of info" // Browser user-agent
}]

"pl": [{
	"data": {
		"age": 21, //Reserved. User's age in years
		"cheater": true, //Reserved. True, if a user is a cheater 
		//In case you have your own methods to detect
		//cheaters, you can mark such users.
		//Event records made by cheaters will be 
		//ignored when counting statistical metrics. 

		"tester": true, //Reserved. True, if a user is a tester 
		//Attention! This marker cannot be removed
		//through the SDK (It can not be set to false
		//after true).
		//Event records made by testers will be 
		//ignored when counting statistical metrics. 

		"gender": 1, //Reserved. User's sex 0-unknown, 1-male, 2-female 
		"name": "John Doe", //Reserved. User's name
		"email": "john@email.com", //Reserved. User's e-mail 
		"phone": "+15555555555", //Reserved. User's phone number 
		"photo": "http://google.com/pic.png", //Reserved. User's photo

		//Custom characteristics of a user in a key-value format 
		"key1": "stringValue", //String value
		"key2": 1.54, //Number value
		"key3": [1, 2, "something"] //Array
	},
	"timestamp": 12313 //The date of data changes
}]

"pl": [{
	"data": {
		"key1": null, //Remove user's characteristic key1
		"key2": null //Remove user's characteristic key2
	},
	"timestamp": 12313
}]

Information about an app

The recommended interval of sending is not more than once per 24h.

"ai": [{
	"timestamp": 1386259227,
	"sdkVersion": "1.1", // Required. In case of communication via API, 
	// the version of implementation of a communication mechanism
	"appVersion": "1.2", // App version
	"codeVersion": 14.0, // Version of app's code 
	"bundleId": "com.myown.app" // App's bundle 
}]

Information about a device

The recommended interval of sending is not more than once per 24h. Information is the most relevant for mobile devices.

"di" :[
    {
    	  "timestamp" : 1386259227,
        "manufacturer" : "Apple",                   // The manufacturer of a device
        "model" : "iPhone 4,1",                     // uname (iOS), MODEL (Android)
        "screenResolution" : "1024x768",            // The display's resolution of a device
        "screenDpi" : 144,                          // The density of display's points
        "odin" : "klflaiuewfuasydfiasydpf98ay4",    // DeviceUniqueId SHA-1 (Windows Phone),
                                                    // AndroidId SHA-1 (Android)
        "openUdid" : "f;isyofa7w8yp4fapw49",        // OpenUDID ((Android, iOS, Windows phone)
        "idfa" : "AYTSD-ADSYS-LAUSDY-IUAYSD",       // Ad identifier IDFA (iOS)
        "idfv" : "87ASD-9A7SD-AD2G-Q26EO-AS7D",     // Device identifier within the vendor IDFV (iOS)
        "d2dUdid" : "dsufyoa-sfa3wr-ra3rawQ2-AWR3A",// Base64 от DeviceUniqueId (Windows Phone) , 
                                                    // random by http:// www.ietf.org/rfc/rfc4122.txt (Android)
        "imei" : "w87ea6owe7aow78eaow",             // IMEI (Android)
        "androidId" : "o8a7d6oa8s7b6doa87sb6d8bs",  // AndroidID (Android)
        "advertisingId" : "38400000-8cf0-11bd-b23e-10b96e40000d", // Advertising ID (Android, Windows phone 8.1)
        "serialId" : "asd76asd9",                   // Hardware serial number  (Android,Windows phone)
        "deviceVersion": "8.1",                     // OS version
        "deviceModel": "Windows"                    // The name of OS family
    }
]

Session

In case it is possible to fix the length of a session, it is sent during the end of a session or during the next session. If there is no such possibility, send the date of the start of a session, the length of a session must be placed in the middle in case it is known. The absence of a parameter of a session's length makes it impossible to count some metrics.

"gs" : [
    {
        "timestamp" : 1386259227,   // The date of session's start 
        "length" : 34,              // The length of a session in seconds
        "level" : 3,                // Player's level 
        "inProgress" : ["village"]
    },
    …
]

Real Payment

In case you transfer data related to several transactions, group them by item name.

"rp": [
    {
        "name": "inapp_name_1",         // The name of a purchase 
        "entries": [
            {
                "orderId": "124567.7654321",// Transaction identifier (max. 64 symbols)
                "price": 1.99,              // The price of a purchase in a transaction currency
                "currencyCode": "USD",      // Transaction currency(ISO 4217 format)
                "timestamp": 1386259227,    // The date of a transaction
                "level": 3,                 // Player's level
                "inProgress": ["village"]   // Location (game level) in which an action has been performed
            },{     //If there is one more identical purchase for a report period
                "orderId": "1224567.7634327",
                "price": 1.99,
                "currencyCode": "USD",
                "timestamp": 1386259227,
                "level": 3,
                "inProgress": ["village"]
            }
        ]
    },{     //If there are other purchases for a report period 
        "name": "inapp_name_2",
        "entries": [
            {
                "orderId": "1234567.7654321",
                "price": 9.99,
                "currencyCode": "USD",
                "timestamp": 1386259227,
                "level": 3,
                "inProgress": ["town"]
            }
        ]
    }
]

Onboarding (tutorial) steps

The event allows to learn how a user goes through a tutorial. The event is created after every completed step.

If a tutorial that hasn't been completed is programmed to reset to the beginning, the repeated reference of identical steps will be counted and influence the statistical metrics.

"tr" : [
    {
        "step" : 1,                // the number of a tutorial step that has been completed 
        "timestamp" : 1386259227,  // date
        "level" : 3,               // player's level
        "inProgress" : ["village"],// location (game level) in which an action has been performed
        …
    }
]

Use the following constants for basic actions:

"step" : -1  // The beginning of a tutorial(before completing the first step)
"step" : 0   // The tutorial is skipped 
"step" : -2  // The tutorial is completed (instead of the last step's number)

In all other cases use the number of steps above 0.

Custom event

If it is necessary to count events that are absent from the main types of events, use user events. An event must have a unique name and can include up to 20 parameters. You can use up to 300 unique names.

We strongly recommend that you do not use custom event properties to transfer and store data that fits the definition of personal data!

"ce" : [
    {
        "name" : "house_purchase",          // The name of an event (max. 72 symbols)
        "entries" : [
            {
                "t1" : 1231872631,          // The date of an event
                "level" : 3,                // Player's level
                "inProgress" : ["village"], // Location (game level) in which an action has been performed
                "p" : {
                    "t1" : {
                        // up to 10 parameters grouped by data types
                        "double" : {        // Parameters with values - in numbers
                            "key1" : 1,     // The name of a parameter as a key(max. 32 symbols) and
                                            // the value of a parameter
                            "key2" : 2.123,
                            …
                        },
                        "string" : {        // Parameters with values - in strings
                            "key3" : "a",   //  The name of a parameter as a key(max. 32 symbols) and
                                            // the value of a parameter (max. 255 symbols)
                            "key4" : "abc",
                            …
                        }
                    }                       
                }
            },
            {                               // If there are several events with the same name 
            "t1" : 1231872638,
            "level" : 3,                    
            "inProgress" : ["village"],
            "p" : {
                "t1" : {
                    "double" : {
                        "key1" : 1,
                        "key2" : 2.123,
                        …
                    },
                    "string" : {
                        "key3" : "a", 
                        "key4" : "abc",
                        …
                    }
                }                       
            }
        }
    },
    {                                       // If one user had several events with different names for
                                            // a reporting period, continue 
        …
    }
]

New level

This event is for games only.

Allows you to analyze players' distribution by game levels. The event is created when a player moves to the next level. In order to track the average state of game currency accounts, the amount of spendings and earnings of a currency, the amount of a game currency bought while completing a level, you can also send this data in this event.

"lu" : [
    {
        "level" : 10,              // Required. The level that a player got 
        "timestamp" : 1386259227,  // Required. The date of moving to the next level 
        "inProgress" : ["village"],// Location (game level)in which an action has been performed
        "balance" : {              // Optional. The balances of a game currency at the end of a level 
            "money1" : 123,        // The name of a game currency as a key and its amount 
            "money2" : 11,
            …
        },
        "spent" : {                // Optional. The amount of a currency spent on a level
            "money1" : 12,         // The name of a game currency as a key and its amount 
            "money2" : 2,
            "wood" : 12,
            …
        },
        "earned" : {               // Optional. The in-game currency that was earned on a level
            "money1" : 8,    
            "money2" : 2,
            "stone" : 1,
            …
        },
        "bought" : {                // Optional. The in-game currency that was bought on a level 
            "money1" : 10,
            "money2" : 2,
            …
        }
    },
    …
]

Virtual Currency Payment

This event is for games only.

It is used to track the ways in which an in-game currency is spent and the popularity of in-game items.

"ip" :  [
    {
        "purchaseType" : "Weapon",  // The group of an item (max. 96 symbols)
        "purchaseId" : "Dagger",    // The unique name or ID of an item (max. 32 symbols)
        "purchaseAmount" : 1,       // The amount of items bought
        "purchasePrice" : 1.0,      // The price of an item (the overall price of a purchase if there 
                                    // are several identical items are bought) in an in-game currency 
        "purchasePriceCurrency" : "Coins",  // The name of an in-game currency that was used to buy
                                            // an item (max. 24 symbols)
        "timestamp" : 1231872631,   // The date of a purchase
        "level" : 3,                // Player's level
        "inProgress" : ["village"]  // Location (game level) in which an action has been performed
    },
    …
]

In case one item is sold in several currencies, a purchase is divided into several events, the amount of which corresponds to the number of currencies. Wherein the number of items is specified only in one event.

"ip" :  [
    {
        "purchaseType" : "Weapon",  // The group of an item (max. 96 symbols)
        "purchaseId" : "Dagger",    // The unique name or ID of an item (max. 32 symbols)
        "purchaseAmount" : 1,       // The amount of items bought
        "purchasePrice" : 1.0,      // The price of an item (the overall price of a purchase if there 
                                    // are several identical items are bought) in an in-game currency 
        "purchasePriceCurrency" : "Coins",  // The name of an in-game currency that was used to buy
                                            // an item (max. 24 symbols)
        "timestamp" : 1231872631,   // The date of a purchase
        "level" : 3,                // Player's level
        "inProgress" : ["village"]  // Location (game level) in which an action has been performed
    },
    {
        "purchaseType" : "Weapon", 
        "purchaseId" : "Dagger",   
        "purchaseAmount" : 0,      
        "purchasePrice" : 2.0,     
        "purchasePriceCurrency" : "Gold", 
        "timestamp" : 1231872631,
        "level" : 3,               
        "inProgress" : ["village"]
    },
    …
]

Progression event

This event is for games only.

First of all, the event is used for games with short locations (game levels) that are completed during one game session. The event allows to gather data about the success in location completion and receive statistics by parameters that are changeable during location completion.

"pe" : [
    {
        "id" : "location2",         // The name of a location
        "level" : 3,                // Player's level at the moment of location completion 
        "params" : {                // Event parameters
            "source" : "location1", // The name of the previous location of a player 
            "difficulty" : 1,       // Optional. The level of difficulty of location completion 
            "success" : true,       // Success in location completion 
            "duration" : 180        // Optional. Time in seconds of location completion
        },
        "spent" : {                 // Optional. Resources spent during location completion
            "money1" : 12,          // The record of a resource in the format of 
                                    // resource's name - the amount of a resource
            "money2" : 2, 
            "wood" : 12
        }, 
         "earned" : {               // Optional. Resources that are received during location completion 
             "money1" : 8, 
             "money2" : 2, 
             "stone" : 1
        },
        "timestamp" : 1234567890    // The time of exit from a location
    }
]

Ad impression

The event is used for individual tracking of ad revenue.

Do not use 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.

Example:

"adrv": [{
	"ad_network": "TestAdNetwork", //Name of the ad network responsible for the impression (from 1 to 100 symbols)
	"revenue": 0.3434, //Reward for banner display in USD
	"ad_unit": "TestAdUnit", //Banner name (from 1 to 100 symbols,optional)
	"placement": "TestPlacement" //Banner placement (from 1 to 100 symbols, optional)
}]

Allows you to track existing connections to social networks.

"sc" : [
    {
        "socialNetwork" : "FB",   // The name of a social network. The value from the list
                                  // of constants for popular networks or your own string name
        "timestamp" : 1386259227, // The date of connection
        "level" : 3,              // Player's level
        "inProgress" : ["village"]// Location (game level) in which an action has been performed
    },
    ...
]

Constants that are supported by the system:

Allows you to track publications in social networks. It also allows you to analyze viral channels to optimize marketing efficiency.

It is sent after a publication has been approved by a social network.

"sp" : [
    {
        "socialNetwork" : "FB",   // The name of a social network. The value from the list of 
                                  // constants for popular networks or your own string name
        "postReason" : "levelup", // The reason of publication (max. 32 symbols). We recommend you
                                  // to group reasons instead of sending such names as "Level 99 reached".
        "timestamp" : 1386259227, // The date of publication 
        "level" : 3,              // Player's level 
        "inProgress" : ["village"]// Location (game level)in which an action has been performed
    },
    ...
]

We recommend to specify actions that encourage to make a publication as a reason:

Clearing user data

The "Wipe" function can help when you test your app and/or when you need to clear user data as a part of the gameplay.

By default, when you send an event without any parameters, a user-specified will be "forgotten". We will keep user data in the database, but you won’t be able to find them by their main identifier. Respectively, the following event batch with the same identifier will result in creating a new user. Also, in certain circumstances, you can’t just ‘forget’ some of the users. Therefore, we have provided several flags that might be helpful.

"wipe" : [
    {
        "saveRegistration": true,     // Optional. A new user will inherit registration dates after
                                      // an old user; a new user will not be registered by devtodev as
                                      // the new one. It might be useful when you test your app.
        "savePayingStatus": true,     // Optional. Old user payment data will be copied into a new
                                      // user card (number of payments, amounts and payment dates).
        "saveCheaterTester": true,    // Optional. cheater and tester labels will be copied into
                                      // a new user card. It might be useful when you test your app.
        "saveCustomProperties": true, // Optional. Old user custom fields and values from those fields
                                      // will be copied into the new user card.
        "timestamp" : 1234567890      // Optional. The time of exit from a location
    }
]

Limiting the processing of user data. The right to erasure.

This event is implemented in accordance with the GDPR requirements.

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 "ts" event with the parameter "isTrackingAllowed": 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 listed as an impersonal unit in previously aggregated metrics.

When sending a true value, the permission to block data collection is removed.

{
	"JohnDoe": {
		"prev": "LittleJohn",
		"ts" : [{ 
        	"isTrackingAllowed": false,
        	"timestamp" : 1386259227
		}]
	}
}

An example of a package

'POST' https://api.devtodev.com/stat/v1/?api=ak-npADyEmjxc0usQR52k6it38zUPSloGT7 with gzipped body:

{
	"JohnDoe": {
		"prev": "LittleJohn",
		"tr": [{
			"step": 1,
			"timestamp": 1386259227,
			"level": 1,
			"inProgress": ["village"]
		}, {
			"step": 2,
			"timestamp": 1386259236,
			"level": 1,
			"inProgress": ["village"]
		}, {
			"step": 3,
			"timestamp": 1386259288,
			"level": 1,
			"inProgress": ["town"]
		}],
		"gs": [{
			"timestamp": 1386259227,
			"length": 1250,
			"level": 3
		}],
		"pl": [{
			"data": {
				"gender": 1
			}
		}],
		"lu": [{
			"level": 4,
			"inProgress": ["village"],
			"timestamp": 1442392006,
			"balance": {
				"Coins": 1234,
				"Gold": 11
			}
		}],
		"ce": [{
			"name": "Round_finished",
			"entries": [{
				"t1": 1442392451,
				"level": 4,
				"inProgress": ["village"],
				"p": {
					"t1": {
						"double": {
							"Round_time": 83,
							"Score": 2.123
						},
						"string": {
							"Result": "Victory",
							"Type": "Flawless"
						}
					}
				}
			}, {
				"t1": 1442393455,
				"level": 4,
				"inProgress": ["town"],
				"p": {
					"t1": {
						"double": {
							"Round time": 102,
							"Score": 1.5
						},
						"string": {
							"Result": "Defeat",
							"Type": "Shameful"
						}
					}
				}
			}]
		}],
		"pe": [{
			"id": "town",
			"level": 3,
			"params": {
				"source": "vilage",
				"difficulty": 2,
				"success": true,
				"duration": 180
			},
			"spent": {
				"Turns": 54,
				"Boost Bomb": 1,
				"Extra 5 Turns": 1
			},
			"earned": {
				"Stars": 3,
				"Score": 1200,
				"Coins": 5
			},
			"timestamp": 1234567890
		}],
		"ip": [{
			"purchaseType": "Weapon",
			"purchaseId": "Dagger",
			"purchaseAmount": 1,
			"purchasePrice": 30.0,
			"purchasePriceCurrency": "Coins",
			"timestamp": 1442393479,
			"level": 4,
			"inProgress": ["village"]
		}],
		"rp": [{
			"name": "Currency pack 1",
			"entries": [{
				"orderId": "1234567.7654321",
				"inProgress": ["village"],
				"level": 4,
				"price": 1.99,
				"currencyCode": "USD",
				"timestamp": 1442393460
			}]
		}],
		"sp": [{
			"socialNetwork": "FB",
			"postReason": "New level reached",
			"level": 4,
			"inProgress": ["village"],
			"timestamp": 1442392006

		}]
	}
}

Utility for testing

A utility for sending packets

https://www.devtodev.com/upload/files/devtodevapitester.jar

An example of sending to PHP

An example of the implementation of a request to PHP with the use of Curl. The sending of real payment.

$url = 'https://api.devtodev.com/stat/v1/?api='.$api;
$params = [
        $uid=>[
            'rp' =>[
                [
                    'name' => $name,
                    'entries' =>[
                        [
                            'orderId' => $transactionId,
                            'price' => 100,
                            'currencyCode' => 'USD',
                            'timestamp' => time(),
                            'level'=> 5,
                            'inProgress'=> ['village']
                        ]
                    ]
                ]
            ]
        ]
];

$curlHandle = curl_init($url);
curl_setopt($curlHandle, CURLOPT_HTTPHEADER, array('Content-Type: text/plain;charset=UTF-8'));
curl_setopt($curlHandle, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curlHandle, CURLOPT_POST, TRUE);
curl_setopt($curlHandle, CURLOPT_USERAGENT, "Mozilla/4.0 (compatible;)");
curl_setopt($curlHandle, CURLOPT_POSTFIELDS, gzencode(json_encode($params)));
curl_setopt($curlHandle, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($curlHandle, CURLOPT_ENCODING, 'gzip');
$response = curl_exec($curlHandle);

Raw Export

devtodev RAW export API

To use RAW data export API you need to have an individual User API token, which can be found in the settings of space.

Please attend, if you use several spaces, in every space user has an individual User API token.

The pattern of communication with devtodev RAW data export API

The process of getting data consists of three steps:

job assignment
getting the status of performance
getting the report file by link

Let’s have a look at these steps.

Job assignment

This step is the most important, and its description is the longest one.

The request of assignment should be sent to:

https://devtodev.com/api/v1/rawexport/setjob?user_token=USER_API_TOKEN

Where

user_token - individual User API token of the user. It could be sent with both GET and POST methods.
v1 - current version of API

The request content is sent with POST method in JSON format.

The body of the request contains the following properties:

List of available events and their identificators

Custom events filtering

If you’re interested in the export of custom events according to some specific conditions, you should set the objects with the following properties in the array of the event list:

User card filtering

Caution! Filtering uses the property values of the user card at the time of the data export request.

The names of the properties are the same as the column names in the "users" table of the project, which you can find in the SQL report.

The table shows the fields by which filtering is possible:

Property

Type

Description

List of comparison operators which can be applied in filter

The filter can be described with an object, where the following comparison operators can be the properties:

The empty object describes the filter which selects all the events where the parameter value is not null or empty string.

Examples

https://devtodev.com/api/v1/rawexport/setjob

POST

{
	"user_token": "USER_API_TOKEN", // It is obligatory, if it’s not sent with GET.
	"app_id": "af0606ed-bbdc-065a-952c-0d92561f107c",  // Obligatory. Application identificator.
	"start_date": 1464709200,  // Obligatory. Unix time of export start date.
	"end_date": 1464739200,  // Obligatory. Unix time of export end date.
	"events": [ //Not obligatory. List of events to export.
		"tr", // Export all  Tutorial step events
		"customEvent1Name",  // Export all customEvent1Name events
        //{"name": "customEvent1Name"} - alternative way with the same result
		{
			"name": "customEvent2Name",
			"filters": {  // Object with filter conditions
				"paramName1": {
					// 5<paramName1<=10 and paramName1!=8
					"lte": 10,
					"gt": 5,
					"neq": 8
				},
				"paramName2": {
					//Parameter paramName2 is equal to the one of elements.
					"eq": ["a","b","c"] 
				},
				"paramName3": {} // paramName3 is not empty.
			}
		}
	],
	"user_card_filter": { //user card properties filter object
		"paramName1": { //name of preset or custom user card parameter
			"lte": 10,
			"gt": 5,
			"neq": 8
		},
		"paramName2": { //name of preset or custom user card parameter
			"eq": ["a", "b", "c"]
		}
	}
}

Or another way with event group identificator.

{
	"user_token": "USER_API_TOKEN",
	"app_id": "af0606ed-bbdc-065a-952c-0d92561f107c",
	"start_date": 1464709200,
	"end_date": 1464739200,
	"events": ["@custom_events"] //Export all custom events
}

The format of the response to the job assignment

The response in case of successful start execution:

{
	"status_code": 200,
	"data": "JOB_ID"
}

Where

status_code - is the HTTP status code
data - an identificator which is assigned to the job

If you get this response, you can go to the next stage - request of job status (else go to Error handling).

Getting the status of performance

With the job identificator, you can request its current status, using the following request:

https://devtodev.com/api/v1/rawexport/getprogress?user_token=USER_API_TOKEN

The body of request can contain the following properties:

The format of the response to the request of status

The response to the request of status can be one of the following:

The job is in the queue
The job is in progress
The job is done
Error of job performance

Let’s explore every variant.

The job is in the queue

{  
	"status_code":202,
	"data":{  
		"status":"pending",
		"percent_complete":0
	}
}

The job is in progress

{  
	"status_code":200,
	"data":{  
		"status":"running",
		"percent_complete":10
	}
}

The job is done

{  
	"status_code":201,
	"data":{  
		"status":"complete",
		"percent_complete":100,
		"result":{  
			"msg":"Report file is ready",
			"format":"csv",  // Format of report files in archive
			"url":"https://devtodev.com/api/v1/rawexport/download/?job_id=JOB_ID&user_token=USER_API_TOKEN",
			"ttl": 100500, // Report lifetime from the end of the performance to the removal
			"expire":123434534534  // Date when the report will be removed (in UNIX-time format)
		}
	}
}

To get the report use the link in the URL property.

The report file is zip-archive with files in .CSV format. Every file contains data about one event and/or alias (which was set in the filter in job assignment).

If there are no events according to the query conditions, the response will be the following:

{  
	"status_code":200,
	"data":{  
		"status":"complete",
		"percent_complete":100,
		"result":{  
			"msg":"Unfortunately the result of your request is empty. Please try to change the report conditions."
		}
	}
}

Error handling

{
    "status_code": 400,
    "errors": [{
        "code": 3,
        "msg": "Error description"
    }]
}

where

status_code (number) - a general status of an error
errors (array) - an array of error descriptions
code (number) - the exact code of an error from the table of errors
msg (string) - a brief description of an error

The list of possible errors is given in a table.

Limitations

There are the following limitations to devtodev RAW data export API:

List of available events

Below you can find the description of each table for events available for export.

Users

This file is always attached to the exported file. The table contains a list of users who performed the exported events. It also contains their characteristics available at the time of the export.

Column name

Description

All subscription events.

Tutor

Tutorial steps events.

UDIDs

This file contains information about changes of user and device identifiers during the selected export period.

UserUpdate

This file contains data on user characteristics and devices updates for the selected export period.

AdImpression

This file contains app’s ad impression events. Data from ad networks or the Ad Impression event.

CustomEvent.{EventName}

This file contains custom events with {EventName} name.

Labels API

Obtaining the User API token

In order to be able to use Labels API you must have an individual User API token, which can be found in space settings in devtodev system.

Pay your attention that if you use several spaces, each of them will have an individual User API token.

Obtaining the list of categories

The result of the request is the obtaining of the list of all existing labels categories for the app.

Request:

https://www.devtodev.com/api/v1/labels/categories/get

POST

{
	"user_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", // devtodev user API token
	"app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"  // devtodev App ID
}

Response:

{
	"status_code": 200,
	"data": {
		"status": "complete",
		"categories": [
			"category name",
			"category name 2"
		]
	}
}

Removing categories

Request:

https://www.devtodev.com/api/v1/labels/categories/delete

POST

{
	"user_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
	"app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
	"category": "category to be removed",
	"move_labels_to_category": "category to which the labels will be moved"
}

Response:

{
	"status_code": 200,
	"data": {
		"status": "deleted",
		"category": "category to be removed"
	}
}

Obtaining the list of labels

The result of the request is the obtaining of the list of labels that are presented as objects.

You can use filters to get some specific labels you need. In case no filter is specified, you will receive the whole list of labels. It is possible to use any combination of fields in a filter.

Request:

https://www.devtodev.com/api/v1/labels/get

POST

{
	"user_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
	"app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
	"filters": {
		"id": {
			"in": [100500, 100501]
		},
		"category": {
			"in": ["category name", "category name 2"]
		},
		"start_date": {
			"gte": 1478625206
		},
		"end_date": {
			"lte": 1478625206
		}
	}
}

Response:

{
	"status_code": 200,
	"data": {
		"status": "complete",
		"labels": [{
			"id": 100500,
			"name": "label name",
			"description": "short label description",
			"category": "category name",
			"start_date": 1478625206,
			"end_date": 1478625206
		}]
	}
}

List of comparison operators that can be applied in a filter

The filter can be described with an object, where the following comparison operators can be the properties:

The empty object describes the filter that selects all the events in which the parameter value is not null or empty string.

Adding labels

In case the specified category doesn't exist, it will be created. If string values of fields exceed the maximum, they will be cut off.

If you need to specify an event without time length, start_date must be equal to end_date or end_date must not be specified.

Request:

https://www.devtodev.com/api/v1/labels/add

POST

{
	"user_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
	"app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
	"labels": [{
		"name": "label name",
		"description": "short label description",
		"category": "category name",
		"start_date": 1478625206,
		"end_date": 1478625206
	}]
}

Response:

{
	"status_code": 201,
	"data": {
		"status": "created",
		"labels": [{
			"id": 100500,
			"name": "label name",
			"description": "short label description",
			"category": "category name",
			"start_date": 1478625206,
			"end_date": 1478625206
		}]
	}
}

Editing labels

To edit a label you need to specify its identifier (id). All the specified fields for the label will be replaced. In case the specified category doesn't exist, it will be created.

Request:

https://www.devtodev.com/api/v1/labels/edit

POST

{
	"user_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
	"app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
	"id": 100500,
	"name": "label name",
	"description": "short label description",
	"category": "category name",
	"start_date": 1478625206,
	"end_date": 1478625206
}

Response:

{
	"status_code": 200,
	"data": {
		"status": "complete",
		"labels": [{
			"id": 100500,
			"name": "label name",
			"description": "short label description",
			"category": "category name",
			"start_date": 1478625206,
			"end_date": 1478625206
		}]
	}
}

Deleting labels

The request is used to delete one or several labels. To delete a label its identifier is required. The request without specified identifiers is not valid.

Request:

https://www.devtodev.com/api/v1/labels/delete

POST

{
	"user_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
	"app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
	"ids": [100500, 100501]
}

Response:

{
	"status_code": 200,
	"data": {
		"status": "deleted",
		"labels": [{
			"id": 100500,
			"name": "label name",
			"description": "short label description",
			"category": "category name",
			"start_date": 1478625206,
			"end_date": 1478625206
		}]
	}
}

Error handling

In case there is an error in a request, the response is made in the following format:

{
	"status_code": 500,
	"errors": [{
		"code": 3,
		"msg": "Malformed json"
	}]
}

where

status_code (number) - the general status of an error
errors (array) - an array of error descriptions
code (number) - the exact code of an error from the table of errors
msg (string) - a brief description of an error

The list of possible errors is given in a table.

List of possible errors

Limitations

Limitations on the lenght of values

Limitations on the number of actions

Not more than 30 labels in one request on labels creation
Not more than 500 labels to be created in a calendar day for User API token
Not more than 200 labels to be created in a calendar day for an app

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

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

Example POST Data:

{  
    "reports" : [
        {
            "deviceId" : "deviceId",
            "previousDeviceId" : "samplePreviousMainId",
            "userId" : "sampleUserId",
            "previousUserId" : "samplePreviousUserId",
            "devtodevId": 6123517,
            "packages" : [
                {
                    "language" : "en",
                    "country": "US",
                    "ip": "154.12.121.11",
                    "appVersion" : "1.0",
                    "appBuildVersion": "30",
                    "sdkVersion" : "2.0",
                    "sdkCodeVersion" : 20,
                    "bundle" : "com.example.application",
                    "installationSource" : "",
                    "engine": "Unity",
                    "events" : [
                        ... //see Events section
                    ]
                },
                {
                    ...
                }
            ]  
        },
        ...
    ]
}

The reports object contains:

Each packet consists of the following fields:

Response

The server responds with code 200 if everything is OK.

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.

Example

{
	"code": "di",
	"timestamp": 1694783505123,
	"osVersion": "10.2.2",
	"os": "iOS",
	"displayPpi": 401,
	"displayResolution": "1920x1080",
	"dispalyDiagonal": "5.5",
	"manufacturer": "Apple",
	"model": "iPhone8,2",
	"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_2) AppleWebKit/602.3.12 (KHTML, like Gecko) Version/10.0.2 Safari/602.3.12",
	"timeZoneOffset": 7200,
	"idfv": "30FE1CE1-1125-4657-97B0-638744C3C6D1",
	"idfa": "0A60DCF2-3186-4801-9192-D8CFA995DD6D"
}

Session Start

Sends information about the start of a new session.

Example

{
    "code": "ss",
    "timestamp": 1694783505123,
    "level": 1
}

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.

Example

{
    "code": "ue",
    "timestamp": 1694783735122,
    "level": 1,
    "length": 230,
    "sessionId": 1694783505123
}

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.

Example

{
    "code": "ts",
    "trackingAllowed": false,
    "timestamp": 1694783565763
}

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.

Example

{
    "code": "al",
    "timestamp": 1694783607178
}

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!

Predefined user properties (in addition to 30 custom user properties).

Example

{
	"code": "pl",
	"timestamp": 1694783511089,
	"sessionId": 1694783505123,
	"level": 2,
	"parameters": {
		"name": "John Doe",
		"cheater": false,
		"age": 21
	}
}

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!

Example

{
	"code": "ce",
	"timestamp": 1694783521034,
	"sessionId": 1694783505123,
	"level": 2,
	"name": "eventName",
	"parameters": {
		"intParameter": 134,
		"stringParameter": "hello",  //255 symbols max
		"doubleParameter": 12.98
	}
}

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.

Example

{
	"code": "rp",
	"timestamp": 1694783605101,
	"sessionId": 1694783505123,
	"level": 2,
	"productId": "starter_pack",
	"orderId": "GPA.100054271428",
	"price": 19.99,
	"currencyCode": "USD"
}

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.

Example

{
	"code": "tr",
	"timestamp": 1694783715371,
	"sessionId": 1694783505123,
	"level": 2,
	"step": -1
}

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.

Example

{
	"code": "vp",
	"timestamp": 1694783555833,
	"sessionId": 1694783505123,
	"level": 2,
	"purchaseId": "house_327",
	"purchaseAmount": 2,
	"purchasePrice": {
		"coins": 500,
		"wood": 2
	},
	"purchaseType": "buildings"
}

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.

{
	"code": "ca",
	"timestamp": 1694783625364,
	"sessionId": 1694783505123,
	"level": 2,
	"bought": {
		"sourceA": {
			"resource1": 1231,
			"resource2": 1231
		},
		"sourceB": {
			"resource1": 12,
			"resource2": 31
		},
		"sourceC": {
			"resource2": 40,
			"resource1": 10
		}
	},
	"earned": {
		"sourceA": {
			"resource1": 1231,
			"resource2": 1231
		},
		"sourceD": {
			"resource1": 1231,
			"resource2": 1231
		}
	}
}

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.

Example

{
	"code": "cb",
	"timestamp": 1694783615284,
	"sessionId": 1694783505123,
	"level": 2,
	"balance": {
		"money1": 123,
		"money2": 11
	}
}

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.

Example

{
	"code": "lu",
	"timestamp": 1694783675815,
	"sessionId": 1694783505123,
	"level": 2,
	"balance": {
		"money1": 123,
		"money2": 11
	},
	"spent": {
		"money1": 12,
		"money2": 2,
		"wood": 12
	},
	"earned": {
		"crystals": 5
	},
	"bought": {
		"wood": 200
	}
}

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.

parameters object:

Example

{
	"code": "pe",
	"timestamp": 1694783885625,
	"sessionId": 1694783505123,
	"level": 2,
	"name": "MyAwesomeLocation",
	"parameters": {
		"source": "location1",
		"difficulty": 1,
		"success": true,
		"duration": 180
	},
	"spent": {
		"money1": 12,
		"money2": 2,
		"wood": 12
	},
	"earned": {
		"money1": 8,
		"money2": 2,
		"stone": 1
	}
}

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

{
	"code": "rp",
	"timestamp": 1694783895114,
	"sessionId": 1694783505123,
	"level": 2,
	"productId": "starter_pack",
	"orderId": "GPA.100054271428",
	"price": 19.99,
	"currencyCode": "USD",
	"inProgress": ["MyAwesomeLocation"]
}

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.

Example

{
	"code": "rf",
	"timestamp": 1694783915948,
	"sessionId": 1694783505123,
	"source": "google",
	"campaign": "christmas",
	"content": "sale for ducks",
	"medium": "traff",
	"term": "a,b,c,d,e"
}

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.

Example

{
	"code": "adrv",
	"timestamp": 1694783775187,
	"sessionId": 1694783505123,
	"source": "IronSource",
	"ad_network": "Facebook",
	"placement": "End of the round",
	"ad_unit": "TestAdUnit",
	"revenue": 0.3434
}

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.

Example

{
	"code": "sc",
	"timestamp": 1694783815155,
	"sessionId": 1694783505123,
	"level": 2,
	"socialNetwork": "fb"
}

Preset social network codes

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.

Example

{
	"code": "sp",
	"timestamp": 1694783905478,
	"sessionId": 1694783505123,
	"level": 2,
	"socialNetwork": "fb",
	"postReason": "quest_completed"
}

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.

{
	"reports": [{
		"deviceId": "0A60DCF2-3186-4801-9192-D8CFA995DD6D",
		"userId": "u_100500",
		"packages": [{
			"language": "en",
			"country": "US",
			"appVersion": "1.0",
			"events": [{
					"code": "di",
					"osVersion": "10.2.2",
					"os": "iOS",
					"displayPpi": 401,
					"displayResolution": "1920x1080",
					"dispalyDiagonal": "5.5",
					"manufacturer": "Apple",
					"model": "iPhone8,2",
					"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_2) AppleWebKit/602.3.12 (KHTML, like Gecko) Version/10.0.2 Safari/602.3.12",
					"timeZoneOffset": 7200,
					"idfv": "30FE1CE1-1125-4657-97B0-638744C3C6D1",
					"idfa": "0A60DCF2-3186-4801-9192-D8CFA995DD6D",
					"timestamp": 1694783505122
				}, {
					"code": "ss",
					"timestamp": 1694783505123,
					"level": 1
				}, {
					"code": "pl",
					"timestamp": 1694783511089,
					"sessionId": 1694783505123,
					"level": 1,
					"parameters": {
						"name": "John Doe",
						"cheater": false,
						"age": 21
					}
				}, {
					"code": "tr",
					"timestamp": 1694783715371,
					"sessionId": 1694783505123,
					"level": 1,
					"step": -1
				}, {
					"code": "tr",
					"timestamp": 1694783725344,
					"sessionId": 1694783505123,
					"level": 1,
					"step": 1
				}, {
					"code": "lu",
					"timestamp": 1694783736345,
					"sessionId": 1694783505123,
					"level": 2,
					"balance": {
						"money1": 123,
						"money2": 11
					}
				}, {
					"code": "tr",
					"timestamp": 1694783741456,
					"sessionId": 1694783505123,
					"level": 2,
					"step": 2
				}, {
					"code": "tr",
					"timestamp": 1694783752425,
					"sessionId": 1694783505123,
					"level": 2,
					"step": -2
				}, {
					"code": "ce",
					"timestamp": 1694783773675,
					"sessionId": 1694783505123,
					"level": 2,
					"name": "eventName",
					"parameters": {
						"intParameter": 134,
						"stringParameter": "hello",
						"doubleParameter": 12.98
					}
				},
				{
					"code": "rp",
					"timestamp": 1694783798278,
					"sessionId": 1694783505123,
					"level": 2,
					"productId": "com.example.application.starterpack",
					"orderId": "280001601071201",
					"price": 19.99,
					"currencyCode": "USD"

				}, {
					"code": "ue",
					"timestamp": 1694783898278,
					"level": 2,
					"length": 393,
					"sessionId": 1694783505123
				}
			]
		}]
	}]
}