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

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"
    },
}

See also

• Integration milestones