Lifecycle

Sessions contain information about the app's current lifecycle, such as the device information, the application install or upgrade information, the session start and pause times, the number of application launches, and additional context data that is provided by the developer through the lifecycleStart API. Session data is persisted, so it is available across application launches.

Add the Lifecycle extension to your app

Include Lifecycle extension as an app dependency

Add MobileCore and Lifecycle extensions as dependencies to your project.

Android Kotlin

Add the required dependencies to your project by including them in the app's Gradle file.

implementation(platform("com.adobe.marketing.mobile:sdk-bom:3.+"))
implementation("com.adobe.marketing.mobile:core")
implementation("com.adobe.marketing.mobile:lifecycle")

data-variant=warning

data-slots=text

Android Groovy

Add the required dependencies to your project by including them in the app's Gradle file.

implementation platform('com.adobe.marketing.mobile:sdk-bom:3.+')
implementation 'com.adobe.marketing.mobile:core'
implementation 'com.adobe.marketing.mobile:lifecycle'

data-variant=warning

data-slots=text

iOS CocoaPods

Add the required dependencies to your project using CocoaPods. Add following pods in your Podfile:

use_frameworks!

target 'YourTargetApp' do
  pod 'AEPCore', '~> 5.0'
  pod 'AEPLifecycle', '~> 5.0'
end

Initialize Adobe Experience Platform SDK with Lifecycle Extension

Next, initialize the SDK by registering all the solution extensions that have been added as dependencies to your project with Mobile Core. For detailed instructions, refer to the initialization section of the getting started page.

Using the MobileCore.initialize API to initialize the Adobe Experience Platform Mobile SDK simplifies the process by automatically registering solution extensions and enabling lifecycle tracking.

Android Kotlin

data-variant=warning

data-slots=text

import com.adobe.marketing.mobile.LoggingMode
import com.adobe.marketing.mobile.MobileCore
...
import android.app.Application
...

class MainApp : Application() {
  override fun onCreate() {
    super.onCreate()
    MobileCore.setLogLevel(LoggingMode.DEBUG)
    MobileCore.initialize(this, "ENVIRONMENT_ID")
  }
}

Android Java

data-variant=warning

data-slots=text

import com.adobe.marketing.mobile.LoggingMode;
import com.adobe.marketing.mobile.MobileCore;
...
import android.app.Application;
...
public class MainApp extends Application {
  @Override
  public void onCreate(){
    super.onCreate();
    MobileCore.setLogLevel(LoggingMode.DEBUG);
    MobileCore.initialize(this, "ENVIRONMENT_ID");
  }
}

iOS Swift

data-variant=warning

data-slots=text

// AppDelegate.swift
import AEPCore
import AEPServices
...

final class AppDelegate: NSObject, UIApplicationDelegate {
  func application(_: UIApplication, didFinishLaunchingWithOptions _: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
    MobileCore.setLogLevel(.debug)
    MobileCore.initialize(appId: "ENVIRONMENT_ID")
    ...
  }
}

iOS Objective-C

data-variant=warning

data-slots=text

// AppDelegate.m
#import "AppDelegate.h"
@import AEPCore;
@import AEPServices;
...
@implementation AppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  [AEPMobileCore setLogLevel: AEPLogLevelDebug];  
  [AEPMobileCore initializeWithAppId:@"ENVIRONMENT_ID" completion:^{
      NSLog(@"AEP Mobile SDK is initialized");
  }];
  ...
  return YES;
}
@end

Add Lifecycle start and pause calls

data-variant=info

data-slots=text

You can start collecting Lifecycle information at any time in your app, but you should start as soon as your app enters the foreground. This allows Lifecycle metrics to be correctly attributed to all of your users' activities for their current session.

You should pause Lifecycle collection when the user stops using your app. The best time to do this is usually when your app has entered the background.

Lifecycle on iOS

Start Lifecycle data collection on launch

Start Lifecycle data collection by calling lifecycleStart(_:) from within the callback of the MobileCore.registerExtensions(_:) method in your app's application(_:didFinishLaunchingWithOptions:) delegate method.

If your iOS application supports background capabilities, your application(_:didFinishLaunchingWithOptions:) method might be called when iOS launches your app in the background. If you do not want background launches to count towards your lifecycle metrics, then lifecycleStart(_:) should only be called when the application state is not equal to UIApplicationStateBackground.

