Adobe Analytics

amandadeasy · 6/10/24

Mobile Core is one of the fundamental extensions in a Mobile SDK implementation and is pre-configured when creating a new mobile tags property. Within Mobile Core lives the Lifecycle extension enabling collection of installs, upgrades, launches, and crashes, along with app-centric dimensions including the app ID and device information. This mobile reporting can be used to understand your mobile app usage, popularity in various operating systems, version adoption, and crash rates. This post will explain the significance of how Lifecycle metrics, when implemented properly, gives valuable insight into app usage, and potential pitfalls that can wreak havoc in your reporting.

Installing Lifecycle Metrics

The first step of implementing Lifecycle metrics is to add and import the necessary extensions for calling the Lifecycle APIs, integrating lifecycle start and pause calls into the data collection functionality. Start with the Lifecycle API within the Mobile Core extension. Find the Android and iOS code examples here.

NOTE

If you're using Edge Data Collection, be sure to add the Edge Network extension to your app in addition to the Lifecycle and Mobile Core extensions as described above.

Once the extensions are installed, register the Lifecycle and Mobile Core extensions and add the start and pause calls.

lifecycleStart

The lifecycleStart API starts lifecycle data collection and should be called when the app enters the foreground, including when the app launches or resumes from the background. The lifecycleStart calls enable the Launches, First Launches, Installs, and Upgrades metrics, as well as passing context data about the app including the app ID, name, and version as well as the device and environment details. These calls are critical for determining session starts and resumes, which impacts the Launch count. It is important to note that Launches are measured differently than Visits. Launches are counted each time the app is opened or brought to the foreground outside of the configured Lifecycle session timeout window. Visits, on the other hand, count the number of sessions and reset after 30 minutes of inactivity by default, though this setting is configurable. An app can have multiple Launches within a 30-minute window, resulting in a higher number of Launches than Visits.

lifecyclePause

Conversely, the lifecyclePause API pauses Lifecycle data collection and should be called when the app enters the background. The lifecyclePause call enables background metrics which determines if the app was closed gracefully. If the app is closed and a lifecyclePause call is missing due to an incorrect implementation, actual app crash, force close of the app, or similar, the next start of the app will flag the previous session as a crash. Pause calls also determine session length, influencing time spent metrics.

If You're Using Edge

In an Edge implementation, Lifecycle dimensions are not automatically set on every call as they previously were with mobile Analytics implementation and do not match exactly. Metrics such as Previous Session Length, Launch Number, Days Since First Use, and more are no longer available out of the box and can either be calculated or captured manually. Instead, you can add these dimensions to every hit with a Launch rule following these steps:

Update your schema to include the "AEP Mobile Lifecycle Details" field group. This field group contains three sub-field groups: "applications" which includes the Lifecycle metrics, "device" which collects data about the user's device, and "environment" for information including the system software.
Configure a rule in your tags property to forward data to the Edge Network. This will send data to Edge on Foreground and Background events. Check out the documentation for a step-by-step guide.

Pitfalls to Avoid

Be sure to avoid these common pitfalls when implementing start and pause calls:

Missing lifecycleStart calls when the app re-enters the foreground can prevent lifecycle data collection when a session continues.
Consecutive lifecyclePause calls can leave a new session undetected if lifecycleStart is not called, and can impact app background time.
Missing lifecyclePause calls when the app enters the background causes the app close type to be unknown, which will inflate crashes. Learn more on tracking app crashes in Android and iOS.
Missing lifecyclePause calls will also cause excessive session length as the app enters the background but data collection has not been paused.
If you're migrating your mobile implementation to Edge Data Collection, you should consider mapping the application.name and application.version schema fields with XDM variables. These fields make up the App ID, so mapping these in your implementation will ensure consistency in your reporting as you migrate.
It is recommended to disable the Legacy Reporting and Attribution for Background Hits in your Analytics report suite App Reporting. This setting is enabled by default with App Reporting but can cause background hits to appear in reporting and affects attribution.

Validating Start and Pause Calls

Use AEP Assurance to validate that the Lifecycle start and pause calls are happening as expected. With AEP Assurance installed, connect to a session to validate the Adobe logs.

Search for "LifecycleResume" when the app enters the foreground and "LifecyclePause" when the app enters the background. Additionally, check within the event that the ACPExtensionEventData is set to "start" or "pause" and that the application XDM fields are mapped correctly.

Lifecycle metrics provide valuable insight into app usage and details. Use this guide when preparing for implementation and validation and avoid common pitfalls that can skew your metrics. Let us know in the comments what other learnings you've found when implementing the Lifecycle extension!