devtodev RAW export API

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

Attention! 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 this 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 individual User API token.

 

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 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 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.

app_id

string

Application identificator. It can be found in the application settings in 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 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

@basic_events

All events below

Any custom event name

Custom event

@custom_events

All custom events

 

Custom events filtering

If you’re interested in export of custom events according to some specific conditions, you should set the objects with following properties in 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 filter 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 “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 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 select all the events where 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 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 - 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 response of job assignment.

 

The format of 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 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 in the moment of job assignment or in the moment of checking the status.

The format of response in case of error is the same:

In case there is an error, an 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 request. There is no POST data in the request.

400

3

Malformed json

JSON error in the body of request. 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 user makes a mistake with 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 to access to the application used in 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 raise 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%

Obligatory field can not be found. You need to complement 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 user is exceeded. You can send the next request in the beginning of 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 in the beginning of 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 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 request with the format set in 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 with devtodev technical support.

 

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 report file

24 hours

Max number of report file downloads

10

 

Data API
Push API