Mobile Application Lifecycle Events Spec

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

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 (Java) / iOS (Obj-C) SDK.

Application Installed

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

Note that:

• RudderStack does not collect this event if you not open the app after installation.
• This event fires only on a fresh install — if you reinstall the app without uninstalling it first (and the build number increases), RudderStack triggers the Application Updated event instead.
• If you uninstall the app and then reinstall it, the Application Installed event fires again once you open the app.

This event supports the following properties:

A sample payload for the Application Installed event is shown below:

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

Application Opened

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

This event supports the following properties:

A sample payload for the Application Opened event is shown below:

{
  "userId": "1hKOmRA4el9Z",
  "type": "track",
  "event": "Application Opened",
  "properties": {
    "from_background": false,
    "referring_application": "Whatsapp",
    "url": "https://www.example.com/best-seller/1",
    "version": "11.1.7"
  }
}

userId will be present only if the user is logged into the application, that is, an identify call was previously made for the user.

Note that there are some differences in the way the RudderStack SDKs handle event properties:

Android (Java) 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 (Obj-C) 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

Flutter SDK

Cordova SDK

Application Updated

The Application Updated event is triggered when a user updates their application.

This event supports the following properties:

A sample payload for the Application Updated event is shown below:

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

For the Unity SDK, you need to perform some additional steps for Android and iOS platforms to trigger the Application Updated lifecycle event.

Application Backgrounded

The Application Backgrounded event is triggered when the user backgrounds the application.

A sample payload for the Application Backgrounded event is shown below:

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

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.

Does the Application Installed event fire only on a fresh install?

Yes, the Application Installed event fires only on a fresh install.

If you reinstall the app without uninstalling it first (and the build number increases), RudderStack triggers the Application Updated event instead.

However, if you uninstall the app and then reinstall it, the Application Installed event will fire again once you open the app.

Questions? Contact us by Email or on Slack