Application Lifecycle Events Specification

Detailed technical description of the various application lifecycle events tracked by the 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.

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 the Tracking application lifecycle events on the Android platform section.

Supported lifecycle events

RudderStack automatically tracks the following application lifecycle events:

• Application Installed

• Application Opened

• Application Updated

• Application Backgrounded

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 fired when a user opens an application for the first time after installation.

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

A sample payload is shown below:

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

RudderStack tracks the following properties for this event:

Property	Type	Description
version	String	The version of the installed application.

Application Opened

This event is fired when a user launches an application after the first launch and subsequently every time the app is reopened after it is closed or backgrounded.

A sample payload is shown below:

{
  "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"
  }
}

userId will be present only if the user is logged into the application, i.e. an identify call is made previously.

RudderStack tracks the following properties for this event:

Property	Type	Description
from_background	Boolean	Determines if the app was backgrounded initially or if it is a fresh open.
url*	String	The deep linking URL with which the user was directed into the app.
referring_application*	String	The external application from which the user was referred to the app.
version*	String	The version of the installed application.

There are some differences in the way the RudderStack SDKs handle the above 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 the 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

Platform	Expected behavior
Android	RudderStack does not track the properties marked with an asterisk (url, referring_application, version).
iOS	The properties marked with an asterisk are tracked only if they are available on every application launch.

Flutter SDK

Platform	Expected behavior
Android	No properties are tracked.
iOS	The properties marked with an asterisk (url, referring_application, version) are tracked only if they are available on every application launch.

Cordova SDK

Platform	Expected behavior
Android	Same behavior as the Android SDK.
iOS	Same behavior as the iOS SDK.

Application Updated

This event is fired when a user updates their application.

A sample payload is shown below:

{
  "userId": "1hKOmRA4el9Z",
  "type": "track",
  "event": "Application Updated",
  "properties": {
    "previous_version": "11.1.7",
    "version": "12.0.1"
  }
}

RudderStack tracks the following properties for this event:

Property	Type	Description
previous_version	String	The application version before it was updated.
version	String	The current version of the application after it is updated.

For the Unity SDK, you need to perform the required steps for the Android and iOS platforms to trigger the Application Updated lifecycle event. For more information on these steps, refer to the Triggering Application Updated lifecycle event section.

Application Backgrounded

This event is fired when the user backgrounds the application.

A sample payload is shown below:

{
  "userId": "1hKOmRA4el9Z",
  "type": "track",
  "event": "Application Backgrounded",
  "properties": {}
}

RudderStack does not track any properties for this event.

FAQ

Do the application lifecycle events follow the standard timestamping format?

Yes, the lifecycle events follow the timestamp format in accordance with the RudderStack API Spec.

Do the lifecycle events include the user traits or context objects?

The application lifecycle events include the context objects. Note that userId would be present only if the user is logged into the application, i.e. an identify call is made previously.

Contact us

For more information on any of the sections covered in this guide, you can contact us or start a conversation in our Slack community.