# 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.

{{< info >}}
To track application lifecycle events in Android apps using the Unity SDK, you need to perform some additional steps — refer to [Tracking application lifecycle events on the Android platform]({{< ref "sources/event-streams/sdks/rudderstack-unity-sdk/v1.md#tracking-application-lifecycle-events-on-the-android-platform" >}}) for more information.
{{< /info >}}


## 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)

{{< tip >}}
To disable the auto-tracking of these events, set the `withTrackLifecycleEvents` parameter to `false` while initializing the [Android (Java)]({{< ref "sources/event-streams/sdks/rudderstack-android-sdk/_index.md" >}}) / [iOS (Obj-C)]({{< ref "sources/event-streams/sdks/rudderstack-ios-sdk/" >}}) SDK.
{{< /tip >}}

## 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](#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:

| Property | Type | Description |
| :--------| :-----| :------------|
| `version` | String | Application version |
| `build` | Number | Application build number |

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

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

This event supports the following properties:

| Property | Type | <div style="width: 300px;">Description</div> |
| :--------| :-----| :------------|
| `from_background` | Boolean | Determines if the app was backgrounded initially |
| `version` | String | Application version <br /><br />{{< info >}}This property is included only on the first `Application Opened` event after app launch. It is omitted when the event fires on subsequent returns from the background.{{< /info >}} |
| `url`* | String | Deep linking URL  |
| `referring_application`* | String | External application that referred the user to the app |

Note the following regarding the above properties marked with an asterisk (*):

- These properties are supported only in the [React Native iOS]({{< ref "sources/event-streams/sdks/rudderstack-react-native-sdk.md" >}}), [Flutter iOS]({{< ref "sources/event-streams/sdks/rudderstack-flutter-sdk/" >}}), and {{< legacy-tooltip "ios-objc" >}}.
- They require the legacy `AppDelegate` architecture and work by default in iOS 12 or iOS 13+ (with `SceneDelegate` disabled, by removing `UIApplicationSceneManifest` from the `Info.plist` file). They are not supported in the iOS 13+ apps using `SceneDelegate`.
- These properties are not supported in the new [iOS (Swift)]({{< ref "sources/event-streams/sdks/swift-sdk/" >}}), [Android (Kotlin)]({{< ref "sources/event-streams/sdks/kotlin-sdk/" >}}), and {{< legacy-tooltip "android-java" >}}.

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

```json
{
  "userId": "1hKOmRA4el9Z",
  "type": "track",
  "event": "Application Opened",
  "properties": {
    "from_background": false,
    "version": "11.1.7"
  }
}
```

{{< info >}}
`userId` is present only if the user is logged into the application, that is, an [`identify`]({{< ref "event-spec/standard-events/identify.md" >}}) call was previously made for the user.
{{< /info >}}

## Application Updated

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

This event supports the following properties:

| Property | Type | Description |
| :--------| :-----| :------------|
| `previous_version` | String | Application version before update  |
| `version` | String | Application version after update |
| `build` | Number | Application build number after update |
| `previous_build` | Number | Application build number before update |

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

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

{{< info >}}
For the Unity SDK, you need to perform some [additional steps]({{< ref "sources/event-streams/sdks/rudderstack-unity-sdk/v1.md#triggering-application-updated-lifecycle-event" >}}) for Android and iOS platforms to trigger the **Application Updated** lifecycle event.
{{< /info >}}

## 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:

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

{{< info >}}
RudderStack does not track any properties for this event.
{{< /info >}}

## FAQ 

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

The lifecycle events timestamp format is the same as [Common Fields]({{< ref "event-spec/standard-events/common-fields.md" >}}).

#### 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]({{< ref "event-spec/standard-events/identify.md" >}}) 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](#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.

<br />