iOS Swift

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    let appState = application.applicationState
    MobileCore.registerExtensions([Lifecycle.self, ...], {
        if appState != .background {
        // only start lifecycle if the application is not in the background
        MobileCore.lifecycleStart(additionalContextData: nil)
        }
    }
}

iOS Objective-C

- (BOOL) application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    const UIApplicationState appState = application.applicationState;
    [AEPMobileCore registerExtensions:@[AEPMobileLifecycle.class, ...] completion:^{
    // only start lifecycle if the application is not in the background
    if (appState != UIApplicationStateBackground) {
        [AEPMobileCore lifecycleStart:nil];
    }
    }];
}

Start and Pause Lifecycle data collection from iOS lifecycle delegate

When your app is resuming from the background state, call lifecycleStart(_:) from the appropriate delegate object's "will enter foreground" method. When your app enters the background state, call lifecyclePause() from the appropriate delegate object's "did enter background" method.

• For a scene-based UI, call the Lifecycle APIs from the UISceneDelegate's sceneWillEnterForeground(_:) and sceneDidEnterBackground(_:) methods.

• For all other apps, call the Lifecycle APIs from the UIApplicationDelegate's applicationWillEnterForeground(_:) and applicationDidEnterBackground(_:) methods.

• If your application supports both a scene delegate and an app delegate, implement the Lifecycle APIs in both delegate objects.

iOS Swift

In iOS 13 and later, for a scene-based application, use the UISceneDelegate as follows:

func sceneWillEnterForeground(_ scene: UIScene) {
    MobileCore.lifecycleStart(additionalContextData: nil)
}

func sceneDidEnterBackground(_ scene: UIScene) {
    MobileCore.lifecyclePause()
}

In iOS 12 and earlier, use the UIApplicationDelegate as follows:

func applicationWillEnterForeground(_ application: UIApplication) {
    MobileCore.lifecycleStart(additionalContextData: nil)
}

func applicationDidEnterBackground(_ application: UIApplication) {
    MobileCore.lifecyclePause()
}

iOS Objective-C

In iOS 13 and later, for a scene-based application, use the UISceneDelegate as follows:

- (void) sceneWillEnterForeground:(UIScene *)scene {
    [AEPMobileCore lifecycleStart:nil];
}

- (void) sceneDidEnterBackground:(UIScene *)scene {
    [AEPMobileCore lifecyclePause];
}

In iOS 12 and earlier, use the UIApplicationDelegate as follows:

- (void) applicationWillEnterForeground:(UIApplication *)application {
    [AEPMobileCore lifecycleStart:nil];
}

- (void) applicationDidEnterBackground:(UIApplication *)application {
    [AEPMobileCore lifecyclePause];
}

data-variant=info

data-slots=text

Start and Pause Lifecycle data collection in SwiftUI

If your pure SwiftUI application does not use an app delegate or scene delegate, you may still use the Lifecycle extension by listening for scenePhase changes.

1. Register the Lifecycle extension and configure the Mobile SDK from the App class's init() function.

2. Set the @Environment property wrapper to observe the scenePhase variable to read the application's current phase.

3. Use the scenePhase property in conjunction with .onChange(of:) to trigger the Lifecycle APIs when the phase changes between .active and .background.

import SwiftUI
import AEPCore
import AEPLifecycle

@main
struct TestSwiftUIApp: App {

    @Environment(\.scenePhase) private var scenePhase

    init() {
        MobileCore.registerExtensions([Lifecycle.self]) {
            // Post registration tasks, such as configureWith(appId:)
        }
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }.onChange(of: scenePhase) { phase in
            switch phase {
                case .active:
                    MobileCore.lifecycleStart(additionalContextData: nil)
                case .background:
                    MobileCore.lifecyclePause()
                case .inactive:
                    print("Inactive scene phase")
                @unknown default:
                    print("unknown scene phase has been added to scenePhase enum")
            }
        }
    }
}

For more information, read the full blog post Implement Adobe Experience Cloud Mobile Lifecycle Tracking in SwiftUI.

Include additional context data

To include additional data with lifecycle tracking calls, pass an additional parameter to lifecycleStart(additionalContextData:) that contains context data:

