A session starts when you call the Apsalar startSession method. Every time you hit an instrumented event (i.e., communicate with Apsalar) we know the session is alive. In addition, there is a heartbeat mechanism in the SDK that lets Apsalar know if your session is still alive even if a user is not hitting events. Every time a heartbeat event occurs, the session length is extended. In general, this continues until the application is explicitly terminated and the session truly ends. The next time the user starts the app, it will be counted as a new session and the cycle repeats. (Note: if your app goes into the background and returns to the foreground later, the heartbeat mechanism will continue and the length will include the time in the background. For instance, if a user starts your app and uses it for 3 minutes, goes into the background for 3 days, and then brings the app into the foreground, the session length will be 3 days and 3 minutes.)
If you want more control over the recording of session counts and length, you can use the endSession and reStartSession API calls. The following describes some examples of how to handle this, however, you must make your own decisions based upon your application and your analytic needs.
In order to end a session prior to explicitly ending the application, place
[Apsalar endSession]; into the appropriate method in your AppDelegate file. For example, place it into applicationWillTerminate.
If you want to end a session when your app goes into background and start a new session when the app becomes active or comes to the foreground, then place
[Apsalar endSession]; into applicationDidEnterBackground in your AppDelegate file. To start a new session when the app becomes active (comes into the foreground), then place
[Apsalar reStartSession:@"yourAPIKey" withKey:@"yourSecret"]; into applicationWillEnterForeground in your AppDelegate file. So, if a user uses your app for 3 minutes, goes into the background, and then returns to the foreground 3 days later, the first session will be counted as 3 minutes and a second session will be started.
Refer to the diagram below when determining where to put your startSession, endSession and reStartSession calls. Be careful to make sure that you don’t place reStartSession in such a place that it will always be executed immediately following a startSession or reStartSession call, as this could result in double-counting of sessions, with the first session ending almost as soon as it starts.