Raw Export
devtodev RAW export API
Last updated
devtodev RAW export API
Last updated
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 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.
This step is the most important, and its description is the longest one.
The request of assignment should be sent to:
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.
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
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.
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:
devtodevid
string
Unique identifier of the user which is used in devtodev and assigned to the user when he launches the app for the first time.
customuid
string
User ID, assigned by the developer.
idfa
string
iOS advertising identifier
idfv
string
iOS vendor identifier
advertisingid
string
Advertising ID (Android, Windows)
androidid
string
Android ID
created
int
Unix timestamp (ms) when the user opened the app for the first time
lasttime
int
Unix timestamp (ms) of the last user payment
publisher
string
Acquisition. The name of the publisher/ad network that led to the acquisition of the user
campaign
string
Acquisition. The name of the ad campaign that resulted in acquiring the user
placement
string
Acquisition. Place where the ad unit is located
ad
string
Acquisition. Name of ad unit/banner
firstpaymentdate
int
Unix timestamp (ms) of the first user payment
lastpaymentdate
int
Unix timestamp (ms) of the last user payment
paymentcount
int
Number of payments that the user have made in the app
paymentsum
number
Total sum of payments in USD
sbsfirstpaymentdate
int
Unix timestamp of the first subscription payment date
sbspaymentcount
int
The number of subscription payments made by the user in the app
sbspaymentsum
number
Total amount of subscription payments in USD
cheater
boolean
Whether the user has cheated or not (true/false
tester
boolean
Whether the user is a tester or not (true/false)
appversion
string
Current version of the app
firstappversion
string
App version installed by the user at the time of registration
sdkversion
string
Current version of devtodev SDK
level
int
Current user level
locale
string
User/device language (ISO 639-1, ISO 639-2, ISO 639-3)
country
string
User/device country (ISO_3166-1_alpha-2)
timezoneoffset
int
User timezone offset from UTC in milliseconds
pushavailable
boolean
True if there is a push token in devtodev DB
username
string
User name
string
User email
phone
string
User telephone number
photo
string
User photo url.
age
int
User age
gender
int
User gender. The values can be:
0 - Unknown gender
1 - Male
2 - Female
_AnyCustomUserPropertyName The prefix "_" here should be used to indicate that this is a custom property
string, number, boolean
Custom user card property, assigned by the developer.
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.
POST
Or another way with event group identificator.
The response in case of successful start execution:
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).
With the job identificator, you can request its current status, using the following request:
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 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.
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:
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:
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.
400
9
Event alias duplicated: %alias%
The event alias is duplicated. There should be no equal custom events without alias and no equal aliases in the request.
400
8
Unknown event: %event_name%
Unknown event. This error can raise when the event is not in @basic_event group or the event doesn’t exist or the event is blocked custom event.
500
1
Unknown Error
Unknown error. Please contact devtodev technical support.
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
Below you can find the description of each table for events available for export.
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.
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
OPEN_UDID
OpenUDID
username
User name. Preset using the User card
useremail
User email. Preset using the User card
userphoto
User photo url. Preset using the User card
userphone
User telephone number. Preset using the User card
AdCampaign
Acquisition. The name of the ad campaign that resulted in acquiring the user
Time zone offset
User timezone offset from UTC in milliseconds
OsVersion
Version of the user’s operating system
segments
List of user custom segments containing this user. Segments separated by comma
Agency
Acquisition. Ad mediator name (Sub-publisher)
Keyword
Acquisition. Ad keywords and/or keywords that led to install
Placement
Acquisition. Place where the ad unit is located
Site
Acquisition. Website or app where the ad was placed
Ad group
Acquisition. Name of ad group
Ad
Acquisition. Name of ad unit/banner
segments
Comma separated segment names. The state at the time the data was exported.
abtests
Comma separated names of AB test groups. The state at the time the data was exported.
Custom property field name 1
User card custom property
Custom property field name N
User card custom property
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).
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
session_starts
Session start. Marked as 1 when session started.
activity_duration
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
app_version
Application version. The data at the moment the event was generated.
segments
Comma separated segment names. The data at the moment the event was generated.
abtests
Comma separated names of AB test groups. The data at the moment the event was generated.
This file contains entries on virtual purchases in the app.
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)
app_version
Application version. The data at the moment the event was generated.
segments
Comma separated segment names. The data at the moment the event was generated.
abtests
Comma separated names of AB test groups. The data at the moment the event was generated.
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.
devtodev ID
Numeric user identifier in the project’s Users table
install_date
User registration date. Unix timestamp
Event for when the user reaches a certain game level.
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
app_version
Application version. The data at the moment the event was generated.
segments
Comma separated segment names. The data at the moment the event was generated.
abtests
Comma separated names of AB test groups. The data at the moment the event was generated.
Some user properties updates for the selected export period. (devtodev ID, logged IP, os_version).
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
List of user transactions. Purchases for real currency.
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
app_version
Application version. The data at the moment the event was generated.
segments
Comma separated segment names. The data at the moment the event was generated.
abtests
Comma separated names of AB test groups. The data at the moment the event was generated.
This file contains a list of triggered Progression events.
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
app_version
Application version. The data at the moment the event was generated.
segments
Comma separated segment names. The data at the moment the event was generated.
abtests
Comma separated names of AB test groups. The data at the moment the event was generated.
Social media connection events.
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
app_version
Application version. The data at the moment the event was generated.
segments
Comma separated segment names. The data at the moment the event was generated.
abtests
Comma separated names of AB test groups. The data at the moment the event was generated.
Social media publication events.
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
app_version
Application version. The data at the moment the event was generated.
segments
Comma separated segment names. The data at the moment the event was generated.
abtests
Comma separated names of AB test groups. The data at the moment the event was generated.
Subscription events: buying, renewal, and refund. This file contains only subscription events that impact revenue.
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
app_version
Application version. The data at the moment the event was generated.
segments
Comma separated segment names. The data at the moment the event was generated.
abtests
Comma separated names of AB test groups. The data at the moment the event was generated.
All subscription events.
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
app_version
Application version. The data at the moment the event was generated.
segments
Comma separated segment names. The data at the moment the event was generated.
abtests
Comma separated names of AB test groups. The data at the moment the event was generated.
Tutorial steps events.
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
app_version
Application version. The data at the moment the event was generated.
segments
Comma separated segment names. The data at the moment the event was generated.
abtests
Comma separated names of AB test groups. The data at the moment the event was generated.
This file contains information about changes of user and device identifiers during the selected export period.
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
This file contains data on user characteristics and devices updates for the selected export period.
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
This file contains app’s ad impression events. Data from ad networks or the Ad Impression event.
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
This file contains custom events with {EventName} name.
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
app_version
Application version. The data at the moment the event was generated.
segments
Comma separated segment names. The data at the moment the event was generated.
abtests
Comma separated names of AB test groups. The data at the moment the event was generated.
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)