Integrate the App Tracking API
Overview
The App Tracking API enables your game to record analytical data via our tracking interface POST https://x.skymavis.com/track
that also handles data processing.
How it works
Whenever a user interacts with your website or app, the website or app sends a request to the App Tracking API. The request includes information about the user, such as their IP address, browser, and operating system.
The API then returns data about the interaction, such as the page the user visited, the time they spent on the page, and any actions that they took, to Sky Mavis. The data is then visualized in the Developer Console.
Prerequisites
Complete the steps in Get started.
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 blank.
For example:
api_key = 'secret'
credential = base64encode(api_key + ':')
Then, the header is:
Authorization: Basic c2VjcmV0Ogo=
Content-Type
You must set the content-type
header to application/json
.
Errors
Status | Description |
---|---|
200 | Success |
5xx | Server error |
4xx | Client error: path not found, invalid api_key , exceeded rate limit. |
Limitations
- Maximum of 1 MB per request, applicable to both single and batch requests.
- Maximum 100 requests per second. When the system throttles 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 you can use 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 1 MB per request limit.
This example sends a single event:
POST https://x.skymavis.com/track
Content-Type: application/json
Authorization: Basic c2VjcmV0Ogo=
{
"api_key": "{API_KEY}",
"events": {
{ "type": "identify", "data": {"uuid": "1"} },
}
}
This example sends multiple events:
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
App Tracking supports the following 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 the system doesn't validate the data structure of your requests, make sure that they're 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, adheres to the 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 | UTC timezone compliant with the ISO 8601 standard. | 2020-07-10 15:00:00 |
session_id | String | Required | Unique for each session, adheres to the UUID v4 standard. If the user logs out, your game must regenerate session_id . | 03d7be98-e4aa-474f-95c4-e38959802a45 |
offset | Integer | Optional | Auto-increment, starts at 0 and increases by 1 per every event emitted, and resets to 0 when a new session starts. | 0 |
user_id | String | Optional | External identifier of the user. | 1ec9eb6f-3f66-6f9f-a60c-b01a7149cfda |
Example payload:
// Base data
"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 the information about the session, including the operating system, device, and network information:
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 identifier of the device. | becb03c98e716ba970193551263ab110 |
platform_name | String | Required | Platform name, which can be the name of the operating system or that of the browser. | Windows /Mac /iOS /Android /Chrome /Safari /Firefox /etc. |
platform_version | String | Optional | Platform version. | Android 8.0 /Windows 10 |
internet_type | String | Optional | The way the user accesses the internet. | 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
You can use free-form data 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
"action_properties": {
"design_version": "Athena",
"theme_version": "Dark Blue",
"button_version": "Materialized",
"font": "Helvetica"
},
Event structure with examples
This sections provides the actual structure of identify
, screen
, and track
events with examples.
Identify
When your game identifies the user, that is, you know the user_id
/ ronin_address
, you can send the identify
event to the tracking endpoint.
Field | Format | Required? | Description | Example |
---|---|---|---|---|
ronin_address | String | Required | 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 system requires the following field:
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 system requires the following field:
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"
},
}