Lifecycle

In version 4 of the iOS SDK, this implementation was completed automatically.
The Experience Platform SDK will not automatically collect Lifecycle metrics. To continue collecting Lifecycle metrics, you must add code to your app. For more information, see Manual Lifecycle Implementation.
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 Lifecycle to your app
Android
iOS (AEP 3.x)
iOS (ACP 2.x)
React Native
Flutter
Cordova
Unity
Xamarin
1.Import the library:
1
   import com.adobe.marketing.mobile.*;
Copied!
Add the AEPLifecycle extension and its dependency, the Mobile Core extension, to your project using Cocoapods.
Add the following pods in your Podfile:
1
pod 'AEPCore','~>3.0'
2
pod 'AEPLifecycle','~>3.0'
Copied!
Import the Lifecycle library:
Swift
1
import AEPCore
2
import AEPLifecycle
Copied!
Objective-C
1
@import AEPCore;
2
@import AEPLifecycle;
Copied!
The Lifecycle extension is included in the Mobile Core extension. Add the Mobile Core extension to your project using Cocoapods.
Add the following pod in your Podfile:
1
pod 'ACPCore','~>2.0'
Copied!
Import the Lifecycle library:
Swift
In Swift, importing ACPCore also imports the necessary Lifecycle APIs:
1
import ACPCore
Copied!
Objective-C
1
 #import "ACPLifecycle.h"
2
 #import "ACPCore.h"
Copied!
JavaScript
Import the Lifecycle extension
1
import {ACPLifecycle} from '@adobe/react-native-acpcore';
Copied!
Dart
Import the Lifecycle extension
1
import 'package:flutter_acpcore/flutter_acplifecycle.dart';
Copied!
Cordova
After creating your Cordova app and adding the Android and iOS platforms, the Lifecycle extension for Cordova can be added with this command:
1
cordova plugin add https://github.com/adobe/cordova-acpcore.git
Copied!
C#
After importing the ACPCore.unitypackage, the Lifecycle extension for Unity can be added with following code in the MainScript
1
using com.adobe.marketing.mobile;
Copied!
C#
After adding the iOS ACPCore NuGet package or the Android ACPLifecycle NuGet package, the Lifecycle extension can be added by this import statement
1
using Com.Adobe.Marketing.Mobile;
Copied!
Register Lifecycle with Mobile Core and add appropriate Start/Pause calls
Android
iOS (AEP 3.x)
iOS (ACP 2.x)
React Native
Cordova
Unity
Xamarin
1.Register the Lifecycle extension:
1
public class TargetApp extends Application {
2
​
3
 @Override
4
 public void onCreate() {
5
     super.onCreate();
6
     MobileCore.setApplication(this);
7
​
8
     try {
9
         Lifecycle.registerExtension();
10
         // register other extensions
11
         MobileCore.start(new AdobeCallback () {
12
             @Override
13
             public void call(Object o) {
14
                 MobileCore.configureWithAppID("yourAppId");
15
             }
16
         });    
17
     } catch (Exception e) {
18
         //Log the exception
19
     }
20
 }
21
}
Copied!
2.In the onResume function, start the lifecycle data collection:
1
   @Override  
2
   public void onResume() {  
3
      MobileCore.setApplication(getApplication());
4
      MobileCore.lifecycleStart(null);
5
   }
Copied!
Setting the application is only necessary on activities that are entry points for your application. However, setting the application on each Activity has no negative impact and ensures that the SDK always has the necessary reference to your application. We recommend that you call setApplicationin each of your activities.
3.In the onPause function, pause the lifecycle data collection:
1
   @Override
2
   public void onPause() {
3
      MobileCore.lifecyclePause();
4
   }
Copied!
To ensure accurate session and crash reporting, this call must be added to every activity.
Swift
1.Register the Lifecycle extension with the SDK Core by adding the following to your app's application:didFinishLaunchingWithOptions: delegate method. This will register the extension with Core and begin Lifecycle event processing:
1
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
2
     MobileCore.registerExtensions([Lifecycle.self, ...], {
3
       ...
4
     }
5
}
Copied!
2.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.
1
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
2
     let appState = application.applicationState            
