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.
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.
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:
Property
Type
Description
user_token
string
Individual user API token. It can be found on the space settings page. It is possible to send it with both POST and GET methods.
app_id
string
Application identificator. It can be found in the application settings in the Integration section.
start_date
number
Start date of the request interval. Attention! Data is sent in UNIX-time format. Don’t forget to add/subtract the number of correction seconds to get data according to your timezone.
end_date
number
End date of the request interval. Data is sent in UNIX-time format.
events
array
List of events to export. The element of the array can be in the following formats:
  • Event identificator (string). Have a look at the list of available events and their identificators.
  • Event group identificator (string). Have a look at the list of available events and their identificators.
  • Object with the name of custom event where it is possible to assign alias and to add filters. Have a look at Custom events filtering.
The empty array means the export of all the available events.

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 @).
Event ID
Event name
lu
Level up
rp
Real Payment
tr
Tutorial step
ip
Ingame purchase
sc
Social network connect
sp
Social network post
gs
Sessions
uu
User update
ud
UDIDs
pe
Progression event
rg
Registration (install date)
sbs
Subscription (all actions with subscriptions)
adrv
Ad impressions. Data from ad networks or the Ad Impression event.
@basic_events
All events below
sbs_payments
Subscription (payments only)
Any custom event name
Custom event
@custom_events
All custom events

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:
Property
Type
Description
name
string
Name of custom event
filters
object
Object with the filtering conditions.
Names of the object properties correspond with the name of custom event parameters. It is possible to apply filters to each of them.
Example
"filters":{ "paramName1":{ "gt": 5 // Events where paramName1>5. Have a look at List of comparison operators. } }
alias
string
Name of file in the report where to put the event with filter. The default name is set in the “name” property. Attention! If you export several equal events with different filters, the “alias” property is obligatory.

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:
API operator
Math operator
Description
gt
>
Greater than
lt
<
Less than
eq
=
Equal
gte
>=
Greater than or equal
lte
<=
Less than or equal
neq
!=
Not equal
eq
In the list
neq
Not in the list
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.
}
}
]
}
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:
Property
Type
Description
user_token
string
Individual user API token. It can be found on the space settings page. It is possible to send it with both POST and GET methods.
job_id
string
Job identificator which can be got from the response of job assignment.

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.
Status code
Code
Value of "msg" field
Error description
400
2
Request body is empty
Empty body of the request. There is no POST data in the request.
400
3
Malformed json
JSON error in the body of the equest. Fix the formatting error.
401
11
Authorization error. Wrong user token %user_token value%
Authorization error. The set token is wrong. “User_token” field. User API token.
401
12
Authorization error.
User_token is not set.
Authorization error. “User_token” field is absent. User API token should be set either as a parameter in GET string of request or in POST body of request.
400
6
Invalid app id %app id value%
The requested project can not be found. Unknown application. This error can raise when a user makes a mistake with the app id or when the application with this ID was removed.
403
13
Access denied. You have no access to the app %app id value%
The error of access. User has no access to this application.
403
14
Access denied. You have no access to the report file %file id value%
The error of access. User has no access to this file. This error can raise if you have no access to the application used in the previously created request.
403
15
Access denied. You have no access to API.
The error of access. No access to User API token. This error can happen when the access rights were changed (in consequence of changing the user role or tariff plan)
403
16
Access denied. You have no access to RAW data export API.
The error of access. This error can raise when you have no rights to RAW data export API for your user role or tariff plan.
400
4
Field not found: %field_name%
An obligatory field can not be found. You need to complement the request with this field.
403
17
Quota exceeded. %% concurrent requests per user has been reached.
The limit of simultaneous jobs per user is exceeded. Wait until one of the jobs will be finished and repeat the request.
429
18
Too many requests. %% requests per day per user quota has been exhausted.
The daily limit of the user is exceeded. You can send the next request at the beginning of the next day.
429
19
Too many requests. %% requests per day per space quota has been exhausted.
The daily space limit is exceeded. You can send the next request at the beginning of the next day.
429
20
Too many requests. One request per %% seconds per user quota has been exhausted.
The limit of request frequency is exceeded. You have to wait for the time set in the error text.
404
21
File not found. The requested report file had been expired and was deleted.
The requested file can not be found. This can be when the file was removed due to the end of its lifetime. You have to repeat the job assignment and wait for the new file.
400
10
Incorrect report time frame interval:
start_date and end_date can not be earlier than 90 days from now.
Incorrect report time frame interval.
Both start and end date should be later than 90 days from now.
400
22
The job_id you requested is not found.
The job_id you requested is not found or the job was done and the report lifetime is exceeded.
400
5
Field %field_name% has type %received_type% but %expected_type% expected
The data type is not equal to the expected data type. Check the correspondence of the request with the format set in the documentation. Possible data types: boolean, integer, float, number (integer+float), string.
400
7
Unknown format: %format%
You have set the unknown export file format.

