Links

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 [email protected] 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

Post entities

Send metadata of entities.
post
https://api.carv.io
/entity
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.