3
     MobileCore.registerExtensions([Lifecycle.self, ...], {
4
       if appState != .background {
5
         // only start lifecycle if the application is not in the background 
6
         MobileCore.lifecycleStart(additionalContextData: nil)
7
       }
8
     }
9
}
Copied!
3.When launched, if your app is resuming from a backgrounded state, iOS might call your applicationWillEnterForeground: delegate method. You also need to call lifecycleStart:, but this time you do not need all of the supporting code that you used in application:didFinishLaunchingWithOptions::
1
func applicationWillEnterForeground(_ application: UIApplication) {    
2
   MobileCore.lifecycleStart(additionalContextData: nil)
3
}
Copied!
In iOS 13 and later, for a scene-based application, use the UISceneDelegate's sceneWillEnterForeground method as follows:
1
func sceneWillEnterForeground(_ scene: UIScene) {
2
   MobileCore.lifecycleStart(additionalContextData: nil)
3
}
Copied!
For more information on handling foregrounding applications with Scenes, refer to Apple's documentation here​
4.When the app enters the background, pause Lifecycle data collection from your app's applicationDidEnterBackground: delegate method:
1
func applicationDidEnterBackground(_ application: UIApplication) {    
2
    MobileCore.lifecyclePause()
3
}
Copied!
In iOS 13 and later, for a scene-based application, use the UISceneDelegate's sceneDidEnterBackground method as follows:
1
func sceneDidEnterBackground(_ scene: UIScene) {
2
    MobileCore.lifecyclePause()
3
}
Copied!
For more information on handling backgrounding applications with Scenes, refer to Apple's documentation here​
Objective-C
1.Register the Lifecycle extension with the SDK Core by adding the following to your app's application:didFinishLaunchingWithOptions: delegate method. This will register the extension with Core and begin Lifecycle event processing:
1
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
2
  // register the lifecycle extension
3
 [AEPMobileCore registerExtensions:@[AEPMobileLifecycle.class, ...] completion:^{
4
   ...
5
 }];
6
 return YES;
7
}
Copied!
2.Start Lifecycle data collection by calling lifecycleStart: from within the callback of the AEPMobileCore::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.
1
- (BOOL) application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
2
    // register the lifecycle extension, and begin event processing with Core
3
    const UIApplicationState appState = application.applicationState;
4
   [AEPMobileCore registerExtensions:@[AEPMobileLifecycle.class, ...] completion:^{
5
     // only start lifecycle if the application is not in the background
6
     if (appState != UIApplicationStateBackground) {
7
         [AEPMobileCore lifecycleStart:nil];
8
     }
9
   }];
10
}
Copied!
3.When launched, if your app is resuming from a backgrounded state, iOS might call your applicationWillEnterForeground: delegate method. You also need to call lifecycleStart:, but this time you do not need all of the supporting code that you used in application:didFinishLaunchingWithOptions::
1
- (void) applicationWillEnterForeground:(UIApplication *)application {
2
    [AEPMobileCore lifecycleStart:nil];
3
}
Copied!
In iOS 13 and later, for a scene-based application, use the UISceneDelegate's sceneWillEnterForeground method as follows:
1
- (void) sceneWillEnterForeground:(UIScene *)scene {
2
   [AEPMobileCore lifecycleStart:nil];
3
}
Copied!
For more information on handling foregrounding applications with Scenes, refer to Apple's documentation here​
4.When the app enters the background, pause Lifecycle data collection from your app's applicationDidEnterBackground: delegate method:
1
 - (void) applicationDidEnterBackground:(UIApplication *)application {
2
    [AEPMobileCore lifecyclePause];
3
 }
