Session Management

The mParticle platform leverages the concept of a user session, which is meant to represent a common pattern whereby a given user opens an app and interacts with it for a period of time, and then eventually moves on to another app or stops using their device. Different integrations use sessions for the similar purpose of grouping user interactions and deriving insights from these groupings. The mParticle platform translates the sessions it detects into each integrations equivalent.

Although the mParticle SDKs ship with sensible default parameters by which sessions are derived, the SDKs also provide APIs to allow developers custom session control. The first customization lever that developers have is known as the session timeout.

Session Timeout

When a user launches your app, the mParticle SDK will begin a new session. The same session is maintained for as long as your app is in the foreground and all events logged during this time will be associated with the same session. If a user navigates away, or sends your app to the background, the SDK starts a timer to expire the current session. If, however, the user brings your app back to the foreground before the session times out, the same session is continued. Otherwise the session will expire and the next time the app is used a new session will be created.

By default the session timeout is 60 seconds, but can be customized.

In iOS, if an application is allowed to continue running in the background for long periods of time, such as media playing or recording, and map based applications, the current session will not expire for as long as the media or maps operations are active. Once those activities are paused or stopped, the session timeout will start ticking and the session will expire after it times out. If, however, the activity resumes before the session times out, the session will also be resumed. For iOS, the maximum allowed session timeout is 120 seconds.

//Set the session timeout in seconds up to a max of 120
[MParticle sharedInstance].sessionTimeout = 60;

//or

[[MParticle sharedInstance] setSessionTimeout:60];
//Set the session timeout in seconds up to a max of 120
MParticle.sharedInstance().sessionTimeout = 60

Session Attributes

You can associate attributes with a session. When the user’s session times out (when they navigate away from your app for a period of time), these attributes will be reset.

You can also increment numeric session attributes by a certain amount. For example, if a user is listening to music on her device, you may choose to increment the song count by 1 every time a new song starts playing.

//A session attribute value can be an NSString or NSNumber
[[MParticle sharedInstance] setSessionAttribute:@"level_achieved"
                                          value:@11];

[[MParticle sharedInstance] incrementSessionAttribute:@"song_count"
                                              byValue:@1];
MParticle.sharedInstance().setSessionAttribute("level_achieved", value: 11)

MParticle.sharedInstance().setSessionAttribute("song_count", value: 1)

Opt-Out

The mParticle SDKs support the ability to selectively opt-out users from all tracking features. When opt-out is enabled, no event data will be communicated from the SDKs.

Enable opt-out either via your app’s configuration in the mParticle console, or by calling the following API method:

[MParticle sharedInstance].optOut = YES;
MParticle.sharedInstance().optOut = true

Session Lifetime Notifications

You can register to receive notifications from the mParticle SDK when a new session begins or when the current session is about to end. The registration is done in the NSNotificationCenter using the mParticleSessionDidBeginNotification and mParticleSessionDidEndNotification name constants. The notifications contain a userInfo dictionary containing the session id in question. You can access its value by using the mParticleSessionId key constant.

- (void)registerForSessionNotifications {
    NSNotificationCenter *notificationCenter = [NSNotificationCenter defaultCenter];

    [notificationCenter addObserver:self
                           selector:@selector(handleSessionDidBegin:)
                               name:mParticleSessionDidBeginNotification
                             object:nil];

    [notificationCenter addObserver:self
                           selector:@selector(handleSessionDidEnd:)
                               name:mParticleSessionDidEndNotification
                             object:nil];
}

- (void)handleSessionDidBegin:(NSNotification *)notification {
    NSDictionary *userInfo = [notification userInfo];
    NSLog(@"New session has begun. Id: %@", userInfo[mParticleSessionId]);
}

- (void)handleSessionDidEnd:(NSNotification *)notification {
    NSDictionary *userInfo = [notification userInfo];
    NSLog(@"Session id %@ will end.", userInfo[mParticleSessionId]);
}
func registerForSessionNotifications() -> Void {
    let notificationCenter = NotificationCenter.default

    notificationCenter.addObserver(self,
                                   selector: #selector(self.handleSessionDidBegin(notification:)),
        name: NSNotification.Name.mParticleSessionDidBegin,
        object: nil)
    notificationCenter.addObserver(self,
                                   selector: #selector(self.handleSessionDidEnd(notification:)),
                                   name: NSNotification.Name.mParticleSessionDidEnd,
                                   object: nil)
}

@objc func handleSessionDidBegin(notification: NSNotification) -> Void {
    if let sessionID = notification.userInfo?[mParticleSessionId] {
        NSLog("New session has begun. Id: %@", sessionID)
    }
}

@objc func handleSessionDidEnd(notification: NSNotification) -> Void {
    if let sessionID = notification.userInfo?[mParticleSessionId] {
        NSLog("Session id %@ will end. Id: %@", sessionID)
    }
}