Mobile Application Lifecycle Events Spec

Learn the app lifecyle events tracked out of the box by RudderStack SDKs.

RudderStack lets you track various application lifecycle events across the mobile SDKs and get insights into app-related metrics like installs, opens, etc. This guide provides the details and semantic definitions of these events and the associated properties.

info
To track the application lifecycle events on the Android platform using the Unity SDK, you need to perform some additional steps. For more information on these steps, refer to Tracking application lifecycle events on the Android platform.

Supported lifecycle events

RudderStack automatically tracks the following application lifecycle events:

info
To disable the auto-tracking of these events, set the withTrackLifecycleEvents parameter to false while initializing the Android / iOS SDK.

Application Installed

This event is triggered when a user opens an application for the first time after installation.

warning
RudderStack does not collect this event if the user does not open the app after installation.

The following properties are supported:

PropertyTypeDescription
versionStringApplication version

Here is a sample payload:

{
  "type": "track",
  "event": "Application Installed",
  "properties": {
    "version": "11.1.7"
  }
}

Application Opened

This event is triggered each time a user launches the application (except for the initial launch after installation).

The following properties are supported:

PropertyTypeDescription
from_backgroundBooleanWas the app was backgrounded initially?
url*StringDeep linking URL
referring_application*StringExternal application that referred the user to the app.
version*StringApplication version

Here is a sample payload:

{
  "userId": "1hKOmRA4el9Z",
  "type": "track",
  "event": "Application Opened",
  "properties": {
    "from_background": false,
    "referring_application": "Whatsapp",
    "url": "https://www.estore.com/best-seller/1",
    "version": "11.1.7"
  }
}
info
userId will be present only if the user is logged into the application, i.e., an identify call was previously triggered.

There are some differences in the way the RudderStack SDKs handle event properties:

Android SDK

  • The properties marked with an asterisk (url, referring_application, version) are tracked and sent only if they are available on the first launch of the application.
  • RudderStack also sends all query parameters received as a part of the deep linking URL as key-value pairs in the Application Opened event properties.

iOS SDK

  • The properties marked with an asterisk (url, referring_application, version) are tracked and sent only if they are available on every application launch.

Unity SDK

  • The properties marked with an asterisk (url, referring_application, version) are not tracked either for Android or iOS.

React Native SDK

PlatformExpected behavior
AndroidRudderStack does not track the properties marked with an asterisk (url, referring_application, version).
iOSThe properties marked with an asterisk are tracked only if they are available on every application launch.

Flutter SDK

PlatformExpected behavior
AndroidNo properties are tracked.
iOSThe properties marked with an asterisk (url, referring_application, version) are tracked only if they are available on every application launch.

Cordova SDK

PlatformExpected behavior
AndroidSame behavior as the Android SDK.
iOSSame behavior as the iOS SDK.

Application Updated

This event is triggered when a user updates their application.

The following properties are supported:

PropertyTypeDescription
previous_versionStringApplication version before update
versionStringApplication version after update

Here is a sample payload:

{
  "userId": "1hKOmRA4el9Z",
  "type": "track",
  "event": "Application Updated",
  "properties": {
    "previous_version": "11.1.7",
    "version": "12.0.1"
  }
}
info
For the Unity SDK, you need to perform additional required steps for the Android and iOS platforms to trigger the Application Updated lifecycle event.

Application Backgrounded

This event is triggered when the user backgrounds the application.

Here is a sample payload:

{
  "userId": "1hKOmRA4el9Z",
  "type": "track",
  "event": "Application Backgrounded",
  "properties": {}
}
info
RudderStack does not track any properties for this event.

FAQ

What is the format of application lifecycle events follow the standard timestamps?

The lifecycle events timestamp format is the same as Common Fields.

Do application lifecycle events include user traits or context objects?

Application lifecycle events include context objects. Note that userId will only be present if the user is logged into the application, i.e., an identify call was previously triggered.


Questions? Contact us by email or on Slack