Limitations

There are the following limitations to devtodev RAW data export API:
Limitations
Value
Max number of job assignments per 24 hours per space
100
Max number of job assignments per 24 hours per user
50
Max number of simultaneous job assignments per user
5
Max timeout between user job assignments
5 seconds
Max time to perform one job
-
Max lifetime of the report file
24 hours
Max number of report file downloads
10

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
devtodev ID
Numeric user identifier in the projects’s Users table
Main ID
Main user identifier
Created
User registration date. Unix timestamp
Paying
Flags payers
Cheater
Flags cheaters
Tester
Flags testers
Level
Current user level
AppVersion
Current app version
Language
User’s device locale
Country
User country (set by IP address)
Device manufacturer
Device manufacturer
Device name
Device trademark name
Crossplatform User ID
User ID set by developer
Channel
Acquisition. User acquisition channel
InstallSource
Android. Android installer bundle
User agent
User agent
Screen resolution
Screen resolution of the device or app’s workspace
OS version
Version of the operating system
IDFV
iOS vendor identifier
IDFA
iOS advertising identifier

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 count field) and time when the app was in focus (rows with filled avg_duration field).
Column name
Description
devtodev ID
Numeric user identifier in the project’s Users table
time
Event (session start or end of activity) start date. Unix timestamp in milliseconds
count
Session start
avg_duration
Average duration of user activity (time the app was in focus)
isTester
At the time of event start the user was a Tester
cheat
At the time of event start the user was a Cheater
level
User level at the time of event start
install_date
User registration date. Unix timestamp

IngamePurchase

This file contains entries on virtual purchases in the app.
Column name
Description
devtodev ID
Numeric user identifier in the project's Users table
time
Event (session start or end of activity) start date. Unix timestamp in milliseconds
level
User level at the time of event start
item_type
Item category
item
Item name
count
Amount of items the user bought
cheat
At the time of event start the user was a Cheater
isTester
At the time of event start the user was a Tester
install_date
User registration date. Unix timestamp
Virtual currency name 1
Amount of virtual currency spent on the item (overall)
Virtual currency name N
Amount of virtual currency spent on the item (overall)

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.
Column name
Description
devtodev ID
Numeric user identifier in the project’s Users table
install_date
User registration date. Unix timestamp

LevelUp

Event for when the user reaches a certain game level.
Column name
Description
devtodev ID
Numeric user identifier in the project’s Users table
time
Event (session start or end of activity) start date. Unix timestamp in milliseconds
level
User level at the time of event start
isTester
At the time of event start the user was a Tester
cheat
At the time of event start the user was a Cheater
install_date
User registration date. Unix timestamp
spent
Amount of virtual currency spent by user on the previous level. List of currency names and amounts separated by comma.
Example: “Coins: 90, Gold: 10”
earned
Amount of virtual currency earned by user on the previous level. List of currency names and amounts separated by comma.
Example: “Coins: 90, Gold: 10
balance
Amount of virtual currency on user balance at the time of reaching a new level. List of currency names and amounts separated by comma.
Example: “Coins: 90, Gold: 10
bought
Amount of virtual currency bought by user for real currency on the previous level. List of currency names and amounts separated by comma.
Example: “Coins: 90, Gold: 10

NewUserUpdate

Some user properties updates for the selected export period. (devtodev ID, logged IP, os_version).
Column name
Description
devtodev ID
Numeric user identifier in the project’s Users table
logged ip
User IP address. Last digit of the address is anonymized
os_version
Version of the user operating system

Payments

List of user transactions. Purchases for real currency.
Column name
Description
devtodev ID
Numeric user identifier in the project’s Users table
date
Event (session start or end of activity) start date. Unix timestamp in milliseconds
level
User level at the time of event start
transaction_id
Unique transaction identifier
transaction_name
Item name or SKU
amount_in_usd
Amount of real currency spent by user. Converted into USD using exchange rate at the moment the event is received by the devtodev server
status
Is transaction valid or not
install_date
User registration date. Unix timestamp
isTester
At the time of event start the user was a Tester
cheat
At the time of event start the user was a Cheater

Progression

This file contains a list of triggered Progression events.
Column name
Description
devtodev ID
Numeric user identifier in the project’s Users table
time
Event (session start or end of activity) start date. Unix timestamp in milliseconds
level
User level at the time of event start
location
Game location name
success
Is location successfully completed (true/false)
prev_location
Name of the previous location
duration
Time spent on completing the location
difficulty
Location difficulty (numeric)
isTester
At the time of event start the user was a Tester
cheat
At the time of event start the user was a Cheater
install_date
User registration date. Unix timestamp
spent
Amount of virtual currency or resources spent by user upon completing the location. List of currency names and amounts separated by comma.
Example: “Coins: 90, Gold: 10
earned
Amount of virtual currency or resources earned by user upon completing the location. List of currency names and amounts separated by comma.
Example: “Coins: 90, Gold: 10

