HomeUser GuideDeveloper GuideChangelog
Developer Guide

Tracking User Behavior

The Leanplum SDK will automatically log session and other limited amounts of user data for you. This includes when a user starts or ends a session and such data like their location or device.

Leanplum is also able to track more detailed data points you collect on a user. This may include points such as ad revenue, user preferences or how long it takes a users to play each level of your game. Each of these custom behavior you capture can be sent as an event or state.

Events can be used to target users for certain messages, tests, or other content changes. Below you will find more details on the the type of behavior you are wanting to track in Leanplum.

Tracking an Event

An event is anything that can occur in your app. Events include actions like clicking a link, sharing an update, purchasing a subscription or other in-app asset, killing enemies etc. All events are timestamped according to when they occur. Thus, it is not advisable to log too many events, as each one will have to be sent to our server.

Add the following lines of code to track an event. You can place the Leanplum track call anywhere as long as it executes after start (examples below):

// This example tracks the event "Launch" 
import UIKit
import Foundation

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

    var window: UIWindow?

    func application(application: UIApplication!, didFinishLaunchingWithOptions launchOptions: NSDictionary!) -> Bool {
        ...
        Leanplum.onVariablesChanged({
            Leanplum.track(event: "Launch")
        })
        ...
        return true
    }
...

// This example tracks the event "Launch" after defining the variable "welcomeMessage". 
#import <Leanplum/Leanplum.h>

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{ ...
  [Leanplum onVariablesChanged:^{
    NSLog(@"%@", welcomeMessage.stringValue);
    [Leanplum track:@"Launch"];
  }];
  return YES;
}
...
@end

// This example tracks the event "Launch" after defining the variable "welcomeMessage".
import com.leanplum.annotations.Variable;
import com.leanplum.annotations.Parser;

public class ApplicationClass extends Application {

  @Variable public static String welcomeMessage = "Welcome to Leanplum!";

  @Override
  public void onCreate() {
    ...
    Parser.parseVariables(this);

    Leanplum.addVariablesChangedHandler(new VariablesChangedCallback() {
      @Override
      public void variablesChanged() {
        Log.i("Test", welcomeMessage);
        Leanplum.track("Launch");
      }
    });
    ...

    Leanplum.start();
  }
}

// This example tracks the event "Launch".
using LeanplumSDK;

public class LeanplumWrapper : MonoBehaviour
{   ...
    void Start()
    {   ...
      Leanplum.Track("Launch");
    }
}

// Tracks view cart event for a user.
Leanplum.track("View Cart");

// Tracks view cart event for a user.
Leanplum.track("View Cart");

// User killed an enemy.
Leanplum.track(event: "Kills")

// User completed a challenge.
Leanplum.track(event: "Score", value: 1)
Leanplum.track(event: "Challenges")

// User liked a post.
Leanplum.track(event: "Likes", info: post.id)

// Or, you can supply a dictionary with up to 200 numerical or string parameters.
Leanplum.track(event: "Likes", params:["post":post.id])

// User killed an enemy.
[Leanplum track:@"Kills"];

// User completed a challenge.
[Leanplum track:@"Score" withValue:@1];
[Leanplum track:@"Challenges"];

// User liked a post.
[Leanplum track:@"Likes" withInfo:@"Post Info"];

// Or, you can supply a dictionary with up to 200 numerical or string parameters.
[Leanplum track:@"Likes" withParameters:@{@"post":post.id}];

// User killed an enemy.
Leanplum.track("Kills");

// User completed a challenge.
Leanplum.track("Score", challengeValue);
Leanplum.track("Challenges");

// User liked a post.
Leanplum.track("Likes", post.id());

// Or, you can supply a dictionary with up to 200 numerical or string parameters.
Map<String, Object> params = new HashMap<String, Object>();
params.put("post", post.id());
Leanplum.track("Likes", params);

// User killed an enemy.
Leanplum.Track("Kills");

// User completed a challenge.
Leanplum.Track("Score", challengeValue);
Leanplum.Track("Challenges");

// User liked a post.
Leanplum.Track("Likes", post.id());

// Or, you can supply a dictionary with up to 200 numerical or string parameters.
Dictionary<string, object> params = new Dictionary<string, object>();
params.Add("post", post.id());
Leanplum.Track("Likes", params);

// You can also pass a value and parameters.
// User made a purchase. Use Leanplum.PURCHASE_EVENT_NAME to indicate a purchase.
Dictionary<string, object> item = new Dictionary<string, object>();
params.Add("itemCategory", "Apparel");
Leanplum.Track(Leanplum.PURCHASE_EVENT_NAME, 19.99, item);