iOS Swift

MobileCore.lifecycleStart(additionalContextData: ["myapp.category": "Game"])

iOS Objective-C

[AEPMobileCore lifecycleStart:@{@"myapp.category": @"Game"}];      

Lifecycle on Android

Start and Pause Lifecycle data collection from Android Activity

To ensure accurate session and crash reporting, the Lifecycle APIs must be implemented in every Activity of the Android Application. Do not start or stop Lifecycle in a Fragment.

Android Kotlin

Add the following to each Android Activity class.

import com.adobe.marketing.mobile.MobileCore
import com.adobe.marketing.mobile.Lifecycle
...

    override fun onResume() {
        MobileCore.setApplication(this.application)
        MobileCore.lifecycleStart(null)
    }

    override fun onPause() {
        MobileCore.lifecyclePause()
    }

Android Java

Add the following to each Android Activity class.

import com.adobe.marketing.mobile.MobileCore;
import com.adobe.marketing.mobile.Lifecycle;
...

    @Override
    public void onResume() {
        MobileCore.setApplication(getApplication());
        MobileCore.lifecycleStart(null);
    }

    @Override
    public void onPause() {
        MobileCore.lifecyclePause();
    }

data-variant=info

data-slots=text

Implementing global lifecycle callbacks

Starting with API Level 14, Android allows global lifecycle callbacks for activities. For more information, please read the Android developer guide.

You can use these callbacks to ensure that all of your activities correctly call the Lifecycle APIs without needing to update each individual Activity class. Add code to register an instance of ActivityLifecycleCallbacks in your Application class, just before registering your extensions with MobileCore.

Android Kotlin

import com.adobe.marketing.mobile.MobileCore
import com.adobe.marketing.mobile.Lifecycle

class MobileApp : Application() {

override fun onCreate() {
    super.onCreate()

    registerActivityLifecycleCallbacks(object: ActivityLifecycleCallbacks {
        override fun onActivityResumed(activity: Activity) {
            MobileCore.setApplication(activity.application)
            MobileCore.lifecycleStart(null)
        }

        override fun onActivityPaused(activity: Activity) {
            MobileCore.lifecyclePause()
        }

        // the following methods aren't needed for our lifecycle purposes, but are
        // required to be implemented by the ActivityLifecycleCallbacks object
        override fun onActivityCreated(activity: Activity, savedInstanceState: Bundle?) {}
        override fun onActivityStarted(activity: Activity) {}
        override fun onActivityStopped(activity: Activity) {}
        override fun onActivitySaveInstanceState(activity: Activity, outState: Bundle) {}
        override fun onActivityDestroyed(activity: Activity) {}
    })

    ...
}
 ...
}

Android Java

import com.adobe.marketing.mobile.MobileCore;
import com.adobe.marketing.mobile.Lifecycle;

public class MobileApp extends Application {

@Override
protected void onCreate() {
    super.onCreate();

    registerActivityLifecycleCallbacks(new ActivityLifecycleCallbacks() {
        @Override
        public void onActivityResumed(Activity activity) {
            MobileCore.setApplication(activity.getApplication());
            MobileCore.lifecycleStart(null);
        }

        @Override
        public void onActivityPaused(Activity activity) {
            MobileCore.lifecyclePause();
        }

        // the following methods aren't needed for our lifecycle purposes, but are
        // required to be implemented by the ActivityLifecycleCallbacks object
        @Override
        public void onActivityCreated(Activity activity, Bundle savedInstanceState) {}
        @Override
        public void onActivityStarted(Activity activity) {}
        @Override
        public void onActivityStopped(Activity activity) {}
        @Override
        public void onActivitySaveInstanceState(Activity activity, Bundle outState) {}
        @Override
        public void onActivityDestroyed(Activity activity) {}
    });

    ...
}
 ...
}

Include additional context data

To include additional data with lifecycle tracking calls, pass an additional parameter to lifecycleStart(Map) that contains context data:

Android Kotlin

MobileCore.lifecycleStart(mapOf("myapp.category" to "Game"))

Android Java

HashMap<String, Object> additionalContextData = new HashMap<String, Object>();
contextData.put("myapp.category", "Game");
MobileCore.lifecycleStart(additionalContextData);

data-variant=info

data-slots=text