Copied!
In iOS 13 and later, for a scene-based application, use the UISceneDelegate's sceneDidEnterBackground method as follows:
1
- (void) sceneDidEnterBackground:(UIScene *)scene {
2
   [AEPMobileCore lifecyclePause];
3
}
Copied!
For more information on handling backgrounding applications with Scenes, refer to Apple's documentation here​
Swift
1.Register the Lifecycle extension with the SDK Core by adding the following to your app's application:didFinishLaunchingWithOptions: delegate method:
1
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
2
    // register the lifecycle extension
3
    ACPLifecycle.registerExtension();
4
}
Copied!
2.Start Lifecycle data collection by calling lifecycleStart: from within the callback of the ACPCore::start: 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.
1
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
2
    // register the lifecycle extension
3
    ACPLifecycle.registerExtension();
4
​
5
    let appState = application.applicationState;            
6
    ACPCore.start {
7
        // only start lifecycle if the application is not in the background    
8
        if appState != .background {
9
            ACPCore.lifecycleStart(nil)
10
        }    
11
    }    
12
}
Copied!
3.When launched, if your app is resuming from a backgrounded state, iOS might call your applicationWillEnterForeground: delegate method. You also need to call lifecycleStart:, but this time you do not need all of the supporting code that you used in application:didFinishLaunchingWithOptions::
1
func applicationWillEnterForeground(_ application: UIApplication) {    
2
    ACPCore.lifecycleStart(nil)
3
}
Copied!
In iOS 13 and later, for a scene-based application, use the UISceneDelegate's sceneWillEnterForeground method as follows:
1
func sceneWillEnterForeground(_ scene: UIScene) {
2
     ACPCore.lifecycleStart(nil)
3
}
Copied!
For more information on handling foregrounding applications with Scenes, refer to Apple's documentation here​
4.When the app enters the background, pause Lifecycle data collection from your app's applicationDidEnterBackground: delegate method:
1
func applicationDidEnterBackground(_ application: UIApplication) {    
2
    ACPCore.lifecyclePause()
3
}
Copied!
In iOS 13 and later, for a scene-based application, use the UISceneDelegate's sceneDidEnterBackground method as follows:
1
func sceneDidEnterBackground(_ scene: UIScene) {
2
     ACPCore.lifecyclePause()
3
}
Copied!
For more information on handling backgrounding applications with Scenes, refer to Apple's documentation here​
Objective-C
1.Register the Lifecycle extension with the SDK Core by adding the following to your app's application:didFinishLaunchingWithOptions: delegate method:
1
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
2
  // register the lifecycle extension
3
 [ACPLifecycle registerExtension];
4
  return YES;
5
}
Copied!
2.Start Lifecycle data collection by calling lifecycleStart: from within the callback of the ACPCore::start: 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.
1
- (BOOL) application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
2
    // register the lifecycle extension
3
    [ACPLifecycle registerExtension];
4
​
5
    const UIApplicationState appState = application.applicationState;
6
    [ACPCore start:^{
7
        // only start lifecycle if the application is not in the background
8
        if (appState != UIApplicationStateBackground) {
9
            [ACPCore lifecycleStart:nil];
10
        }
11
    }];
12
}
Copied!
3.When launched, if your app is resuming from a backgrounded state, iOS might call your applicationWillEnterForeground: delegate method. You also need to call lifecycleStart:, but this time you do not need all of the supporting code that you used in application:didFinishLaunchingWithOptions::
1
- (void) applicationWillEnterForeground:(UIApplication *)application {
2
    [ACPCore lifecycleStart:nil];
3
}
Copied!
In iOS 13 and later, for a scene-based application, use the UISceneDelegate's sceneWillEnterForeground method as follows:
1
- (void) sceneWillEnterForeground:(UIScene *)scene {
2
   [ACPCore lifecycleStart:nil];
3
}
Copied!
For more information on handling foregrounding applications with Scenes, refer to Apple's documentation here​
4.When the app enters the background, pause Lifecycle data collection from your app's applicationDidEnterBackground: delegate method:
1
 - (void) applicationDidEnterBackground:(UIApplication *)application {
2
    [ACPCore lifecyclePause];
3
 }
