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.
  ],
});

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.
  ],
});

If you choose this step, let us know and in a private channel we’ll provide you the {DATA_PLATFORM_URL} and the X-API-Key header value to use. Make a POST call to https:// {DATA_PLATFORM_URL}/ingress/events where the body of the quest is your event payload JSON.

Make an HTTP POST call using your preferred method. This example uses the Axios HTTP client for Node.js.

import axios from "axios";

// Single payload.
const payload = {
  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
  }
};

await axios.post(`${DATA_PLATFORM_URL}/ingress/events`, payload, {
  headers: { "X-API-Key": X_API_KEY },
});

// Batch payload.
const payloadBatch = [
  {
    smart_account: '...',
    user_id: '...',
    chain_id: 1,
    cartridge_tag: 'the-game',
    name: 'session_start',
    session_id: '...',
    id: '...',
    time_server: 1712162689800,
    properties: { ... },
    device: { ... },
    app: { ... },
  },
  {
    smart_account: '...',
    user_id: '...',
    chain_id: 1,
    cartridge_tag: 'the-game',
    name: 'session_start',
    session_id: '...',
    id: '...',
    time_server: 1712162691553,
    properties: { ... },
    device: { ... },
    app: { ... },
  },
  {
    smart_account: '...',
    user_id: '...',
    chain_id: 1,
    cartridge_tag: 'the-game',
    name: 'session_start',
    session_id: '...',
    id: '...',
    time_server: 1712162695102,
    properties: { ... },
    device: { ... },
    app: { ... },
  },
];

await axios.post(`${DATA_PLATFORM_URL}/ingress/events`, payloadBatch, {
  headers: { "X-API-Key": X_API_KEY },
});

If you choose this method, let us know and we’ll provide you the {TREASURE_AWS_ACCOUNT} in a private channel.

Create an SNS topic. Let’s say you called it prod-events-for-treasure. Then its topicArn is going to be arn:aws:sns:{your AWS region}:{your AWS account}:prod-events-for-treasure.
Allow Treasure’s AWS account to subscribe to your SNS topic by adding this to your SNS topic’s access policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "TreasureSubscribe",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::{TREASURE_AWS_ACCOUNT}:root"
      },
      "Action": "sns:Subscribe",
      "Resource": "arn:aws:sns:{your AWS region}:{your AWS account}:prod-events-for-treasure"
    }
  ]
}

Please tell us your SNS topic’s topicArn so we can update our infrastructure to subscribe to it.
Grant your own lambdas/servers sns:Publish permission to send payloads to the SNS topic.
Publish event payloads to your SNS topic. AWS SDKs support multiple languages. The following example is in TypeScript:

import { SNS } from '@aws-sdk/client-sns';

const topicArn =
    'arn:aws:sns:{your AWS region}:{your AWS account}:prod-events-for-treasure';

const sns = new SNS({ ... });

// Single payload.
const payload = {
    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
    }
}

await sns.publish({
    TopicArn: topicArn,
    Message: JSON.stringify(payload),
});

// Batch payload.
const payloadBatch = [
  {
    smart_account: '...',
    user_id: '...',
    chain_id: 1,
    cartridge_tag: 'the-game',
    name: 'session_start',
    session_id: '...',
    id: '...',
    time_server: 1712162689800,
    properties: { ... },
    device: { ... },
    app: { ... },
  },
  {
    smart_account: '...',
    user_id: '...',
    chain_id: 1,
    cartridge_tag: 'the-game',
    name: 'session_start',
    session_id: '...',
    id: '...',
    time_server: 1712162691553,
    properties: { ... },
    device: { ... },
    app: { ... },
  },
  {
    smart_account: '...',
    user_id: '...',
    chain_id: 1,
    cartridge_tag: 'the-game',
    name: 'session_start',
    session_id: '...',
    id: '...',
    time_server: 1712162695102,
    properties: { ... },
    device: { ... },
    app: { ... },
  },
];

await sns.publish({
    TopicArn: topicArn,
    Message: JSON.stringify(payloadBatch),
});

Introduction

Treasure Chain

Treasure Development Kit (TDK)

Magicswap

Platform

Treasure Desktop Launcher

References

Prepare your payload

Push analytics events to Treasure