Localytics: The Importance of customer_id

Posted by Nick Servidio on May 23, 2016 9:56:11 AM

Localytics is a marketing double threat. You can use it to track important information about how your users behave and who your users are, and it enables you to send push notifications that target users based on the data that you have collected!

There are many resources that can help you integrate Localytics into your app— the Localytics documentation is a good place to start. However, as you begin to track events and profile data, there are several questions to consider: How you will continue tracking events for a user when they get a new phone? How will you associate events sent from someone’s iPad and iPhone with a single user? What is the most efficient way to send push notifications through Localytics?

All of these questions can be answered with one of the most important terms in the Localytics lexicon: customer_id. Let’s take a look at all of the benefits of utilizing customer_id when integrating Localytics.

What is customer_id?

Customer_id is a unique identifier for each user in your Localytics database. Localytics can track information about a user in the form of a Localytics profile. A user can have a different Localytics profile for each app in your organization. If your company makes a game, some of the profile attributes could be High_Score, or Last_Level_Completed. These attributes would not apply if your company also made a banking app. Some common profile attributes are: Last_Login_Date and Purchase_Dates.

If you are new to Localytics, you might assume that each user profile contains a customer_id. However, the hierarchy of Localytics profile data can actually be visualized like this:

customer_id :

profile1 :

attribute_key : attribute_value

attribute_key : attribute_value

profile2 :

attribute_key : attribute_value

attribute_key : attribute_value

profile3 :

attribute_key : attribute_value

attribute_key : attribute_value

Each user has one customer_id associated with one or more profiles. There is also a customer_id associated with every event tagged in Localytics. The latter is a slightly strange concept that is not explicitly stated in the documentation. While the docs do provide for a way to attach attributes to an event, they don’t make it clear that customer_id is silently associated with each event.

A strange side effect occurs if you do not set a customer_id for a user in your mobile app. Try tagging a few events in a freshly created Localytics app and check the Localytics profile page after the events show up in the events page. You will eventually see Total Profiles = 1 and Known Profiles = 0% under Application Statistics. If you press the Actions button on the ride side of the screen and select Export Customer IDs, a CSV file containing the anonymous ID will be emailed to you. Anonymous customer_ids look like this: 87ABF476-F0BF-43D8-9ADB-A492F8CD8C34.

Besides cluttering up your Localytics database, anonymous customer_ids have other implications that will be discussed later.

Common Use Cases Involving customer_id

So what’s the big deal? My company just makes one app, so I don’t need customer_id. I’ll just use the anonymous customer_id generated by Localytics. It turns out that customer_id really comes into play when trying to reach customers through a Localytics push campaign.

In order to send a push campaign in Localytics, you need to set up an audience that the campaign will target. This audience can include everyone who uses your app, or can be filtered by either behavior (events) or profile conditions. A typical behavior filter looks like this:


Let’s say you have an app that tags a Purchase_Event every time a user buys something. At some point you want to send a push notification to all users who have recorded 10 or more Purchase_Events. Also, your app runs on both iPhone and iPad, so you want to aggregate the purchases from both types of devices. A purchase on an iPad is certainly just as valuable as a purchase on an iPhone! In order to do this, you have specified that you want to track the behavior across a person’s devices.

Suppose a customer named Nick has both the iPad and iPhone version of your app. Nick has recorded five purchases on his iPhone and five on his iPad. If you are simply tracking purchase events, Nick will not receive the push notification. What a shame, your faithful customer will not get to view the marketing material specifically targeted at him!

A similar scenario exists if another user, Deborah, records 5 purchases on her iPhone 5s then upgrades her phone and records five more purchases on her iPhone 6s plus.

This is exactly where cutomer_id comes into play. By setting a customer_id for a user at login, all events that that user records will be associated with a known customer_id. Thus the five events recorded on one device and the five events recorded on another will be attributed to the same user!

