Ingestion API
Introduction
To help games better understand a player's journey in your game, optimize your campaign performance and track results, CARV offers Ingestion API as an event tracking tool to track user events in game. These events will be fed into CARV' data warehouse and machine learning models to optimize campaign targeting, measurement and derivation of insights.
Getting Started
Contact CARV team via infra@carv.io to get an API key issued to your organization. All your requests to the APIs must include the following header:
| Header Name | Header Value | Example Value |
|---|---|---|
api_key | (String) API key | 7fcbe971-3fae-5988-946b-c25afae3a9b9v |
Key Concepts
States
States are the facts of the user at a given time. Examples of states are user's location, balance of their wallet, etc.
Events
User events are tracked user actions. Examples of events are a user loading a page, clicking a button, or opening an email.
Entities
Entities are key objects in the context of a game. Currently supported entities include item, task and achievement.
API Specifications
Post events and states
Send events and states.
POST https://api.carv.io/ingestion
Headers
| Name | Type | Description |
|---|---|---|
api_key* | String | API key issued by CARV |
Request Body
| Name | Type | Description |
|---|---|---|
message_id* | String | Universally unique identifier (UUID v4) idempotency key. This key is utilized to ensure exactly-once execution of mutating requests. |
name* | String | Event or State name, one from the above definition |
character_id* | Integer | If one user are allowed to create more than one character in the game, please specify the id here. E.g. 0 for the first character, 1 for the second character. |
timestamp | String | Unix Timestamp in milliseconds. |
uid | String | Partner user id, one of uid or (chain+address) needs to be sent |
chain | String | chain name, one of uid or (chain+address) needs to be sent |
address | String | User address on chain, one of uid or (chain+address) needs to be sent. |
properties | Object | Free-form dictionary of properties of the event or state, follow the above definition |
context | Object | Dictionary of extra information that provides useful context about the event or state such as location, device, ip, language. |
Post entities
Send metadata of entities.
POST https://api.carv.io/entity
Headers
| Name | Type | Description |
|---|---|---|
api_key* | String | API key issued by CARV |
Request Body
| Name | Type | Description |
|---|---|---|
id* | String | Unique id of the entity |
name* | String | Name of the entity. |
entity_type* | Entity type, one of [item, task, achievement] | |
description* | String | A short description. |
pic_url* | The url of the entity display picture. | |
properties | Object | Free-form dictionary of properties of the entity |
Recommended gaming app events
The following section provides a list of event structures that are typical to gaming apps in general. Each structure includes a pre-defined event name and suggested event parameters to use.
Standard Events and States
1. login
Understand the retention of your registered users. Emit when user logs in.
Properties
| Key | Value | Description |
|---|---|---|
method | (String) email,phone,wallet | Login method |
level | (String) | Current level of user |
achievements | (list<String>) | All completed achievements of the current user |
2. logout
Understand the activeness and engagement of users. Emit when user logs out.
3. register
Learn how many users installed the app and completed the signup process, and what signup methods your users prefer. Emit when the user completes the signup process.
Properties
| Key | Value | Description |
|---|---|---|
method | (String) email,phone,wallet | register method |
4. level_up
One of the main goals of users is to level up in games. Leveling up often unlocks new features and stages in the game and this encourages users to keep playing. Recording the level of achievement can help you:
Determine which campaigns generate the most active users
See what type of users are most active and engaged
Associate overall user activity with dimensions such as revenue
Emit when user level reaches to next level.
Properties
| Key | Value | Description |
|---|---|---|
level (required) | (String) | user current level |
5. achievement_unlock
In-game achievements track user's capability, time invested, money spent and more. Emit when user unlocks any achievement.
Properties
| Key | Value | Description |
|---|---|---|
achievement_id (required) | (String) email,phone,wallet | Achievement ID, use the entity api to send metadata of the achievement |
6. purchase
Normally games allow users to purchase items, for example, coins, gems, or weapons. Recording these purchases can help you:
Determine the LTV of your users and the ROI of your campaigns across ad networks and ad agencies
Determine what offers are most popular with your users
Cross-reference campaigns with purchased items in order to optimize campaign targeting
Emits when a successful purchase is made.
Properties
| Key | Value | Description |
|---|---|---|
currency | (String) USD, ETH | Currency code |
amount | (String) | amount of the transaction |
item_id | (String) | item id |
quantity | (integer) | Number of items purchased |
7. deposit
Emit when user deposits currency into the game account.
Properties
| Key | Value | Description |
|---|---|---|
currency | (String) USD, ETH | Currency code |
amount | (String) | amount of the transaction |
8. withdraw
Emit when user withdraws currency from the game account.
Properties
| Key | Value | Description |
|---|---|---|
currency | (String) USD, ETH | Currency code |
amount | (String) | amount of the transaction |
9. tutorial_initialize and tutorial_complete
Tutorials provide your users especially new users with guidance on how to use the app. Recording this event can help you determine:
What topics users might have trouble with
What tutorials are not performing well
Emit when a user initializes or completes a tutorial.
Properties
| Key | Value | Description |
|---|---|---|
tutorial_id (required) | (String) | tutorial id, metadata could be send via entity api |
10. share
Users like to share their achievements in games on social media sites. Sharing creates brand awareness and can drive more users to download and install your app. Recording this event can help you understand when users are most likely to share the app with their friends. Emit when user successfully made a share action.
Properties
| Key | Value | Description |
|---|---|---|
content | (String) | the content of the sharing |
platform (required) | (String) facebook, twitter | platfrom that user shared to |
11. invite_initialize and invite_complete
Learn which social media sites users send invites to, and how many users invited their friends to download and install the app. Emit when the user initializes or successfully invited a friend to download and install the app.
Properties
| Key | Value | Description |
|---|---|---|
content | (String) | the content of the invitation |
to_user_id | (String) | the user id of the destination user |
12. mission_initialize and mission_complete
Track the user gaming progress. Emit when user initializes or completes a mission.
Properties
| Key | Value | Description |
|---|---|---|
mission_id (required) | (String) | mission id |
13. boss_defeat
Track the user gaming progress. Emit when user defeats a boss.
Properties
| Key | Value | Description |
|---|---|---|
boss_id (required) | (String) | boss id, metadata could be send via entity api |
14. item_acquire
Collection items is a key part in game, it is a big need for user to presend the collection they have. Emit when user acquires an item in the game.
Properties
| Key | Value | Description |
|---|---|---|
item_id (required) | (String) | item id, metadata could be send via entity api |
15. pvp_battle
Track the user gaming progress. Emit when user has a battle.
Properties
| Key | Value | Description |
|---|---|---|
opponent_id (required) | (String) | opponent id, should be a user id of the opponent |
battle_type (required) | (String) | battle type |
result (required) | (String)) | win or lose |
16. item_enhance
Track the user gaming progress. Emit when user enhances an item in the game.
Properties
| Key | Value | Description |
|---|---|---|
item_id (required) | (String) | item id |
result (required) | (String) | success or fail |
item_level | (String) | item level after the enhancement |
17. item_trade
Track the user gaming progress. Emit when user trades an item in the game.
Properties
| Key | Value | Description |
|---|---|---|
item_id (required) | (String) | item id |
to_user_id (required) | (String) | the user id of the destination user |
currency | (String) | item level after the enhancement |
amount | (String) | transaction amount |
18. friend_add
Track the user social progress. Emit when user trades an item in the game.
Properties
| Key | Value | Description |
|---|---|---|
to_user_id (required) | (String) | the user id of the destination user |
Custom Events and States
You can send us custom events or states, just define your events/states name (suggest start with your game name like lol_customize_event_a to avoid duplication).
The properties of each events/states can also be customized.
Last updated