Integrate using the API
Overview
The App Tracking API enables you to record analytical data from the app you created in the Developer Console. The data is processed via our tracking interface at POST https://x.skymavis.com/track
.
Before you start
Before you start integrating your app with App Tracking, make sure you have access and an API key to the service.
Authentication
To authenticate with tracking API, send your API Key (api_key
) along with the request using the HTTP Basic Auth header.
The api_key
is used as username
in username:password
, where the password
field is left empty.
For example:
api_key = 'secret'
credential = base64encode(api_key + ':')
Then, the header is:
Authorization: Basic c2VjcmV0Ogo=
Content-Type
The content-type
header must be set to application/json
.
Errors
Status | Description |
---|---|
200 | Success |
5xx | Server error |
4xx | Client error: path not found, invalid api_key , exceeded rate limit. |
Limitations
- There is a maximum of 1 MB per request, both single and batch request.
- There is a threshold of 100 events per second. When we throttle a request, the response has an HTTP
429
status code.
API
For implementation details of the tracking events, see the following sections.
There is only one API https://x.skymavis.com/track
, which can be used to send both single and multiple events (batch).
We recommend sending by batch to reduce the throughput to the server, which also avoids request throttling.
If you are sending events by batch, be aware of the maximum of 1 MB per request.
Example:
Single:
POST https://x.skymavis.com/track
Content-Type: application/json
Authorization: Basic c2VjcmV0Ogo=
{
"api_key": "{API_KEY}",
"events": {
{ "type": "identify", "data": {"uuid": "1"} },
}
}
Batch:
POST https://x.skymavis.com/track
Content-Type: application/json
Authorization: Basic c2VjcmV0Ogo=
{
"api_key": "{API_KEY}",
"events": {
{ "type": "identify", "data": {"uuid": "1"} },
{ "type": "screen", "data": {"uuid": "2"} },
{ "type": "screen", "data": {"uuid": "3"} },
{ "type": "track", "data": {"uuid": "4"} },
{ "type": "track", "data": {"uuid": "5"} }
}
}
Events
There are three types of events.
Event type | Description |
---|---|
identify | Lets you profile users and record traits about them. |
screen | Lets you record whenever a user sees a web page or screen of your mobile app or game. |
track | Lets you record the actions users perform. Every action can have associated properties. |
As we do not validate the data structure of your requests, make sure they are correct and follow the associated event type.
Event modeling
Each event consists of some of the following components:
- Base data (all events)
- Platform data (
identify
events only) - Free-form data (all events)
Base data
Base data includes all the fundamental information about the event.
Field | Format | Required? | Description | Example |
---|---|---|---|---|
uuid | String | Required | Unique per event, follows UUID v4 standard. | bd36eb67-057a-4350-a6dc-876bf69fb4af |
ref | String | Required | Identifier of the reference event (the event that happens before event ), used to link events together. | root |
timestamp | String | Required | In ISO 8601 standard with UTC timezone. | 2020-07-10 15:00:00 |
session_id | String | Required | Unique for each session, follows UUID v4 standard. If the user logs out, session_id should be regenerated. | 03d7be98-e4aa-474f-95c4-e38959802a45 |
offset | Integer | Optional | Auto-increment, starts by 0 and increases by 1 per every event emitted, restarts to 0 when a new session starts. | 0 |
user_id | String | Optional | External identifier of the user. | 1ec9eb6f-3f66-6f9f-a60c-b01a7149cfda |
Example payload:
"uuid": "bd36eb67-057a-4350-a6dc-876bf69fb4af",
"event": "login",
"ref": "root",
"timestamp": "2020-07-10 15:00:00",
"session_id": "03d7be98-e4aa-474f-95c4-e38959802a45",
"offset": 0,
"user_id": "1ec9eb6f-3f66-6f9f-a60c-b01a7149cfda",
Platform data
Platform data includes all the OS, device, and network information about the session.
Field | Format | Required? | Description | Example |
---|---|---|---|---|
build_version | String | Optional | Build version. | 0.2.15-159 |
device_name | String | Optional | Device name. | Xiaomi POCOPHONE F1 |
device_id | String | Optional | Unique device identifier. | becb03c98e716ba970193551263ab110 |
platform_name | String | Required | Platform name, which can be the OS name or the browser's name. | Windows /Mac /iOS /Android /Chrome /Safari /Firefox /etc. |
platform_version | String | Optional | Platform version. | Android 8.0 /Windows 10 |
internet_type | String | Optional | How the user used the network. | wifi /ethernet /mobile_data |
Example payload:
// platform data
"build_version": "0.2.15-159",
"device_name": "Xiaomi POCOPHONE F1",
"device_id": "becb03c98e716ba970193551263ab110",
"platform_name": "Android",
"platform_version": "Android OS 10 / API-29 (QKQ1.190828.002/V12.0.3.0.QEJMIXM)",
"internet_type": "wifi",
Free-form data
Free-form data can be used to capture anything that doesn't belong to any of the fields in the Base data and Platform data sections.
user_properties
(identify event): free-form dict of properties of the user.
"user_properties": {
"email": "john.doe@skymavis.com",
"is_web3_user": false
},
action_properties
(track event): free-form dict of properties of user's actions.
# example properties for mouse tracking
"action_properties": {
"xs": [0, 100, 200, 300, 400, 500],
"ys": [0, 100, 200, 300, 400, 500]
},
screen_properties
(screen event): free-form dict of properties of the screen.
# example properties for A/B testing purpose
"action_properties": {
"design_version": "Athena",
"theme_version": "Dark Blue",
"button_version": "Materialized",
"font": "Helvetica"
},
Events structure with examples
This sections provides the actual structure of identify
, screen
, and track
events with examples.
Identify
When the user is identified, that is the user_id
(or ronin_address
) is known, you can send the identify
event into the tracking endpoint.
You can include ronin_address
in base data:
Field | Format | Required? | Description | Example |
---|---|---|---|---|
ronin_address | String | Optional | The Ronin address of the user. | 0xe514d9deb7966c8be0ca922de8a064264ea6bcd4 |
{
// base data
"uuid": "69660436-bf79-4e8b-a9be-9b3ba2fe20e8",
"ref": "ref",
"timestamp": "2006-01-02 15:04:05",
"session_id": "aeaad67a-a12a-41f5-ba79-23b893ddc6ba",
"offset": 10,
"user_id": "aeaad67a-a12a-41f5-ba79-23b893ddc6ba",
"ronin_address": "0xe514d9deb7966c8be0ca922de8a064264ea6bcd4",
// platform data
"build_version": "",
"device_name": "",
"device_id": "",
"platform_name": "",
"platform_version": "",
"internet_type": "",
// user properties
"user_properties": {
"email": "",
},
}
Screen
For screen
events, the following field is required:
Field | Format | Required? | Description | Example |
---|---|---|---|---|
screen | String | Required | Identifier of the event. Should match your internal implementation name, for easier integration and semantic understanding. | lobby |
{
// base data
"uuid": "69660436-bf79-4e8b-a9be-9b3ba2fe20e8",
"ref": "ref",
"timestamp": "2006-01-02 15:04:05",
"session_id": "aeaad67a-a12a-41f5-ba79-23b893ddc6ba",
"offset": 10,
"user_id": "aeaad67a-a12a-41f5-ba79-23b893ddc6ba",
// screen properties
"screen": "screen_name",
"screen_properties": {},
}
Track
For track
events, the following field is required:
Field | Format | Required? | Description | Example |
---|---|---|---|---|
action | String | Required | Identifier of the event. Should match your internal implementation name, for easier integration and semantic understanding. | login |
{
// base data
"uuid": "69660436-bf79-4e8b-a9be-9b3ba2fe20e8",
"ref": "ref",
"timestamp": "2006-01-02 15:04:05",
"session_id": "aeaad67a-a12a-41f5-ba79-23b893ddc6ba",
"offset": 10,
"user_id": "aeaad67a-a12a-41f5-ba79-23b893ddc6ba",
// action properties
"action": "action_name",
"action_properties": {
"name": "Nguyen Van A",
"email": "nguyen@gmail.com"
},
}