Copied!
In iOS 13 and later, for a scene-based application, use the UISceneDelegate's sceneDidEnterBackground method as follows:
1
- (void) sceneDidEnterBackground:(UIScene *)scene {
2
   [ACPCore lifecyclePause];
3
}
Copied!
For more information on handling backgrounding applications with Scenes, refer to Apple's documentation here​
Registering the extension with Core:
When using React Native, registering Lifecycle with Mobile Core should be done in native code which is shown under the Android and iOS (ACP 2.x) tabs.
When using Cordova, registering Lifecycle with Mobile Core must be done in native code which is shown under the Android and iOS tabs.
Starting and Pausing a lifecycle event: Add the OnApplicationPause in the MainScript with the following code:
1
private void OnApplicationPause(bool pauseStatus)
2
{
3
  if (pauseStatus)
4
  {
5
    ACPCore.LifecyclePause();
6
  }
7
  else
8
  {
9
    var cdata = new Dictionary<string, string>();
10
    cdata.Add("launch.data", "added");
11
    ACPCore.LifecycleStart(cdata);
12
  }
13
}
Copied!
iOS
1.Register the Lifecycle extension with the SDK Core by adding the following to your app's FinishedLaunching: delegate method:
1
public override bool FinishedLaunching(UIApplication app, NSDictionary options)
2
{
3
  ACPLifecycle.RegisterExtension();
4
  return base.FinishedLaunching(app, options);
5
}
Copied!
2.Start Lifecycle data collection by calling LifecycleStart: from within the callback of the ACPCore::start: method in your app's FinishedLaunching: delegate method.
If your iOS application supports background capabilities, your FinishedLaunching: 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 UIApplicationState.Background.
1
public override bool FinishedLaunching(UIApplication app, NSDictionary options)
2
{
3
  ACPLifecycle.RegisterExtension();
4
​
5
  // only start lifecycle if the application is not in the background
6
  var appstate = app.ApplicationState;
7
  if(appstate != UIApplicationState.Background)
8
  {
9
    ACPCore.LifecycleStart(null);
10
  }
11
  return base.FinishedLaunching(app, options);
12
}
Copied!
3.When launched, if your app is resuming from a backgrounded state, iOS might call your WillEnterForeground: delegate method. You also need to call LifecycleStart:, but this time you do not need all of the supporting code that you used in FinishedLaunching::
1
public override void WillEnterForeground(UIApplication uiApplication)
2
{
3
  base.WillEnterForeground(uiApplication);
4
  ACPCore.LifecycleStart(null);
5
}
Copied!
4.When the app enters the background, pause Lifecycle data collection from your app's DidEnterBackground: delegate method:
1
public override void DidEnterBackground(UIApplication uiApplication)
2
{
3
  base.DidEnterBackground(uiApplication);
4
  ACPCore.LifecyclePause();
5
}
Copied!
Android
1.Register the Lifecycle extension:
1
protected override void OnCreate(Bundle savedInstanceState)
2
{
3
  base.OnCreate(savedInstanceState);
4
 LoadApplication(new App());
5
  ACPCore.Application = this.Application;
6
  ACPLifecycle.RegisterExtension();
7
}
Copied!
2.In the onResume function, start the lifecycle data collection:
1
protected override void OnResume()
2
{
3
  base.OnResume();
4
  ACPCore.LifecycleStart(null);
5
}
Copied!
Setting the application is only necessary on activities that are entry points for your application. However, setting the application on each Activity has no negative impact and ensures that the SDK always has the necessary reference to your application. We recommend that you set the application (ACPCore.Application = this.Application;) in each of your activities.
3.In the onPause function, pause the lifecycle data collection:
1
protected override void OnPause()
2
{
3
  base.OnPause();
4
  ACPCore.LifecyclePause();
5
}
Copied!
To ensure accurate session and crash reporting, this call must be added to every activity.
Lifecycle metrics
The following is a complete list of all of the metrics provided on your user's app lifecycle.
Application Context
Metric
Key
Description
App ID
a.AppID
Stores the application name and version in the following format: AppName BundleVersion (app version code) . An example of this format is MyAppName 1.1(1).
Device Name
a.DeviceName
Stores the device name.
Operating System Version
a.OSVersion
Operating system name and version.
Carrier Name
a.CarrierName
Stores the name of the mobile service provider as provided by the device.