To be more specific, the steps to manage customer_id are as as follows:

  1. A user creates an account for your app via a RESTful API.
  2. The response of that API call contains a unique identifier for the user that exists on your app’s backend. Let’s call it user_unique_id.
  3. Assign customer_id to equal user_unique_id.
  4. If the user logs out, set the customer_id to nil.
  5. When the user logs in again via a RESTful API call, have that call’s response also contain the user_unique_id.
  6. On a successful login, again assign customer_id to be equal to user_unique_id.

This balanced system accomplishes two things. First, it ensures that a customer_id is always assigned to the user who is logged in. Second, it allows you to track accurate analytics if multiple users are using an app on the same device. Though this is an edge case, it is nice to know that Nick’s events are not being associated with Deborah’s customer_id if Nick is using Deborah’s phone.

This procedure also allows a user to get a new device and still be treated as the same user. When Deborah logs in on her new iPhone 6s plus, the customer_id will be set to her unique identifier on the app’s backend, which hasn’t changed. This will prevent her from being considered a new user in the Localytics system.


Do you recall those anonymous customer_ids mentioned earlier? Remember, when you tag events prior to assigning a customer_id, those events will be associated with an anonymous customer_id. What types of events could occur before assigning a customer_id? Any pre-sign up event such as sign-up failure, login failure, reset password, etc. Thus, these events are difficult to track. If your client or project manager is demanding that you track these events then you can inform them that the task is not trivial.

If you really want to track pre-sign-up events, then you could try something like this:

  1. Generate your user’s user_unique_id on the client side.
  2. Assign user_unique_id to customer_id.
  3. Tag events.
  4. Set the user’s user_unique_id on your app’s backend during your RESTful sign up call.

Events are often used to identify pain points in an app’s flow. It is my opinion that your app’s sign-up process should never be so complicated that it requires analytics.

Using the Localytics Push API

There is another serious benefit you get when using customer_id that I only discovered through talking to some of Localytics’ support engineers. There is a certain amount of latency associated with sending push notifications through the Localytics web portal. The Localytics database needs to use the filter criteria contained in the audience that you provided to look up the people who should receive notifications. Though Localytics is hesitant put a number on the duration for this lookup, it can be on the order of 15 minutes. This doesn’t seem that bad. Users will get the notification when they get it, right?

In certain situations, 15 minutes is clearly unacceptable. Imagine if you were riding in your Uber and 15 minutes later you received a push notification: “Your Uber is arriving now.” Not very helpful.

For time-sensitive push notifications, developers can turn to the Localytics Push API. Using this API, you can specify a group of customer_ids that you want to push to. You will have to query your own database to identify which customers need a notification, but this will most likely take less than 15 minutes. On the Localytics end there is no wait and no delay. Your messages will be instantaneously sent to those users.

Recapping the Benefits of customer_id

To recap, it is important to utilize customer_id when integrating Localytics. You can use customer_id to continue tracking events for a user when they get a new phone. It can also be used to associate events sent from someone’s iPad and iPhone with a single user. Finally, using a set of customer_ids and the Localytics push API is the most efficient way to send push notifications with Localytics.

Sending Pushes Across a Person’s Devices

When a user has multiple devices using the same customer_id, any events logged by those devices will be associated with that customer_id. Let’s say Deborah, who has a valid customer_id, tags 5 Purchase_Event’s with her iPhone and 5 Purchase_Event’s with her iPad. If you define a push campaign audience as people who performed at least 10 Purchase_Event’s “across a person’s devices,” you might assume that both the iPad and the iPhone will receive a push notification when the campaign is finally sent.

In reality, the user will only receive a push notification on the last device on which she opened your app. This is usually satisfactory. However, I think it would be nice for Localytics to simply send a push notification to every one of a user’s qualified devices, or at least provide a configurable setting. Remember, if customer_id is not set, then NO devices will receive a notification.


Topics: Development, iOS, Localytics