// Tracks view cart event for a user.
Leanplum.track("View Cart");

// Tracks view cart event with numeric event parameter, itemsInCart.
Leanplum.track("View Cart", {itemsInCart: 4});

// Tracks an event with a value and two event parameters.
Leanplum.track("Purchase", 4.99, {itemCategory: 'Apparel', itemName: 'Shoes'});

// Tracks view cart event for a user.
Leanplum.track('View Cart');

// Tracks view cart event with numeric event parameter, itemsInCart.
Leanplum.track('View Cart', {itemsInCart: 4});

// Tracks an event with a value and two event parameters.
Leanplum.track('Purchase', {itemCategory: 'Apparel', itemName: 'Shoes'});

🚧

500 event limit and event naming limits

Note that there is a limit of 500 events per app in Leanplum. Since events are not unlimited, it's best to track more general events, and use parameters to track specific information associated with the event.

For example, you should use a simple name for a purchase event, such as LP_PURCHASE_EVENT and pass a purchase ID or item ID as a parameter. Review our Naming rules for events, states, and parameters for a full list of limitations.

Advancing to a State

A state is a time-based event in Leanplum that allows you to track . For example, some states can include being in a particular level, watching a video, or browsing an in-app store.

All states have a time and a duration. The duration is set automatically — when one state begins, the previous one ends.

This example is called when the user advances to the next level.

//Example state call
Leanplum.advance(state: "Level", info: level.name)


//The pause state function is useful if you need to pause in the middle of use. 
//EX: Game with 'pause' mode.  We automatically handle this when the app is backgrounded
Leanplum.pauseState()
Leanplum.resumeState()


//They will cause the user to leave current state and not enter another one
Leanplum.advance(state:nil)

//Example state call
[Leanplum advanceTo:@"Level" withInfo:level.name];

//The pause state function is useful if you need to pause in the middle of use. 
//EX: Game with 'pause' mode.  We automatically handle this when the app is backgrounded
[Leanplum pauseState];
[Leanplum resumeState];

//They will cause the user to leave current state and not enter another one
[Leanplum advanceTo:nil];

//Example state call
Leanplum.advanceTo("Level", level.name());

//The pause state function is useful if you need to pause in the middle of use. 
//Ex with 'pause' mode.  We automatically handle this when the app is backgrounded
Leanplum.pauseState();
Leanplum.resumeState();

//They will cause the user to leave current state and not enter another one
Leanplum.advanceTo(null);

//Example state call
Leanplum.AdvanceTo("Level", level.Name);

//The pause state function is useful if you need to pause in the middle of use. 
//EX: Game with 'pause' mode.  We automatically handle this when the app is backgrounded
Leanplum.PauseState();
Leanplum.ResumeState();

//They will cause the user to leave current state and not enter another one
Leanplum.AdvanceTo(null);

// example state call
Leanplum.advanceTo("Cart", {numItems: 2});

//The pause state function is useful if you need to pause in the middle of use. 
//EX: Game with 'pause' mode.  We automatically handle this when the app is backgrounded
Leanplum.pauseState();
Leanplum.resumeState();

//They will cause the user to leave current state and not enter another one
Leanplum.advanceTo(null);

// example state call
Leanplum.advanceTo("Cart", "info", {numItems: 2});

//The pause state function is useful if you need to pause in the middle of use. 
//EX: Game with 'pause' mode.  We automatically handle this when the app is backgrounded
Leanplum.pauseState();
Leanplum.resumeState();

//They will cause the user to leave current state and not enter another one
Leanplum.advanceTo(null);

Parameter

A parameter is a piece of data associated with an event or state. You can supply parameters as a dictionary along with events and states. Here are some reports you can run with parameters:

  • Filter reports by event parameter values
  • Group metrics by distinct event parameter values (creates a bar graph + table). Example: Show me my top purchased items.
  • Group metrics by ranges of event parameter values (creates a histogram + table). Example: Show me the distribution of purchase prices. Example: Show me the distribution of points scored.
  • Create custom metrics for numeric parameter values, like totals and averages. Example: For a purchase event, track the average revenue and the amount of currency bought per user.

📘

Parameter limitations

Parameters and Event Values are not available in Developer activity analytics, but you can verify your parameters are being tracked correctly in the Debugger console.

Also, with the out-of-box Leanplum SDK, parameters cannot be used as a criteria to target users. For example, if you have an event "Favorite_Color_Selected" with parameters for each color, you would not be able to target users who completed the Favorite color select event and chose the color blue.

Events and states accumulate over time, and we send events in batches periodically to minimize network usage and maximize battery life.