| For Developers / Integrate your app | |
Once you have included the library in your project, these 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.