Post-Install Analytics — Event & Level Tracking via SDK

Last Update:
Chartboost's event tracking lets you monitor play engagement to create segments of users who are likely to make in-app purchases. These segments can then optimize your user acquisition, power your retargeting campaigns, and drive other types of monetization.

Contents


Event Tracking Overview

The PIA Event Tracking integration works by sending player level data – tutorial completed, for example – to Chartboost via SDK or S2S (directly or via a third party) in the form of distinct Event Fields.

We designed the fields to let you collect and send level data in a way that will maximize reengagement and monetization via intelligent segmentation of players.

Each event field must correspond to a single type of level data.

The available fields are listed in the table below; common use cases follow:

Event Field Example Event Label 1 Definition Sequential? 2

Segmentation
Operators 3

Optional
Description Example 4
1 "HIGHEST_LEVEL_REACHED" Highest numerical level a user has reached Yes >=, >, ==, <, <= "Chocolate Fudge Level"
2 "CURRENT_AREA" User's current level/area - ==, != "Lunar Caverns"
3 "CHARACTER_LEVEL" The level of the player’s character in game Yes >=, >, ==, <, <= "Master Wizard"
4 "OTHER_SEQUENTIAL" Extra field for developers to send sequential data Yes >=, >, ==, <, <= "5"
5 "OTHER_NONSEQUENTIAL" Extra field for developers to send non-sequential data - ==, != "Tutorial Completed"
Notes

1. Event labels are required and will be used to identify the type of event field in the Chartboost dashboard

2. A sequential event field is used to track either 1) level data that is always increasing and can never decrease; or 2) numerical data you need to segment based on whether a player is "higher" or "lower" than a certain number (see Use Cases section below)

3. These operators will be able to be used to create player segments to optimize UA efforts, power retargeting campaigns, and drive other types of monetization

4. Optional event descriptions can be used to identify the level name ("Lunar Caverns," for example) rather than the type of level event ("Area main character is in")


In addition to the event field title and event description, the integration requires that you include numerical level values and also supports optional sub-level values.

If your game is area based or uses non-sequential levels, you'll need to map the areas to level values internally (e.g. "Exalted Plains" = 1, "Emerald Graves" = 2, etc.).

Our system will track players' level data and update it upon receipt of new level events.


Use Cases

This section explores possible use cases for each of the five event field types. Note that the OTHER_SEQUENTIAL and OTHER_NONSEQUENTIAL events are extra buckets you can use to categorize and track additional level data.


Highest Level Completion (includes OTHER_SEQUENTIAL)

Use Case #1: Simple Levels

In "Sugar Smash Story," Jane reaches level 400 on 1/15/2015. Upon reaching this level, the game sends an event to Chartboost and the following data is recorded for her device ID and replaces her current state, "level 399."

  • Event Field: 1
  • Event Label: "Sugar Smash Level"
  • Main Level Value: 400
  • Sub Level Value: 0
  • Level Description: "Chocolate Fudge Level"

Use Case #2: Complex Levels

In "Foul Mood Fowl," Bob just finished level 9 of area 2 (2-9). Upon reaching level 10 of area 2 (2-10), the game sends an event to Chartboost with the following data:

  • Event Field: 1
  • Event Label: "Foul Mood Fowl Level"
  • Main Level Value: 2
  • Sub Level Value: 10
  • Level Description: "2-10"

Area in Game Reached/Current Level

Use Case #1: Open-World Levels

In an open-world RPG, Joe travels to the "Exalted Plains" level from "Emerald Graves". The game will send the following event to Chartboost:

  • Event Field: 2
  • Event Label: "Character Current Area"
  • Main Level Value: 3
  • Sub Level Value: 0
  • Level Description: "Exalted Plains"

In this example, the game could have an area-to-level mapping of:

  • Hinterlands = 1
  • Fallow Mires = 2
  • Exalted Plains = 3
  • Emerald Graves = 4

Use Case #2: FTUE (First-Time User Experience)

In an action game where the first few levels are the FTUE/tutorial, you can use the OTHER_SEQUENTIAL or OTHER_NONSEQUENTIAL fields (depending whether you track progress in a tutorial or just tutorial completion) to send us level data in addition to the level data you’re tracking via the HIGHEST_LEVEL_REACHED event field:

