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 upon the next heartbeat or event. 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
Apsalar.restartSession(Activity activity,String APIKey, String secret)
; methods. Apsalar.endSession will timestamp the end of the current session as long as the heartbeat is disabled (see the Optional Android 6.X.X Features section in our documentation about Integrating the Android SDK), but will not end it. The session will only be ended when a new session is started, with the timestamp from Apsalar.endSession() marking the end of the session. Apsalar.restartSession will start a new session and end the current session.
Refer to the following diagram (from http://developer.android.com/guide/topics/fundamentals/activities.html) when determining where to put your Apsalar.endSession and Apsalar.restartSession calls. Here are a couple of recommended scenarios. You can use different scenarios as appropriate for your specific needs.
- If you simply want to count a session as the time from the start of the main activity until the time that the activity is shut down or the process is killed, then place the Apsalar.startSession call into your onCreate() method as described above. The session time will also include the time while the application is in the background. So, if a user uses your app for 3 minutes, goes into the background either through an onPause() or an onStop() and then returns to the foreground 2 hours later through an onResume() or onRestart(), then the session time would be extended to the overall time since the start of the session until an event was recorded or a heartbeat event occurred.
- If you only want to record the time that the activity is running in the foreground you can place a call to Apsalar.restartSession
CAUTION: Every time you use Apsalar.restartSession, it will start a new session. So, if you place it into onCreate(), onStart(), and onResume() it will start 3 sessions sequentially and quickly end the first two. This will inflate your session count and give incorrect session data.