SocialNetworkConnects

Social media connection events.
Column name
Description
devtodev ID
Numeric user identifier in the project’s Users table
time
Event (session start or end of activity) start date. Unix timestamp in milliseconds
level
User level at the time of event start
social
Name of social media
isTester
At the time of event start the user was a Tester
cheat
At the time of event start the user was a Cheater
install_date
User registration date. Unix timestamp

SocialNetworkPosts

Social media publication events.
Column name
Description
devtodev ID
Numeric user identifier in the projest’s Users table
time
Event (session start or end of activity) start date. Unix timestamp in milliseconds
level
User level at the time of event start
social
Name of social media
reason
Reason for publication or title of publication
isTester
At the time of event start the user was a Tester
cheat
At the time of event start the user was a Cheater
install_date
User registration date. Unix timestamp

SubscriptionPayments

Subscription events: buying, renewal, and refund. This file contains only subscription events that impact revenue.
Column name
Description
devtodev ID
Numeric user identifier in the project’s Users table
date
Event (session start or end of activity) start date. Unix timestamp in milliseconds
level
User level at the time of event start
transaction_id
Unique transaction identifier
transaction_name
Subscription name or SKU
amount_in_usd
Amount of real currency spent by user. Converted into USD using exchange rate at the moment the event is received by the devtodev server
install_date
User registration date. Unix timestamp
isTester
At the time of event start the user was a Tester
cheat
At the time of event start the user was a Cheater

Subscriptions

All subscription events.
Column name
Description
devtodev ID
Numeric user identifier in the project’s Users table
date
Event (session start or end of activity) start date. Unix timestamp in milliseconds
level
User level at the time of event start
transaction_id
Unique transaction identifier
transaction_name
Subscription name or SKU
action
An action to subscription. Examples:
purchased
changed renewal status
changed renewal pref
renewed
is_trial
Is subscription a trial or not
is_payment_received
Is payment successfully received or not
started_at
Subscription start date
expired_at
Subscription end date
amount_in_usd
Amount of real currency spent by user. Converted into USD using exchange rate at the moment the event is received by the devtodev server
install_date
User registration date. Unix timestamp
isTester
At the time of event start the user was a Tester
cheat
At the time of event start the user was a Cheater

Tutor

Tutorial steps events.
Column name
Description
devtodev ID
Numeric user identifier in the project’s Users table
time
Event (session start or end of activity) start date. Unix timestamp in milliseconds
level
User level at the time of event start
complete_state
Number of the completed step of the tutorial.
Also has predefined values:
0 – the user skipped the tutorial
-1 – the user started the tutorial
-2 – the user finished the tutorial
isTester
At the time of event start the user was a Tester
cheat
At the time of event start the user was a Cheater
install_date
User registration date. Unix timestamp

UDIDs

This file contains information about changes of user and device identifiers during the selected export period.
Column name
Description
devtodev ID
Numeric user identifier in the project’s Users table
Main ID
Main user identifier
IDFV
iOS vendor identifier
IDFA
iOS advertising identifier
Crossplatform User ID
User ID set by developer
Push token
User push token

UserUpdate

This file contains data on user characteristics and devices updates for the selected export period.
Column name
Description
devtodev ID
Numeric user identifier in the project’s Users table
Main ID
Main user identifier
IDFV
iOS vendor identifier
IDFA
iOS advertising identifier
Crossplatform User ID
User ID set by developer
logged
Date of user’s last activity
level
User level at the time of event start
language
User device locale
country
User country (from IP address)
sdk_version
SDK version at the time of data update
app_version
App version at the time of data update
created
User registration date. Unix timestamp
paying
Is user a payer or not
device_name
Device trademark name
cheater
At the time of event start the user was a Cheater
osversion
Version of the operating system at the time of the data update

AdImpression

This file contains app’s ad impression events. Data from ad networks or the Ad Impression event.
Column name
Description
devtodev ID
Numeric user identifier in the project’s Users table
date
Event (session start or end of activity) start date. Unix timestamp in milliseconds
level
User level at the time of event start
placement
Place where the ad unit is located
network
Name of ad network responsible for placement
unit
Name of ad unit/banner
source
Ad impression data source
revenue
Ad impression revenue in USD
install_date
User registration date. Unix timestamp
isTester
At the time of event start the user was a Tester
cheat
At the time of event start the user was a Cheater

CustomEvent.{EventName}

This file contains custom events with {EventName} name.
Column name
Description
devtodev ID
Numeric user identifier in the project’s Users table
date
Event (session start or end of activity) start date. Unix timestamp in milliseconds
level
User level at the time of event start
isTester
At the time of event start the user was a Tester
cheat
At the time of event start the user was a Cheater
install_date
User registration date. Unix timestamp
custom parameter name 1
Custom parameter value (string, number or boolean)
custom parameter name N (up to 30)
Custom parameter value (string, number or boolean)
Last modified 4mo ago