In order to get started with Localytics, you will need to make a decision how to integrate: automatically or manually. Most apps can rely on automatic integration, but apps that need more explicit control over their session lifecycle can use manual integration.
Do I need to do a manual integration?
Most apps should do an automatic integration. Manual integration should only be needed if your app has special requirements around the session and AppDelegate or Activity lifecycle that mean you can't rely on our default handling, or where you want more precise control over what results in a session being started or resumed, and what causes a session to begin its timeout period.
On Android, you may want to do a manual integration if your app has Activity classes that shouldn't count towards starting or resuming a session - for instance, a messaging app with activities shown as overlays when the app is backgrounded. On iOS, you'll need to do a manual integration if you're using a third-party library that doesn't support using a proxied AppDelegate (due to overly strict type checking, for instance).
Automatic Integration
Using automatic integration the Localytics SDK will track session open and closing by listening to app background and foreground behavior.
On iOS this is achieved by acting as a proxy to the AppDelegate. In this scenario, any AppDelegate that is defined by the user will still exist and receive all the normal callbacks, but in addition the Localytics AppDelegate will also be able to receive them.
Specifically the AppDelegate will listen to the following calls for the following purposes:
applicationWillEnterForegroundandapplicationDidBecomeActive- The Localytics SDK will open a session and upload any data on the device to the Localytics backend.applicationDidEnterBackground- The Localytics SDK will close an open session and attempt to upload any data on the device to the Localytics backend (This upload may fail as the OS can kill the app before completion). Additionally, the Localytics SDK will dismiss any visible In App messages.didReceiveRemoteNotification:anddidReceiveRemoteNotification:fetchCompletionHandler:- The Localytics SDK will handle the tagging of the Localytics Push Received and Localytics Push Opened events, and navigate to any relevant deeplinks.didReceiveLocalNotification:- The Localytics SDK will handle the tagging of the Localytics Places Push Opened event.didRegisterForRemoteNotificationsWithDeviceToken:The Localytics SDK will handle the collection of device push tokens so the user can be targeted by push messaging.
On Android this is achieved by registering as an Application.ActivityLifecycleCallbacks. This allows the app to be informed of Activity events such as foregrounding and backgrounding by keeping track of the number of foregrounded and backgrounded activity. Specifically the Localytics SDK uses the following methods:
onActivityStarted- If the Localytics SDK recognizes this as the first activity (and thus an app foreground) it will open a session and upload any data on the device to the Localytics backendonActivityResumed- The Localytics SDK will check the incoming activity to see if it is attempting to trigger test mode, or if it came from a push notification. If it is, then it will trigger the correct behavior. Additionally, it will make sure that the SDK knows that this is the current activity to connect to for In App messaging.onActivityPaused- The Localytics SDK will dismiss any currently visible In App messages.onActivityStopped- If the Localytics SDK recognizes this as the last activity (and thus an app background) it will close an open session and attempt to upload any data on the device to the Localytics backend (This upload may fail as the OS can kill the app before completion).
Manual Integration
Our alternative initialization docs for iOS and Android cover doing a manual integration; the steps there result in an integration that tracks data with the same lifecycle as the standard automatic integration.
For more information on sessions, continue your reading here.