Life Cycle, Session, User

Apart from the initial Smartlook setup when a new instance of an application starts, Smartlook follows the life cycle of the application automatically. When the application is suspended to the background, recording is paused automatically. When the application resumes to the frontend again, the recording resumes. There is no need to call API methods to achieve this basic behavior.

Session

Sessions roughly correspond to individual application “runs.”

This does not mean, however, that each interval when the application is onscreen is always recorded as a separate session. When an application is suspended to the background just for a short period of time (e.g., it is interrupted by an incoming call, notification, etc.), the original session continues when the application is resumed. If the application is closed for several minutes, a new session will start at the next application opening.

📘

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

User

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:

Smartlook.setUserIdentifier("sample_user_identifier")

Smartlook.setUserIdentifier("sample_user_identifier");

Smartlook.setUserIdentifier(someInternalUserID)

[Smartlook setUserIdentifier:someInternalUserID];

Smartlook.setUserIdentifier('sample_user_identifier');

Smartlook.setUserIdentifier("sample_user_identifier");

smartlook.setUserIdentifier(new SmartlookUserIdentifier("sample_user_identifier"))

Smartlook.setUserIdentifier({identifier: "sample_user_identifier"});

SmartlookUnity.Smartlook.SetUserIdentifier("sample_user_identifier");

Dictionary<string, string> props = new Dictionary<string, string>();
props["name"] = "Sample Name";
Smartlook.Analytics.SetUserIdentifier("sample_user_identifier", props);

📘

This call associates the current user with the provided ID. If a user with such an ID already exists in one of your Smartlook projects, the session is automatically assigned to that user.

🚧

When this method is called on 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 resetSession 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. This ensures that when the application runs again on the same device, the implicit users are by default associated together.

Explicit Control of Sessions and Users

In some use-cases it makes sense to explicitly control the session and users’ flow. For example, when a device with an application is shared among many users. In these cases the application should always start with a fresh session (or user). To do so, use one of the following setup options:

// to always setup with new session
val options = Smartlook.SetupOptionsBuilder(API_KEY)
        .startNewSession()
        .build()

Smartlook.setupAndStartRecording(options)

// to start with new session and user
val options = Smartlook.SetupOptionsBuilder(API_KEY)
        .startNewSessionAndUser()
        .build()
  
Smartlook.setupAndStartRecording(options)

// to always setup with new session
Smartlook.SetupOptionsBuilder builder = new Smartlook.SetupOptionsBuilder(API_KEY)
        .startNewSession();
Smartlook.setupAndStartRecording(builder.build());

// to start with new session and user
Smartlook.SetupOptionsBuilder builder = new Smartlook.SetupOptionsBuilder(API_KEY)
        .startNewSessionAndUser();
Smartlook.setupAndStartRecording(builder.build());

// to always setup with new session
Smartlook.setup(
  key: "THE_API_KEY",
  options: [.startNewSession: true]
)

// to start with new session and user
Smartlook.setup(
  key: "THE_API_KEY",
  ptions: [.startNewSessionAndUser: true]
)

// to always setup with new session
[Smartlook setupWithKey:@"THE_API_KEY"
                options:@{
                     SLSetupOptionStartNewSessionKey: @YES
                }];

// to setup with new session and user
[Smartlook setupWithKey:@THE_API_KEY
                options:@{
                     SLSetupOptionStartNewSessionAndResetUserKey: @YES
                }];

// to always setup with new session
Smartlook.setupAndStartRecording(API_KEY);
Smartlook.resetSession(false);

// to start with new session and user
Smartlook.setupAndStartRecording(API_KEY);
Smartlook.resetSession(true);

// to always setup with new session
Smartlook.setupAndStartRecording(API_KEY);
Smartlook.resetSession(false);

// to start with new session and user
Smartlook.setupAndStartRecording(API_KEY);
Smartlook.resetSession(true);

// to always setup with new session
var builder = new SmartlookSetupConfigBuilder(API_KEY)
        .startNewSession(true);

Smartlook.setupAndStartRecording(builder.build());

// to always setup with new session and user
var builder = new SmartlookSetupConfigBuilder(API_KEY)
        .startNewSessionAnduser(true);

Smartlook.setupAndStartRecording(builder.build());

// to always setup with new session
Smartlook.setupAndStartRecording({
  smartlookAPIKey: "API_KEY",
  startNewSession: true
});

// to always setup with new session and user
Smartlook.setupAndStartRecording({
  smartlookAPIKey: "API_KEY",
  startNewSessionAndUser: true
});

// to always setup with new session
SmartlookUnity.Smartlook.SetupAndStartRecording(API_KEY);
SmartlookUnity.Smartlook.ResetSession(false);

// to start with new session and user
SmartlookUnity.Smartlook.SetupAndStartRecording(API_KEY);
SmartlookUnity.Smartlook.ResetSession(true);

// to always setup with new session
Analytics.SetupOptions smartlookSetupOptions = new Analytics.SetupOptions(startNewSession: true); 
Smartlook.Analytics.SetupAndStart(API_KEY, smartlookSetupOptions);

// to start with new session and user
Analytics.SetupOptions smartlookSetupOptions = new Analytics.SetupOptions(startNewSessionAndResetUser: true);
Smartlook.Analytics.SetupAndStart(API_KEY, smartlookSetupOptions);

When it is desired to start a new session, or login a new user while the application is running, it is also possible by using a dedicated resetSession method. This method takes one parameter, then indicates whether the user identity should also be reset, or whether the new session should retain the user from the current session.

📘

It is not recommended to call this method when the application is being closed. Smartlook is busy with cleaning up when the application is going to the background, and calling this method may create ephemeral sessions as an unwanted consequence. If it is prefered that sessions do not continue with the next application launch under any circumstances, the setup resetSession options when initializing Smartlook should be used instead.

Explicit Recording Stopping and Starting

📘

Smartlook follows the application life cycle automatically

It is not necessary, under normal circumstances, to stop and restart recording programmatically.

However, in situations when it is practical to record just a small part of the application, it is still possible to stop and start recording programmatically. Smartlook API has methods to stop and start the recording, as well as a property that returns the current recording state.

🚧

When the recording is controlled programmatically this way, the time the user spends in the rest of the application is not visible on the timeline. Thus, for just a short recording interruption (e.g., when the user fills in some form full of sensitive data), consider switching to some combination of rendering and event tracking modes. This way, the time the user spends incognito is visible on the timeline. More about this can be found in Handling Sensitive Data.

Session and User Properties

In many cases, it is convenient to associate some custom properties to the current session and user. Details could be found in the respective API Reference.

📘

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