Start tracking with Leanplum

Introduction to sending custom data points in Leanplum including events, states, and user attributes

By default, the Leanplum SDK will automatically capture all session and limited amounts of other user data for you. This includes when a user starts or ends a session and data such as the location or device.

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

During your activation period, deciding what you want to track is one of the most important first steps in integrating with Leanplum. The foundation of a great data taxonomy is important. The implementation team will help determine this. In the meantime, learn more below on each data type and examples how to implement each.


Data Constraints

Before creating your data taxonomy on what to send to Leanplum, make sure to review our API Limits policy to see the number of events, states, parameters, and user attributes you can track with Leanplum.

Naming rules for events, states, user attributes, and parameters

  • Length must be greater than 0 and fewer than 140 characters.
  • Must not start with a period (.) or hyphen (-).
  • Must not end with a forward slash (/).
  • Must not contain commas (,), vertical pipes (|), double quotes ("), tabs, newlines, or - return characters.
  • Must not be numeric.
  • Must not use the same name for different events and states, e.g. you should not name a state cart and an event cart.


An event is anything that can occur in your app. Events include clicking on a link, sharing, purchasing, or killing enemies, etc. All the events you track with Leanplum are automatically timestamped to capture when they occur. As you sit down and determine your data taxonomy in Leanplum, there are a few things to consider.

Identify the core milestones in your app

As you are deciding which events to send to Leanplum, we recommend focusing on the core user activities your app is trying to drive and sending those and any related activities as events. For example, you might want to track multiple events along your user onboarding and conversion/purchase flows, such as an Add to cart event or an Onboarding complete event. Its important to track each important event along that user path so you can accurately track the user along that journey and analyze the best way to engage with them.

Pick unique event names for distinct actions

When choosing an event name, you want to ensure that each event has a distinct name so you can keep track the actions your users are taking.

For example, the following list each would be considered separate events:

  • Login
  • Register
  • Add To Cart
  • Rate Item
  • Checkout

NOTE: As a general best practice, each step in a funnel should have its own event name.

Use parameters to differentiate similar actions

Within Leanplum, there is a data constraint that allows for only 500 events in each of your Leanplum apps. By sending parameters with each of your events, you will reduce the number of unique events you need to send to Leanplum and will allow you to track in greater depth your users behavior.

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. Parameters are great for adding contextual information about an event or state. For example, a parameter can be the price for an item purchased or the destination city for a flight that was booked. This piece of data can then allow you to personalize message content and to run reports for deeper analysis on specific groups of users.


Parameter Types

Parameters can either be numeric (for example, “number of items ordered”) or a simple string. If you send a numeric parameter, the Leanplum analytics tool will be able to compute averages and sums for that parameter.

As events are tracked, below are examples of how we would recommend implementing events vs what we would not recommend

Recommended (send parameters)

Leanplum.track("Open App", withParameters:["app_name": "Test Bank"])
Leanplum.track("Open App", withParameters:["app_name": "Blink Books"])
// OR better yet
Leanplum.track("Open App", withParameters:["app_name": "Blink TV", "category": "Featured", "page": "Entertainment"])

Events with similar name but different app (not recommended)

Leanplum.track("Open App Test Bank")
Leanplum.track("Open App Blink Books")


A state is a time based event that allows you to track the particular screen or area of your app a user enters. For example, states allow you to track a particular level a user plays and how longs it take for them to finish the level. Other examples include the ability to track the length of time a user takes to complete your onboarding series, watching a video, or browsing your in-app store. With each state you implement, Leanplum will automatically track the time and a duration, from when one state begins to when the previous one ends.

Identify the core milestones in your app

Within Leanplum, there is an option for your dev team to automatically track each screen in your app as states. However, as with events, for the most focused data points we would recommend focusing the tracking of the user state to each key screen in each user path of your app that you'd like to monitor. This will allow you to be strategic in your analysis and really hone in on specific user experiences you are prioritizing.

Use parameters to provide greater depth

As with events, in Leanplum there is a data constraint that allows for only 500 states in each of your Leanplum apps. The sending of parameters is also supported when you are tracking the state of the user. Doing so will reduce the number of unique states you need to send to Leanplum and will allow you to track in greater depth your users behavior.

As with events, 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. Parameters are great for adding contextual information about an event or state.


Use Different Names when tracking States v Events

When tracking events and states, it is best practice to use names that are descriptive and unique to each event and state. Have the same name for a state and event can cause issues in the Leanplum dashboard and you could target an event when you meant to target a state.

User Attributes

A user attribute is any piece of data that describes characteristics about your user. These are custom attributes you can you collect on a user with the Leanplum SDK. User attributes are intended for you to store user characteristics that are consistent across each session of user engagement.

User attributes can consist of any data point you want to attribute to your user base. Examples of user attributes may include:

  • Age
  • Gender
  • Number of friends
  • User interests
  • VIP Tier

As you are thinking about your data taxonomy and which attributes are most important to track in Leanplum, there are a few constraints to consider:

  • You can have up to 200 attributes per app
  • Attribute names must be strings, and values must be strings or numbers
  • Attribute values will be consistent across user sessions for all events and states