diff --git a/gatsby-config.js b/gatsby-config.js index da24c2ebbb..26576c0ed5 100644 --- a/gatsby-config.js +++ b/gatsby-config.js @@ -405,6 +405,10 @@ module.exports = { title: "Event reference", path: "/edge/lifecycle-for-edge-network/event-reference" }, + { + title: "Behavior reference", + path: "/edge/lifecycle-for-edge-network/behavior-reference" + }, { title: "Data reference", path: "/edge/lifecycle-for-edge-network/metrics" diff --git a/src/pages/edge/lifecycle-for-edge-network/assets/index/lifecycle-app-launch-and-close.svg b/src/pages/edge/lifecycle-for-edge-network/assets/index/lifecycle-app-launch-and-close.svg new file mode 100644 index 0000000000..547314efca --- /dev/null +++ b/src/pages/edge/lifecycle-for-edge-network/assets/index/lifecycle-app-launch-and-close.svg @@ -0,0 +1,3 @@ + + +
4b.
Application Close (Background)
(Close type: close)
4a.
lifecyclePause
2b.
Application Launch (Foreground)
2a.
lifecycleStart
(Start of new session)
1.
App launched
3.
App closed by user
\ No newline at end of file diff --git a/src/pages/edge/lifecycle-for-edge-network/assets/index/lifecycle-crash.svg b/src/pages/edge/lifecycle-for-edge-network/assets/index/lifecycle-crash.svg new file mode 100644 index 0000000000..248b93bc96 --- /dev/null +++ b/src/pages/edge/lifecycle-for-edge-network/assets/index/lifecycle-crash.svg @@ -0,0 +1,3 @@ + + +
5b.
Application Close (Background)
(Close type: unknown)
5a.
lifecycleStart
5c.
Application Launch (Foreground)
2b.
Application Launch (Foreground)
2a.
lifecycleStart
1.
App launched
3.
App crashed/force closed
(Unable to call lifecyclePause)
4.
App launched
\ No newline at end of file diff --git a/src/pages/edge/lifecycle-for-edge-network/assets/index/lifecycle-missing-pause-not-terminated.svg b/src/pages/edge/lifecycle-for-edge-network/assets/index/lifecycle-missing-pause-not-terminated.svg new file mode 100644 index 0000000000..2a9c0af050 --- /dev/null +++ b/src/pages/edge/lifecycle-for-edge-network/assets/index/lifecycle-missing-pause-not-terminated.svg @@ -0,0 +1,3 @@ + + +
5b.
Call ignored, no event dispatched
5a.
lifecycleStart
(Consecutive start)
2b.
Application Launch (Foreground)
2a.
lifecycleStart
1.
App launched
3.
App closed normally
(Incorrect implementation:
Missing lifecyclePause)
4.
App launched
(Still in memory)
\ No newline at end of file diff --git a/src/pages/edge/lifecycle-for-edge-network/assets/index/lifecycle-missing-pause-terminated.svg b/src/pages/edge/lifecycle-for-edge-network/assets/index/lifecycle-missing-pause-terminated.svg new file mode 100644 index 0000000000..d5ac381352 --- /dev/null +++ b/src/pages/edge/lifecycle-for-edge-network/assets/index/lifecycle-missing-pause-terminated.svg @@ -0,0 +1,3 @@ + + +
6b.
Application Close (Background)
(Close type unknown)
6a.
lifecycleStart
6c.
Application Launch (Foreground)
2b.
Application Launch (Foreground)
2a.
lifecycleStart
1.
App launched
3.
App closed normally
(Incorrect implementation:
Missing lifecyclePause)
4.
App removed
from memory
5.
App launched
\ No newline at end of file diff --git a/src/pages/edge/lifecycle-for-edge-network/assets/index/lifecycle-missing-start.svg b/src/pages/edge/lifecycle-for-edge-network/assets/index/lifecycle-missing-start.svg new file mode 100644 index 0000000000..053564c2fe --- /dev/null +++ b/src/pages/edge/lifecycle-for-edge-network/assets/index/lifecycle-missing-start.svg @@ -0,0 +1,3 @@ + + +
3b.
Application Close (Background)
3a.
lifecyclePause
1.
App launched
(Incorrect implementation:
Missing lifecycleStart)
2.
App closed normally
\ No newline at end of file diff --git a/src/pages/edge/lifecycle-for-edge-network/assets/index/lifecycle-pause-after-pause.svg b/src/pages/edge/lifecycle-for-edge-network/assets/index/lifecycle-pause-after-pause.svg new file mode 100644 index 0000000000..05eaf860eb --- /dev/null +++ b/src/pages/edge/lifecycle-for-edge-network/assets/index/lifecycle-pause-after-pause.svg @@ -0,0 +1,3 @@ + + +
1. App still in memory
2. lifecycleStart not called
2b.
Call ignored, no event dispatched
2a.
lifecyclePause
1b.
Application Close (Background)
1a.
lifecyclePause
\ No newline at end of file diff --git a/src/pages/edge/lifecycle-for-edge-network/assets/index/lifecycle-rapid-successive-calls.svg b/src/pages/edge/lifecycle-for-edge-network/assets/index/lifecycle-rapid-successive-calls.svg new file mode 100644 index 0000000000..f9fa97c7d3 --- /dev/null +++ b/src/pages/edge/lifecycle-for-edge-network/assets/index/lifecycle-rapid-successive-calls.svg @@ -0,0 +1,3 @@ + + +
< 0.5 sec
5b.
1. Cancels pause task (4b)
2. No Application Launch event
3. No Lifecycle data changes
5a.
lifecycleStart
(Activity B)
4b.
Pause task queued
4a.
lifecyclePause
(Activity A)
2b.
Application Launch (Foreground)
2a.
lifecycleStart
(Activity A)
1.
App launched
(ex: Activity A)
3.
Activity B launched
(Activity A closing)
\ No newline at end of file diff --git a/src/pages/edge/lifecycle-for-edge-network/assets/index/lifecycle-start-after-start.svg b/src/pages/edge/lifecycle-for-edge-network/assets/index/lifecycle-start-after-start.svg new file mode 100644 index 0000000000..e68464ed92 --- /dev/null +++ b/src/pages/edge/lifecycle-for-edge-network/assets/index/lifecycle-start-after-start.svg @@ -0,0 +1,3 @@ + + +
1. App still in memory
2. lifecyclePause not called
2b.
Call ignored, no event dispatched
2a.
lifecycleStart
1b.
Application Launch (Foreground)
1a.
lifecycleStart
\ No newline at end of file diff --git a/src/pages/edge/lifecycle-for-edge-network/behavior-reference.md b/src/pages/edge/lifecycle-for-edge-network/behavior-reference.md new file mode 100644 index 0000000000..ee78d23cdf --- /dev/null +++ b/src/pages/edge/lifecycle-for-edge-network/behavior-reference.md @@ -0,0 +1,374 @@ +--- +title: Mobile Core Lifecycle for Edge Network behavior reference +description: A reference for understanding how Lifecycle for Edge Network behaves under different scenarios. +keywords: +- Lifecycle +- Lifecycle V2 +- Lifecycle for Mobile Core +- Lifecycle for Platform +- Lifecycle for Edge Network +- Lifecycle Edge +- Lifecycle iOS +- Lifecycle Android +- Product reference +--- + +# Lifecycle for Edge Network behavior reference + +The Lifecycle for Edge Network extension introduces a new way of collecting Lifecycle data and tracking sessions. Unlike the previous Lifecycle extension, which used a configurable timeout window for session tracking, this extension emits Application Launch and Close events, treating each pair as an independent session. As a result of not relying on a session timeout window to identify new sessions, the potential Lifecycle states are simplified. + +## General behavior + +The Lifecycle for Edge Network extension relies solely on the Lifecycle events dispatched by the [`lifecycleStart`](../../home/base/mobile-core/lifecycle/api-reference.md#lifecyclestart) and [`lifecyclePause`](../../home/base/mobile-core/lifecycle/api-reference.md#lifecyclepause) calls to determine the start and end of new sessions and to calculate lifecycle data. + +A Lifecycle session is the time between a `lifecycleStart` call and a `lifecyclePause` call. A new session is detected when `lifecycleStart` is called after app first launch or after a `lifecyclePause`. + +All events that are not Lifecycle start or Lifecycle pause do not affect Lifecycle state or data. Starting MobileCore using `registerExtensions` does not automatically start a Lifecycle session nor does it affect Lifecycle data. + +#### Event reference + +Events dispatched by the Lifecycle extension to support Adobe Experience Platform Edge Network workflows include: + +* [Lifecycle Application Launch (Foreground)](../../home/base/mobile-core/lifecycle/event-reference.md#lifecycle-application-foreground) +* [Lifecycle Application Close (Background)](../../home/base/mobile-core/lifecycle/event-reference.md#lifecycle-application-background) + +For full event details, please read the [Lifecycle event reference](../../home/base/mobile-core/lifecycle/event-reference.md). + +#### Data payloads + +The Lifecycle for Edge Network event payloads are defined by the Platform Mobile Lifecycle Details XDM field group, and include information about the application, device, and environment when the event occurred. Please refer to [Lifecycle for Edge Network data](metrics.md) for the data included with these events. + +## Expected Lifecycle scenarios + +The following Lifecycle workflows show examples of the expected ordering of Lifecycle events. + +### App launch and close + +This scenario shows the standard Lifecycle workflow, with expected Lifecycle API calls. + +![](./assets/index/lifecycle-app-launch-and-close.svg) + + + +### On app crash or force close + +This scenario shows the standard Lifecycle workflow when the application crashes or is force closed, preventing `lifecyclePause` from being called. + +![](./assets/index/lifecycle-crash.svg) + + + +### Rapid successive lifecyclePause and lifecycleStart calls + +This scenario shows the handling of rapid successive calls to `lifecyclePause` followed by `lifecycleStart`. This is designed to accommodate use cases such as in Android, where Lifecycle APIs are linked to the Android Activity lifecycle callback methods. When users transition between activities within the same app, this logic prevents these transitions from being tracked as individual sessions. + +![](./assets/index/lifecycle-rapid-successive-calls.svg) + + + +## Troubleshooting unexpected Lifecycle scenarios + +The following Lifecycle workflows show examples of the unexpected ordering of Lifecycle events that can impact Lifecycle data and can indicate an incorrect implementation of the Lifecycle APIs. To address the following scenarios, refer to the [implementation guide for Lifecycle](../../home/base/mobile-core/lifecycle/index.md#register-lifecycle-with-mobile-core-and-add-appropriate-startpause-calls). + +### Consecutive Lifecycle API calls + +Consecutive `lifecycleStart` and consecutive `lifecyclePause` API calls will not update their respective timestamps stored in persistence, and Lifecycle data is not changed. + +#### Consecutive `lifecycleStart` API calls + +![](./assets/index/lifecycle-start-after-start.svg) + + + +#### Consecutive `lifecyclePause` API calls + +![](./assets/index/lifecycle-pause-after-pause.svg) + + + +### Missing pause, app terminated + +This scenario looks the same as a standard crash, but the underlying reason is an incorrect implementation where `lifecyclePause` is not called before the app is terminated. + +![](./assets/index/lifecycle-missing-pause-terminated.svg) + + + +### Missing pause, app still in memory + +This scenario shows an example of [consecutive `lifecycleStart` API calls](#consecutive-lifecyclestart-api-calls). The app close is not detected because `lifecyclePause` is not called. As the app is not removed from memory, the current session continues. + +![](./assets/index/lifecycle-missing-pause-not-terminated.svg) + + + +In this scenario, the `lifecycleStart` call (5a) is not detected as a new session nor a crash. It will have the consequence of a [consecutive `lifecycleStart` API call](#consecutive-lifecyclestart-api-calls). + +### Missing start + +This scenario shows an example of a missing `lifecycleStart` call (1). The new session is not detected because `lifecycleStart` is not called. + +![](./assets/index/lifecycle-missing-start.svg) + + + +In this scenario, the `lifecyclePause` call (3a) will dispatch an Application Close event only if the Lifecycle extension state is not already set to Pause (that is, `lifecyclePause` has not been called before the current call). Otherwise, it is effectively a [consecutive `lifecyclePause` API call](#consecutive-lifecyclepause-api-calls).