How Localytics understands data

Localytics tracks three types of metrics:

  • Session - how a user interacts with your app
  • Events - what types of actions that user takes
  • Profiles - who the user is

To understand Localytics data, it helps to start with a simple analogy. Suppose you want to track statistics for a baseball player named Joe.

You'll want to know certain game-level metrics, like the duration of games and number of games. You'll also want to know each time Joe accomplishes a particular action within each game, like a hit or a home run. This allows you to easily know total home runs or total games in which Joe had a home run.

Localytics has a similar model, but instead of evaluating games we look at app sessions and in-app actions are called events. Additionally, just as you'll want to capture context about Joe's games and actions, for example, the name of the opposing team, Localytics captures information about events and sessions called event attributes and dimensions.

Finally, certain properties about Joe aren't easily represented using just the game and action approach, for example, Joe's hometown or birthday. Localytics allows you to create a user profile to store user-level properties.

Localytics ingests a lot of different data about how your users are interacting with your app. This topic define some of the most common types of data.

Note It’s important to be aware out what is considered personal data to your users. All of the data outlined later, including events, attributes, session dimensions, or profile data, may be, depending on your unique application and privacy requirements, considered personal data.

Great care should be taken to ensure your users’ privacy rights are protected. For more information on getting your integration up to your specific privacy standards, see User privacy.

In this topic:

Session opens and session closes

Every time a user launches an application, Localytics creates a timestamped session open record identifying that a session has started. Every time a session is completed, Localytics creates a separate timestamped session closed record marking the same session as closed.

This way, Localytics can report on:

  • The number of sessions
  • The duration of a session
  • The length of time elapsing between sessions
  • The number of sessions per device, which helps us report on retention and distinguishes new and returning users

Localytics captures these session open and session close records automatically.

Events and event attributes

Events are exactly what they sound like—timestamped records that capture important actions typically performed by a user while using your app. These can be customized to collect additional information called event attributes.

Sample Event

Sample Corresponding Event Attribute
Changed settings Name of the setting that was changed
Logged in Type of log-in
Read an article Article name

Keep in mind, every event can have up to 50 attributes unique to that event.

When events occur within the boundaries of a session, Localytics will connect the observed event and all related attributes to the session during which the event took place. This allows Localytics to report on the quantity of events as well as the quantity of sessions during which a given event occurred.

The instructions for how and when to create a timestamped event are encoded into your app by your developer team using event tags. When a user travels through a particular part of the code that triggers a tagged event, Localytics creates a timestamped record.

Your developer assigns a name to this timestamped record. They can also optionally associate event-specific attributes to provide additional context and/or associate a value with the event that can be used for Lifetime Value (LTV) reporting in Localytics. For details and best practices, see "Tagging Events" in the iOS SDK or Android SDK and "Tracking Revenue" in the iOS SDK or Android SDK.

Lifetime value (LTV)

Some events have monetary value (or other measures of value) to your business. You can measure value-related events through a special event attribute called Lifetime Value (LTV).

You should determine the best measure of value for your app. For some apps (for example, eCommerce apps), monetary value is easy to determine—but other measures of value may include credits purchased, articles read, or in-app ads viewed.

Dimensions and custom dimensions

Similar to how event attributes are properties of an event, dimensions are properties of a session. Dimensions are attached to every Session Open, Session Close, and event record. They can be used to split or filter any report in Localytics and can be used to create more targeted audiences for marketing engagements. By default, Localytics automatically captures about 20 dimensions, as detailed in the following table:

Dimension Description
Day Date of usage broken down by day
Week Date of usage broken down by week
Month Date of usage broken down by month
Hour Date of usage broken down by hour
Daypart Hour in the day of usage
New vs. returning Whether this is the user's first session or not
Country Country of usage
Language Language device is set to
Device Type of device
Platform

Device platform (iOS and Android); browser (web apps)
App version Version of the application
Carrier Network carrier as resolved by IP address
OS version Version of the operating system
Jailbroken For iOS devices, whether they were jailbroken
Push enabled Whether this user has opted in to receive push messages
Push authorization

For iOS devices, if provisional push is enabled in your app, users can opt-in to receive pushes quietly, prominently, or not at all.
Location authorization

Users can opt-in to location tracking if it is available.

  • Options for iOS: "When In Use," "Always," "Denied," "Restricted," or "Not Determined."
  • Options for Android: "Always," "When In Use" and "Denied."
Acquisition source

For native app users acquired via campaigns, the channel of the campaign
Acquisition campaign

For those native app users, the specific campaign (for example, “Christmas Home Run Derby”)
Acquisition adset

For those native app users, the specific adset (for example, “East Coast Millennials”)
Acquisition ad

For those native app users, the specific ad (for example, “Red Creative”)
Monthly cohort The month in which this user had their first session
Weekly cohort The week in which this user had their first session

Custom dimensions are identical in form and function to default dimensions, except that your app can flexibly populate these. For example, you may configure your app to assign a custom dimension called "Logged In" that takes a value of "Yes" when users are logged in and "No" otherwise. You could then view which events are most popular, splitting by whether the user was logged in versus not.