Important: This metric is not automatically stored in an Analytics variable. You must create a processing rule to copy this value to an Analytics variable for reporting.
Resolution
a.Resolution
Width x Height in pixels.
Locale
a.locale
Locale set for this device, for example, en-US.
Install
Metric
Key
Description
First Launches
a.InstallEvent
Triggered at the first run after installation or re-installation.
Install Date
a.InstallDate
Date of first launch after installation. The format is M/d/yyyy, and an example is 5/3/2017.
Upgrade
Metric
Key
Description
Upgrades
a.UpgradeEvent
Triggered at the first run after upgrade or when the version number changes.
Launches since last upgrade
a.LaunchesSinceUpgrade
Number of days since the application version number changed.
Days since last upgrade
a.DaysSinceLastUpgrade
Number of launches since the application version number changed.
Launch
Metric
Key
Description
Daily Engaged Users
a.DailyEngUserEvent
Triggered when the application is used on a particular day. Important: This metric is not automatically stored in an Analytics metric. You must create a processing rule that sets a custom event to capture this metric.
Monthly Engaged Users
a.MonthlyEngUserEvent
Triggered when the application is used during a particular month. Important: This metric is not automatically stored in an Analytics metric. You must create a processing rule that sets a custom event to capture this metric.
Launches
a.LaunchEvent
Triggered on every run, including crashes and installs. Also triggered when the app is resumed from the background after the lifecycle session timeout is exceeded.
Previous Session Length
a.PrevSessionLength
Reports the number of seconds that a previous application session lasted based on how long the application was open and in the foreground.
Ignored Session Length
a.ignoredSessionLength
If the last session is set to last longer than lifecycle.sessionTimeout, that session length is ignored and recorded here.
Launch Number
a.Launches
Number of times the application was launched or brought out of the background.
Days since first use
a.DaysSinceFirstUse
Number of days since first run.
Days since last use
a.DaysSinceLastUse
Number of days since last use.
Hour of Day
a.HourOfDay
Measures the hour the app was launched and uses the 24-hour numerical format. Used for time parting to determine peak usage times.
Day of Week
a.DayOfWeek
Measures the day of the week the app was launched.
Crash
Metric
Key
Description
Crashes
a.CrashEvent
Triggered when the application crashed before closing. The event is sent when the application is started again after the crash.
Device Information
Metric
Key
Description
AppID
a.AppID
Stores the application name and version in the AppName BundleVersion (app version code) format. An example of this format is MyAppName 1.1(1).
Device name
a.DeviceName
Stores the device name.
Operating system version
a.OSVersion
Operating system name and version.
Carrier name
a.CarrierName
Stores the name of the mobile service provider as provided by the devices.
Important: This metric is not automatically stored in an Analytics variable. For reporting, you must create a processing rule to copy this value to an Analytics variable.
Resolution
a.Resolution
Width x height, in pixels.
Locale
a.Locale
Locale set for this device, for example, en-US.
If you need to programmatically update your SDK configuration, use the following information to change your Lifecycle configuration values:
The time that your app spends in the background is not included in the session length.
Key
Description
lifecycle.sessionTimeout
Time, in seconds, that must elapse between the time the app is launched and before the launch is considered to be a new session. This timeout also applies when your application is sent to the background and reactivated.
Default value is 300 seconds (5 minutes).
Identity event reference
Migrating to AEPLifecycle reference
Last modified 8d ago
Export as PDF
Copy link
Edit on GitHub
Contents
Add Lifecycle to your app