Table of Contents
This is a comprehensive document explaining the concept the use of Custom Event in the context of Tapjoy Analytics.
What is Custom Event?
Custom Event allows you to define and record interesting user behaviors. Once you complete the basic Tapjoy SDK integration, sessions and in-app purchases are recorded and analyzed by default. However, there may be certain events that you would like to record specific to your game. You can define events like Level Up or Add friend, but really there is no limit to what event you would like to record. It is our hope that through Custom Events, you can get a better understanding of your users.
When user exhibits a behavior that you defined as Custom Event, the event is automatically reported to the Tapjoy server. From the [Custom Event] analysis page, you can see all the recorded events and relevant indicators in one sight. You can also configure Custom Event to record certain parameters or values when report an event. This may allow you for a more meaningful analysis of the event.
You can also use Custom Events in conjunction with a variety of other Tapjoy features. Note that [Custom Events] page allows you to view data by User Cohort. So you could, for example, see how Japanese and American users differ in purchase of a particular in-app product, or how low-level users and high-level users compare in frequency of adding a new friend. Also note that you can use Custom Event as steps in funnel analysis. This is particularly useful you’re trying to figure out:
- Significant events that affect user engagement
- Conversion rate from one event to another
- Which component of the game your users enjoy and do not enjoy
Again, you do not need to configure a Custom Event for events we record by default, such as session start/end, purchase, and campaign exposure/click.
Event Parameters and Values
When reporting a Custom Event, you can also pass parameters and values associated with the event. For example, when user purchases 50 Gold from the store, you can define ‘Gold_Purchase’ as the custom event and pass ‘Amount: 50’ as the value. Note that parameters are conventionally used for discrete variables like win and lose, while value are usually used for numerical variables.
For each Custom Event, you can define up to 2 parameters and 2 values. Depending on what you wish to analyze, the appropriate values and parameters to pass for an event will vary.
Finally, you can optionally pass the category when reporting an event. For the Gold example, you could say the category is economy.
Of course, you do not need to include parameters and values that we collect by default, such as App Version, OS version, device, country, and User ID.
Example Custom Event
Below is an illustration of how Custom Event can be structured when user finishes playing a stage in your game.
We will name this event StageFinished under category GAME.
When a StageEvent event occurs, we could report the event as follows:
Tapjoy.trackEvent(‘GAME’, ‘StageFinished’, ’10’, ‘y’, "Score", 12321, "GoldUsed",150);
Tapjoy.trackEvent(‘GAME’, ‘StageFinished’, ’20’, ‘n’, "Score", 2233123, "GoldUsed",10, "DiamondGained",150);
Of course, this is a limited example. You could even report the number of tries it took to clear the stage, time it took to clear the stage, etc.
Custom Event – Example
Tracking custom events like ‘Level Up’ or ‘Pick up sword’ will enable you to analyze very specific gameplay behaviors of users. Here, we go over an example set-up of custom event for HunterHK. You can find all of the code in this section inside HelloWorldScene.cpp.
In-App Product Analysis
You can also analyze specific in-app products within the game by tracking custom events. In the example game HunterHK, an
EarnRuby event is created when a ruby item is obtained and a
<UseRuby event is created when a ruby item is consumed.
NSError *error; [Tapjoy trackEvent:@"EarnRuby" // Event Name category:@"Economy" // Event Category parameter1:@"BuySingPack" // Event Parameter 1 (Acquisition channel) parameter2:(campaignId ? @"Event" : @"Normal") // Event Parameter 2 (Type) value:1 // Event Value withError:&error];
A simple trackEvent method is called, since the number of rubies obtained is sufficient for event value. Event parameters are determined according to purchase channel, item type, etc.
UseRuby event is reported when ruby item is consumed.
NSError *error; [Tapjoy trackEvent:@"UseRuby" // Event Name category:@"Economy" // Event Category parameter1:@"InGame" // Event Parameter 1 (Usage) parameter2:(campaignId ? @"Event" : @"Normal") // Event Parameter 2 (Type) value:1 // Event Value withError:&error];
First, create a Stage event whenever user clears a stage.
NSError *error; [Tapjoy trackEvent:@"Stage" // Event Name category:@"Game" // Event Category parameter1:[NSString stringWithFormat:@"%d", stage] // Event Parameter 1 (Stage number) parameter2:[NSString stringWithFormat:@"%d", (prevStageRubyCount-rubyCount)] // Event Parameter 2 (Number of rubies which a player uses in this stage) value1name:@"score" value1: score - prevStageScore // Event Value 1 value2name:@"duration" value2:((stageStart - [self getTimeTick]) / 1000) // Event Value 2 value3name:@"lives" value3:(prevStageLives - lives) // Event Value 3 withError:&error];
In this example, a Stage event of Game category is created with the following parameters: stage number, rubies spent, score earned, time duration, and lives lost. These parameters can be used as filters on the [Custom Events] dashboard page.
When user leaves the game, PlayGame event of Game category is reported. In PlayGame events, event parameters are determined by of the number of stages cleared and the player’s role. Then, the results (score, play time and the number of rubies consumed) are report as event parameter.
NSError *error; [Tapjoy trackEvent:@"PlayGame" // Event Name category:@"Game" // Event Category parameter1:[NSString stringWithFormat:@"%d", stage] // Event Parameter 1 (Stage number) parameter2:playerClass // Event Parameter 2 (Played character class) value1name:@"score" value1: score // Event Value 1 value2name:@"duration" value2:((gameStart - [self getTimeTick]) / 1000) // Event Value 2 value3name:@"ruby" value3:(prevGameRubyCount - rubyCount) // Event Value 3 withError:&error];