For games with sequential tutorial levels:

  • Event Field: 4
  • Event Label: "Tutorial Progress"
  • Main Level Value: 0
  • Sub Level Value: 0
  • Level Description: "Tutorial Start"

To track only tutorial completion:

  • Event Field: 4
  • Event Label: "Tutorial Progress"
  • Main Level Value: 1
  • Sub Level Value: 0
  • Level Description: "Tutorial Complete"

Character Level (includes OTHER_SEQUENTIAL)

In some games – especially RPGs or mid-core games – the character level is the data that you'll want to segment and target.

Use Case: Mid-Core MOBA Game

When Terri’s elven mage reaches level 10, you'd send an event to Chartboost:

  • Event Field: 3
  • Event Label: "Player character level"
  • Main Level Value: 10
  • Sub Level Value: 0
  • Level Description: "Elven Mage"

The next sections walk you through the steps required to send level data to Chartboost via SDK, S2S integration or third-party.


iOS SDK Event Tracking Integration

Prerequisites

Before you get started, you'll need to:

Integration

You should first enumerate the five types of level events as follows:

typedef enum {
    // Highest level reached
    HIGHEST_LEVEL_REACHED = 1,
    // Current area level reached
    CURRENT_AREA = 2,
    // Current character level reached
    CHARACTER_LEVEL = 3,
    // Other sequential level reached
    OTHER_SEQUENTIAL = 4,
    // Current non sequential level reached
    OTHER_NONSEQUENTIAL = 5
} CBLevelType;

After that, you can use the code below to track level information about your user. Levels can be sequential, non-sequential, character levels and more.

@interface CBAnalytics : NSObject

// For games with sub-levels

+ (void)trackLevelInfo:(NSString*)eventLabel
            eventField:(CBLevelType)eventField
             mainLevel:(NSUInteger)mainLevel
              subLevel:(NSUInteger)subLevel
           description:(NSString*)description;
           
@end
@interface CBAnalytics : NSObject

// For games without sub-levels

+ (void)trackLevelInfo:(NSString*)eventLabel
            eventField:(CBLevelType)eventField
             mainLevel:(NSUInteger)mainLevel
           description:(NSString*)description;
           
@end

Definitions:

  • eventField: Any value from the CBLevelType enum shown above; used to define type of event. Sent as an integer (1-5) to Chartboost.
  • mainLevel: Non-zero integer value that represents the player's main level
  • subLevel: Integer that represents player's sub-level; use second method above if not applicable
  • description: Optional string describing the event

Google Play SDK Event Tracking Integration

Prerequisites

Before you get started, you'll need to:

Integration

You should first enumerate the five types of level events as follows:

public class CBAnalytics {
    public enum CBLevelType {
        HIGHEST_LEVEL_REACHED(1),
        CURRENT_AREA(2),
        CHARACTER_LEVEL(3),
        OTHER_SEQUENTIAL(4),
        OTHER_NONSEQUENTIAL(5);
    }
}

After that, you can use the code below to track level information about your user. Levels can be sequential, non-sequential, character levels and more.

public class CBAnalytics {

// For games without sub-levels:
    public static synchronized void trackLevelInfo(String eventLabel, CBLevelType type, int mainLevel, String description) {
        trackLevelInfo(eventLabel, type, mainLevel, 0, description);
    }
    
}
public class CBAnalytics {

// For games with sub-levels:
    public static synchronized void trackLevelInfo(String eventLabel, CBLevelType type, int mainLevel, int subLevel, String description) {
        trackLevelInfo(eventLabel, type, mainLevel, subLevel, description);
    }
    
}

Amazon SDK Event Tracking Integration

Prerequisites

Before you get started, you'll need to:

Integration

For Amazon Event Tracking, follow our Google Play integration instructions above.


Unity Plugin Event Tracking Integration

Prerequisites

Before you get started, you'll need to:

Integration

You should first enumerate the five types of level events as follows:

namespace ChartboostSDK {

/// Enum values for PIA Event Tracking
	public enum CBLevelType : int {
		// Highest Level reached 
		HIGHEST_LEVEL_REACHED = 1,
		// Current area level reached 
		CURRENT_AREA = 2,
		// Current character level reached 
		CHARACTER_LEVEL = 3,
		// Other sequential level reached
		OTHER_SEQUENTIAL = 4,
		// Current non sequential level reached 
		OTHER_NONSEQUENTIAL = 5
	};
}