Custom dimensions are useful because your app only needs to set the value once, and then that value will be associated with all subsequent sessions and events. Localytics provides up to 20 custom dimensions, depending on your subscription plan. For details and best practices, see "Setting custom dimensions" in the iOS SDK or Android SDK

Screen views

Localytics can also be used to capture the flow of screens that a user passes through during a session. Keep in mind, screen views aren’t individually timestamped, as their purpose is to power the Flows report. Screens are simply collected as an ordered set.

Screen views do not increase your app's data point consumption, but screen views cannot be used in same way as tagged events to power funnels, segments, or marketing campaigns.

Note: Because mobile apps typically offer immersive experiences with multiple paths for the user to accomplish an action, Screen view order is usually less meaningful for native mobile apps than for webpages.

If you intend to use a screen view to power anything other than the Flows report, consider additionally tagging the behavior as an event. For example, a common practice is to have a "Screen Viewed" event with an event attribute called "Screen Name." For more information, see "Tracking User Flow" in the iOS SDK or Android SDK and "Tagging Events" in the iOS SDK or Android SDK.

User profiles

So far, this topic has covered how users interact with your app—what their behaviors are. Events and sessions record what a user did. But some information about your users goes beyond their behaviors. This might be a simple trait of the user (like their hometown) or a summary of their behaviors over time (like total sessions). These are better represented as user-level properties. And that’s where profiles come in. Profiles describe who a user is.

Localytics allows your app to optionally assign an identity to a user, which we call the user's Customer ID. If your app has actively assigned a Customer ID, Localytics refers to this as a "known" profile. If your app is either not assigning a Customer ID or the user is using the app with an unknown identity (for example, not logged in), Localytics will assign a random identifier to which you can associate user-level properties.

For details and best practices, see Profiles.

Session handling

To track user engagement and retention, Localytics automatically tracks session data for your app. It’s important to understand that the definition of a session is flexible. For example, Localytics SDK can intelligently handle when a user navigates in and out of your app if they’re backgrounding and foregrounding. If we reported every foreground as a unique session, your app’s data would be likely distorted.

To account for this and prevent inflated session counts, Localytics includes a session timeout interval. The default session timeout interval is 15 seconds. This means that if a user starts a session and then backgrounds the app for more than 15 seconds, the original session will be closed and a new session will initiate if/when the user returns to the app.

Because we automatically track session lifecycle, we can derive session length, session interval, session counts, session trending, and a number of other core metrics for exploration in the Localytics dashboard.

For more information, see "Session Lifecycle" in the iOS SDK, Android SDK, Web SDK, or React Native.

For more information on how developers can customize the session timeout interval, see "Manual Integration" in the iOS SDK or Android SDK.

Device and user identification

In Localytics analytics reporting, a user is defined as a unique device. The Localytics SDK identifies unique devices by creating a proprietary device ID, which is generated using a combination of identifiers found on the device. The resulting unique device ID is attached to all event and session data; therefore, it's what we count as a user. This device ID will stick around through reinstalls—so you don’t have to worry about counting the user multiple times if they delete and reinstall your app.

Keep in mind, Localytics only becomes aware of users when a user opens a version of the app that has Localytics installed. So we won’t be able to detect any users on versions of your app before you installed Localytics.

We consider a user New during the user’s first session and Returning for all subsequent sessions. You can also optionally identify users by assigning them a customer ID. This allows you to connect observed behavioral data collected by Localytics with a user identity familiar to you.

Collecting this data might be considered personal data to your users. For more information about how to better equip your app to handle privacy, see User privacy.

You can use customer IDs to power marketing campaigns but not to count users in analytics reports. For more information, see Profiles.

Location tracking

The Localytics SDK collects available location data to power the Location report. Keep in mind, granular location data is only available under certain conditions, so some sessions will naturally have no locations assigned.

We give preference to the highest-fidelity location data available. This means GPS latitude-longitude coordinates are considered the highest-fidelity and network country is the lowest.

In order for Localytics to collect and report on latitude-longitude data, your app must first receive permissions from the user and the operating system. This information must then be configured to hand off to Localytics.

In the absence of latitude-longitude data, Localytics will look for an IP address, which is typically available if users are connected via WiFi. If neither latitude-longitude data nor an IP address is available, Localytics will report at the country-level using the network country.

Privacy and location

Depending on your unique privacy requirements, Location may be considered personal data. This means that consent might be required prior to collecting location data. Localytics expects customers to solicit consent as appropriate to their unique privacy requirements.

Collecting GPS coordinates must be configured; further, your application must obtain the appropriate permissions to access the OS GPS data.

IP addresses are not stored in any Localytics databases, but the location data generated by an IP lookup is, by default, collected and stored. This data includes country, region, state, city/metro area, if available.

For more information, see User privacy.

Analytics reports and custom dashboards

To learn more about understanding Analytics reports in Localytics,see Anatomy of an Analytics report.

To learn more about custom dashboards, see Custom dashboards.