Analytics Ingestion
Treasure’s Data Platform (codename Darkmatter) is a powerful, scalable and real-time streaming analytics service that allows developers to collect data from games. This data can be used to understand player behaviour, improve game design, and optimize your game’s performance. In the future, this data will power various downstream services such as player segmentation, A/B testing, and more.
Prepare your payload
Messages need to be in the following format, and multiple events can be included in the batch array.
[
{
"cartridge_tag": "<cartridge tag for game - check with Treasure team e.g. zeeverse>",
"name": "<name of event - check with Treasure team e.g. my_event>",
"time_server": <UNIX milliseconds time of event, e.g. 1712162689906>,
"time_local": <If available, UNIX milliseconds of event at originating device>,
"smart_account": "<smart account or wallet address>",
"user_id": "<unique user id within the game's system (optional if smart_account is known)>",
"id": "<unique id for event e.g. 10016ada185840db9e9250d76290303b>",
"session_id": "<unique session id (if available) e.g. 5076f1bb49ca4156a229fbb23ee7450f>",
"chain_id": <chain id (number)>,
"device": {
"device_name": "<device name if known>",
"device_model": "<device model if known>",
"device_unique_id": "<unique identifier for device>",
"device_os": "<device os if known>",
},
"app": {
"app_identifier": "bundle/package name of ap e.g. lol.treasure.tdkunity",
"app_version": "<version of app e.g. 0.1>",
"app_environment": <0 for dev, 1 for prod>
}
"properties": {
"custom_event_key": "hello world",
"custom_event_key_2": false,
},
},
]
Push analytics events to Treasure
From your backend, push your event payloads to our infra. You can choose from the following methods: Kafka, HTTP POST, or AWS SNS.
There is no need for you to set up your own Kafka cluster with this approach. Just send messages to a dedicated Redpanda Kafka topic that Treasure manages for you.
If you are using the Kafka option, prepare each payload as a single JSON object. If you need to batch them together, you can use the Kafka client API to send a batch of single messages.
- Receive Kafka client credentials (username, password, bootstrap URL) from Treasure.
- Send your JSON payloads using a Kafka producer client. Kafka client libraries are available in a number of languages. The following example is in TypeScript (assumes you have already installed
kafkajs@2.2.4
):
import { Kafka as KafkaJs, logLevel } from "kafkajs";
// Create a Kafka producer client.
const kafka = new KafkaJs({
clientId: "mygame-client-id", // You choose this.
brokers: ["KAFKA_BOOTSTRAP_URL"], // Assigned by Treasure.
logLevel: logLevel.WARN,
ssl: true,
sasl: {
mechanism: "scram-sha-256",
username: "KAFKA_USERNAME", // Assigned by Treasure.
password: "KAFKA_PASSWORD", // Assigned by Treasure.
},
});
const producer = kafka.producer();
await producer.connect();
// Prepare event key, payload.
const eventPayload = {
smart_account: "0x1234567890123456789012345678901234567890",
user_id: "<unique user identifier>", // Needed if smart_account is undefined.
chain_id: 42621,
cartridge_tag: "the-game", // Ask Treasure what is your cartridge_tag.
name: "session_start", // Ask Treasure what this should be.
session_id: "5076f1bb49ca4156a229fbb23ee7450f",
id: "<unique identifier for this event>", // You determine this.
time_server: 1712162689906,
properties: {
custom_event_key: "hello world",
custom_event_key_2: false,
},
device: {
device_name: "zxy_device",
device_model: "iPhone 11",
device_unique_id: "ae11273914287364284736423",
device_os: "iOS",
},
app: {
app_identifier: "the-game-backend",
app_version: "1.0",
app_environment: 1, // 0 for dev, 1 for prod
},
};
// Send message to Treasure Kafka.
await producer.send({
topic: "KAFKA_TOPIC", // Assigned by Treasure.
messages: [
{
key: eventPayload.id,
value: JSON.stringify(eventPayload),
},
// If you want to send a batch of messages,
// you can include more here.
],
});