> For the complete documentation index, see [llms.txt](https://rudderlabs.gitbook.io/rudderlabs-1/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rudderlabs.gitbook.io/rudderlabs-1/docs/rudderstack-api/api-specification/application-lifecycle-events-spec.md).

# Application Lifecycle Events Specification

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](https://www.rudderstack.com/docs/stream-sources/rudderstack-sdk-integration-guides/rudderstack-unity-sdk/#tracking-application-lifecycle-events-on-the-android-platform) section.

## Supported lifecycle events

RudderStack **automatically tracks** the following application lifecycle events:

* [Application Installed](#application-installed)
* [Application Opened](#application-opened)
* [Application Updated](#application-updated)
* [Application Backgrounded](#application-backgrounded)

To disable the auto-tracking of these events, set the `withTrackLifecycleEvents` parameter to `false` while initializing the [Android](https://www.rudderstack.com/docs/stream-sources/rudderstack-sdk-integration-guides/rudderstack-android-sdk/#initializing-the-rudderstack-client) / [iOS](https://www.rudderstack.com/docs/stream-sources/rudderstack-sdk-integration-guides/rudderstack-ios-sdk/#initializing-the-rudderstack-client) 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:

```json
{
  "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:

```json
{
  "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](#android-sdk). |
| iOS      | Same behavior as the [iOS SDK](#ios-sdk).         |

## Application Updated

This event is fired when a user updates their application.

A sample payload is shown below:

```json
{
  "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](https://www.rudderstack.com/docs/stream-sources/rudderstack-sdk-integration-guides/rudderstack-unity-sdk/#triggering-application-updated-lifecycle-event) section.

## Application Backgrounded

This event is fired when the user backgrounds the application.

A sample payload is shown below:

```json
{
  "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](https://www.rudderstack.com/docs/rudderstack-api/api-specification/rudderstack-spec/common-fields/).

### 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](mailto:%20docs@rudderstack.com) or start a conversation in our [Slack](https://rudderstack.com/join-rudderstack-slack-community) community.