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:
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
|
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:
Property | Type | Description |
---|---|---|
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:
|
| ||
_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.
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 |
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).
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 |
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.
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) |
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.
Column name | Description |
---|---|
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.
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 |
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).
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 |
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 |
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.
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 |
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.
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 |
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.
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 |
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.
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 |
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.
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 |
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.
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 |
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.
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 |
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 |
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 |
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 |
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) |