Integration Overview

From Localytics Docs
Jump to: navigation, search

Integration is the process of putting the Localytics SDK into your application. Integration is very quick and the following guides are important for making it as successful as possible. It is also recommended to review the docs on Using the Dashboard before integrating to get a sense on how this integration will be used by the dashboard users.

Integration Steps

  1. Are you replacing your old analytics with Localytics?
  2. Create an app key
  3. Follow the basic integration guide for your platform
  4. Tag Events
  5. Follow our integration tips

Library Design Goals

The libraries were created on each platform with the following goals:

  • Be as transparent as possible. This code is running in the integrator’s application and they have a right to know what it does.
  • Maintain as consistent an API and integration model across platforms as possible.
  • Minimize integration effort. A minimum integration should take less than 15 minutes.
  • Provide enough flexibility to allow deeper integration if desired.
  • Keep the design simple so it can be adapted to fit custom requirements

Adding the Object

Once you have included the library in your project, the following function calls are used to control your session:

open(): Opens the session for data collection and records some basic user data such as country, carrier, and device model. This should be done as early in the code as possible because this is what determines the session start time. Any calls to other data collection functions such as getLocation(), tagEvent(), and close() will do nothing until the session is opened. This is a synchronous call which does not create any threads. Once it returns no cycles will be consumed by Localytics until the next Localytics API call is made.

upload(): This causes a new, low-priority thread to be created which uploads any data collected for this application including any previously stored sessions which did not get uploaded. It is best to have this call happen after the open() call so this session’s basic data gets uploaded. Once the data upload is done the thread terminates and will not have further impact on the application. This model causes each session to get uploaded in two parts. The open blob gets uploaded immediately, and the rest of the session gets uploaded the next time the app is started. It would be nice to upload the rest of the session after closing it, however the close call usually happens as the app is exiting and on most platforms it is not possible to do the upload at this time without delaying the app exit which would provide a bad user experience. In some platforms, such as iPhone and Android, it is possible to have a second upload() call when the application is destroyed because on these platforms the user is brought back to the home screen while the upload is happening so the upload will not impact the user experience.

close(): Closes the session. This should be called at the end of program execution because it determines the end time for the session. Like open, this is a synchronous call and once it completes no further work is done.

tagEvent(): (Optional) Records specific events in an opened session. Examples include ‘Button pressed’ and ‘Level Reached’. This is another synchronous call which has no impact on the application after it returns. This function also supports a list of key/value pairs of extra data to associate with a given tag.

tagScreen(): (Optional) Records screens visited in an opened session. This is another synchronous call which has no impact on the application after it returns.

setOptIn / isOptedIn: (Optional) These functions are provided to allow the developer the ability to let the user choose whether or not they are opted in to data collection. Be aware that there are significant business ramifications to enabling opt in because this will cause data skew.


As mentioned above it is possible to tag specific events in an application with a string describing the event. This is particularly useful for answering business questions and design questions such as:

  • What options do users prefer?
  • What level in a game do users tend to get to?

When doing this, it is best to use constant strings defined at compile time. This is advantageous because it avoids the risk of collecting personally identifiable information, it is more efficient, and it guarantees that the charts in the dashboard won’t have too many events to be actionable. In some cases it is acceptable to create these strings dynamically. For example, consider a game with an infinite number of levels. It might be appropriate to record an event named START_LEVEL_X (where X is the current level) every time a user reaches a new level.

To make tagging work for you, keep the following points in mind:

  • Avoid tagging events in a loop. This can cause enough data to be collected as to impact the user.
  • Tags are only useful if they are comparable across sessions. To guarantee this, make sure the string you pass to the tagEvent API is a constant.
  • If you wish to compare behaviors across versions it will be necessary to keep the tag names the same. So choose names that are not version specific.
  • If a tag exists in a code path, make sure all code paths are covered. If an event can be reached in multiple ways, and only some of the ways are tagging the event the data will be skewed.
  • Consider when to use Event Attributes while tagging. For example, determining which options are on in an settings screen a user selected is best done by having a single event which is uploaded when the user closes the screen which captures each specific option as an attribute.

Event Attributes

You can also upload event attributes, which are data points associated with your tags. For example, your article_read tag might include a section attribute.

See our introductory blog post for more information. Read the Event Attributes section in the Integration Overview in order to get the most value out of your attributes.

You can send attributes to Localytics as either strings or numbers. If you send raw numbers, Localytics will automatically bucket the numbers into equally-sized groups to be viewed in the dashboard. You can then filter numeric attribute reports by greater than, greater than or equal to, between, less than, less than or equal to, and equal to any particular value. Numeric attributes have additional metrics in the Dashboard, including Average Value, Total Value, Maximum Value, and Minimum Value. You can then break the numeric attribute out by any other built-in dimension, custom dimension, or attribute.

Numeric attribute data can have a maximum of 13 digits before the decimal and up to 5 digits after. Negative numbers are permitted, so the range available is -9,999,999,999,999.99999–9,999,999,999,999.99999.

Learn about numeric event attributes in the Dashboard.

Crashes / Exceptions

Using event attributes it is possible to collect data about exceptions and crashes within your application. All platforms provide some way to catch exceptions globally, either through an exception filter or by just wrapping the code in a try/catch. Normally this isn’t a good practice but with analytics it is helpful because you can tag an event in the exception filter with data about what the exception was, and where it occurred in the code. As a result there will be a event in your dashboard showing how many exceptions have been hit as well as what and where they were.

Instrumentation Best Practices

  • Data collection should never happen in a loop. This can cause excessive amounts of data to be stored and uploaded.
  • Only one LocalyticsSession should be used inside an application. If multiple objects, or multiple keys are used there is the risk of sessions clobbering each other.
  • All sessions should be closed. It is a good practice to have a single app exit point, and close the session there.
  • Event Tagging must not be used to collect Personally Identifiable Information. All logged information should be predefined constants.

Testing the Instrumentation

The value of the instrumentation effort is only as good as the data collected. So it is important to test the integration to ensure data is being uploaded. The service updates data in real time so the simplest thing to do is run the application in an emulator or, even better, on an actual device and verify the data is visible on the webservice. Some things to consider when testing instrumentation include:

  • Mobile applications often have multiple entry and exit points. Do all of them cause an open() and close() call to occur?
  • Is it possible to have multiple instances of the application running at the same time? If so, each instance should be creating a new object.
  • Do all of the tagged events appear?
  • Has upload been called early enough to allow the application time to upload?
  • Are all code paths instrumented? If you record an event after a code branch, should there be another event on the other branch?