Lifecycle, session, and user

Learn what a session is, who a user is, and how Smartlook automatically follows an application's lifecycle

Once fully implemented, Smartlook automatically follows the lifecycle of the app. When the application is suspended in the background, the session recording pauses automatically. When the application resumes again, the session recording resumes.


Sessions are the main data source for your Smartlook projects. Sessions are recordings and data of users on your app. Sessions begin when you start the session in the app and finishes when one of the following occurs:

  • the session length reaches sixty minutes
  • the app is in the background for five minutes
  • the user force closes your app
  • you call Smartlook.instance.user.openNew() or Smartlook.instance.user.session.openNew() using the API.

Short interruptions of the application (incoming notifications, short calls, going to the device's settings, moving the app to the background, etc.) do not lead to a new session. Session recordings are grouped according to user. Also, what is discussed earlier is the default settings, however, other


To change this default behavior, an API method that resets the session must be called when appropriate, as described later in this document.


Smartlook records user interactions with the application in sessions. Every session has a single user. A single user can have multiple sessions.

User can be uniquely identified by a respective identifier by setting the Smartlook.instance.user.identifier property. This call associates the current user with the provided ID. If a user with the same ID already exists in one of your Smartlook projects, the session is automatically assigned to that user.

If you call the Smartlook.instance.user.identifier method again with a different user identifier, it does not create a new user, it changes the ID of the user currently associated with the session. To login a new user, use the Smartlook.instance.user.openNew() method described in the following section.

The application remembers the last user’s ID and reuses it as the default user ID with each new session (i.e., when the application is launched again on the device). This happens even when the user is not identified explicitly and ensures that when the application runs again on the same device, the sessions are grouped together.

Explicit control of users and sessions

If a device and app are shared among many users, you might want to have more control over the session and user flow. In these cases, the application should always start with a user.

To do so, call Smartlook.instance.user.openNew() before starting the recording.

When you want to start a new session, or login a new user while the app is running, you can do so by using the Smartlook.instance.user.session.openNew() method.


It is not recommended to call the user or session opening method when the application is being closed. Smartlook is busy with clean up when the application is going to the background, and calling this method may create ephemeral sessions as an unwanted consequence. If you want to force a new user or session every time the application starts, call these methods before you first start recording when the app starts.

Explicit session recording stopping and restarting

The Smartlook SDK automatically follows the application life cycle. This means that session recordings will start, stop, and restart without you needing to do anything.

However, maybe you only want to record just a small part of the application. In these cases, it is possible to stop and start recording programmatically. The Smartlook API has methods to stop and start recording, as well as a property that returns the current recording state.


Starting and stopping programmatically

If you control the session recording programmatically, the time the user spends in the rest of the application is not visible on the timeline. So, for a short interruption, such as a user entering sensitive information in a form, consider switching to a combination of rendering and event tracking modes. This way, the time the user spends incognito is visible on the timeline. For more information, see Handling sensitive data.

User properties

To further help you understand your users, you can add custom properties to the current session and user. Details can be found in the API reference for each platform.


Currently, only string values are accepted both as property keys and values.