After that, you can use the code in the appropriate block below to track level information about your user. Levels can be sequential, non-sequential, character levels and more.

Games with sub-levels

namespace ChartboostSDK {
		
    public static void trackLevelInfo(String eventLabel, CBLevelType type, int mainLevel, int subLevel, String description) {
        CBExternal.trackLevelInfo(eventLabel, type, mainLevel, subLevel, description);
    }
    
}

Games without sub-levels

namespace ChartboostSDK {

    public static void trackLevelInfo(String eventLabel, CBLevelType type, int mainLevel, String description) {
        CBExternal.trackLevelInfo(eventLabel, type, mainLevel, description);
    }
  
}

Definitions:

  • type: Any value from the CBLevelType enum shown above; used to define type of event
  • mainLevel: Non-zero integer value that represents the player's main level
  • subLevel: Integer that represents player's sub-level; use second method above if not applicable
  • description: Optional string describing the event

Server-to-Server Event Tracking Integration

The Chartboost server-to-server (S2S) PIA Event Tracking integration can track information player engagement and store it in our system.

S2S Event Tracking calls contain level information and an API token (contact us for your token) to verify the request:

{
    'app_id': app_id,
    'gaid': gaid,
    'event': {
        'event_label': event_label,  
        'event_field': event_field,  
        'main_level': main_level,
        'sub_level': sub_level,
        'description': description
    }

Below is information about the Event Tracking call itself; to receive your API token, contact Chartboost Support.

Event Tracking S2S Request Details

Method

POST

Endpoint

https://live.chartboost.com/event_service/v3/track

Headers

(Note that headers contain authentication information.)

Header Name Example Description
X-Chartboost-Token 9782f24948b6d8125518f421f70240c415e0d25b Your API Token (please contact support.integrations@chartboost.com for your PIA API Token & API Secret)
X-Chartboost-Signature 173e6aeff28e4b76b488d5acf49ed8ebb8e95559 See this gist to generate. This is NOT the same value as your Chartboost app signature!

JSON Body: Event Tracking Parameters

Parameters iOS Apps Android Apps Example Description
track_info       Array of objects below
event_label Required Required "Highest level puzzle solved" Custom label for in-game event
event_field Required Required 1 ID corresponding to type of event; see this table for IDs
main_level Required Required 2 Main level (non-zero integer)
sub_level Required Required 1 Sub-level integer (use 0 if not applicable)
description Optional Optional "The boss level" Description of the level

JSON Body: Identifiers Parameters

Parameters iOS Apps Android Apps Example Description
App ID Required Required "54ecc0535beacdc1e1eff778"  Chartboost App ID (found in the Chartboost dashboard)
ifa Required N/A IFA: "7e8ec8092004283043e99d515ab0c51b0ef755ff" (32 characters; dashes OK; uppercase letters OK) Identifier for Advertising
gaid N/A Required "38400000-8cf0-11bd-b23e-10b96e40000d" (32 characters, plus 4 dashes) Google Services Advertising ID (Android Only)
uuid N/A Optional (if GAID not sent, or if Amazon app) "358414046356276" For legacy Android IDs or Amazon games
First, start with the endpoint:Building the Request
https://live.chartboost.com/event_service/v3/track

Add the parameters in the JSON body, and then you're done – successful requests will receive: {"status":200,"message":"Success"}.

If your call receives a 500 HTTP error code, your server should reattempt the S2S call, but at a later time: Try again in 2 seconds, then 4 seconds, then 8 seconds, then 16 seconds until successful.

Third-Party Server-to-Server Event Tracking Integrations

For a more complete analysis of level data across platforms or networks, you can also set up a S2S integration to import level data from third-party tracking services. After the integration, you'll be able to view the third-party data in the Chartboost dashboard. Learn more ▶


Level/Event User Segments

To find out how to create user segments based on level/event data, see our user segment builder instructions.


Level/Event Tracking Analytics Dashboard

You can use the Post-Install Analytics dashboard to view event tracking analytics. See these PIA dashboard instructions for more information.