Raw Export | Documentation

Last updated 1 year ago

Was this helpful?

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:

List of available events and their identificators

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

Custom events filtering

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

User card filtering

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

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

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

The table shows the fields by which filtering is possible:

List of comparison operators which can be applied in filter

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

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

Examples

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

POST

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

Or another way with event group identificator.

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

The format of the response to the job assignment

The response in case of successful start execution:

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

Where

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

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

Getting the status of performance

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

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

The body of request can contain the following properties:

The format of the response to the request of status

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

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

Let’s explore every variant.

The job is in the queue

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

The job is in progress

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

The job is done

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

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

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

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

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

Error handling

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

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

where

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

The list of possible errors is given in a table.

Limitations

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

List of available events

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

Users

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

GameSessions

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

IngamePurchase

This file contains entries on virtual purchases in the app.

Install

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

LevelUp

Event for when the user reaches a certain game level.

NewUserUpdate

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

Payments

List of user transactions. Purchases for real currency.

Progression

This file contains a list of triggered Progression events.

SocialNetworkConnects

Social media connection events.

SocialNetworkPosts

Social media publication events.

SubscriptionPayments

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

Subscriptions

All subscription events.

Tutor

Tutorial steps events.

UDIDs

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

UserUpdate

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

AdImpression

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

CustomEvent.{EventName}

This file contains custom events with {EventName} name.

Last updated 1 year ago

Was this helpful?