Lifecycle Implementation Explained

[#1]

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:  

1. 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.  
2. 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! 

Resources:  

Lifecycle 

Lifecycle behavior reference 

Mobile Core 

AEP SDKs Documentation: Lifecycle 

[#2]

Thanks for the detailed guide with all the helpful references.

Something I stumbled upon in the lifecycle events implementation with AEP Edge was, that the background event did not contain the device and environment data which is present in the foreground event. See https://developer.adobe.com/client-sdks/edge/lifecycle-for-edge-network/metrics/#lifecycle-applicati...

Why is this the Case? This information should be available at all times. What is the recommendation then if we want to combine device/ environment information with metrics set via the application background event? Do we have to use session persistence in the data view configuration?

Regards

Florian

[#3]

Hi @FlorianGö1, 

Good question! The Lifecycle events for Edge are generally aligned with the metrics that were available in the Lifecycle for Analytics implementation - that is, Lifecycle in the context of a direct Analytics extension implementation also doesn't emit device and environment information for lifecyclePause (app background) events.

Also generally, since the API calls for lifecycleStart and lifecyclePause are intended to be tied to the mobile app's actual launch/backgrounding, the Lifecycle start event should provide the desired device and env information when looking at the app session level.

Hope this helps!

[#4]

@amandadeasy Thank you for the explaination. I just checked Adobe Analytics and there it seems to work just fine to combine operating system / device name etc. with background metrics like Crashes or Average Session Length (Mobile). So it seems that for Adobe Analytics this information is at some point added to these Application Close hits, maybe at the Serverside?

I think it would be best to have the device and environment information also present in the hit level for the AEP background event. Is this maybe planned to be implemented in the future? Or is it not planned and we have to use the session persistence?

If the last is the case, I think it would be really good if you could update this in the guide and the documentation, to make clear that it is recommended to set the persistence of all device and environment dimensions at least to session level in the data view configuration.

Regards

Florian

[#5]

Great blog! Super helpful information

[#6]

@FlorianGö1 The device and environment information is set on the lifecycleStart event and that session data is available on subsequent events (including background events). This is handled by the SDK, so no need to configure session persistence. If you want to set this data on background events, you can do a custom implementation and attach the data manually to the XDM payload where you need it, similar to the steps outlined here: https://developer.adobe.com/client-sdks/edge/adobe-journey-optimizer-decisioning/#define-the-action.