Mobile app install and lifecycle events

Mobile lifecycle events track key moments in your app's usage: when a user installs the app, opens it, or switches away. These events help you understand user engagement patterns, measure retention, and analyze session behavior.

We recommend using the Base mobile tracking plan template for mobile tracking. It includes install and lifecycle events.

Install events

The mobile trackers can automatically track an install event when the app is first opened after installation.

This table shows the support for mobile application install tracking across the main client-side Snowplow tracker SDKs. Depending on your tracker and version, install autotracking may be enabled by default.

Tracker	Supported	Since version	Auto-tracking	Notes
Web	❌
iOS	✅	1.1.0	✅
Android	✅	1.1.0	✅
React Native	✅	0.1.0	✅	Only relevant for mobile events
Flutter	❌
Roku	❌
Google Tag Manager	❌

No uninstall events

It's not possible to track when an app is uninstalled, since the mobile platforms don't provide a callback where such an event could be tracked.

This event has no properties since the relevant data is the timestamp, which is captured in the standard event fields.

application_install

Event

Schema for an event where a mobile application is installed.

Schema URIiglu:com.snowplowanalytics.mobile/application_install/jsonschema/1-0-0

Properties and schema

Table
JSON schema

This schema has no properties.

json
{
  "$schema": "http://iglucentral.com/schemas/com.snowplowanalytics.self-desc/schema/jsonschema/1-0-0#",
  "description": "Schema for an event where a mobile application is installed.",
  "self": {
    "vendor": "com.snowplowanalytics.mobile",
    "name": "application_install",
    "format": "jsonschema",
    "version": "1-0-0"
  },
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Warehouse query

Snowflake
BigQuery
Databricks
Redshift & Postgres

sql
select
unstruct_event_com_snowplowanalytics_mobile_application_install_1 application_install_1
from
atomic.events
where
events.collector_tstamp > getdate() - interval '1 hour'
and events.event = 'unstruct'
and events.event_name = 'application_install'
and events.event_vendor = 'com.snowplowanalytics.mobile'

sql
select
unstruct_event_com_snowplowanalytics_mobile_application_install_1_0_0
from
PIPELINE_NAME.events events
where
events.collector_tstamp > timestamp_sub(current_timestamp(), interval 1 hour)
and events.event = 'unstruct'
and events.event_name = 'application_install'
and events.event_vendor = 'com.snowplowanalytics.mobile'

sql
select
unstruct_event_com_snowplowanalytics_mobile_application_install_1
from
atomic.events events
where
events.collector_tstamp > timestampadd(HOUR, -1, current_timestamp())
and events.event = 'unstruct'
and events.event_name = 'application_install'
and events.event_vendor = 'com.snowplowanalytics.mobile'
and unstruct_event_com_snowplowanalytics_mobile_application_install_1 is not null

sql
select
"application_install_1".*
from
atomic.events events
join atomic.com_snowplowanalytics_mobile_application_install_1 "application_install_1"
  on "application_install_1".root_id = events.event_id and "application_install_1".root_tstamp = events.collector_tstamp
where
events.collector_tstamp > getdate() - interval '1 hour'
and "application_install_1".root_tstamp > getdate() - interval '1 hour'
and events.event = 'unstruct'
and events.event_name = 'application_install'
and events.event_vendor = 'com.snowplowanalytics.mobile'

Android referrer details entity

On Android only, the Android tracker can attach an extra entity with install referrer information to the install event. It makes use of the Google Play Install Referrer library to retrieve the referrer information.

This entity is available from Android tracker version 5.2.0 onwards.

referrer_details

Event

Represents an install referrer details for Android apps installed from the Play Store (see https://developer.android.com/reference/com/android/installreferrer/api/ReferrerDetails)

Schema URIiglu:com.android.installreferrer.api/referrer_details/jsonschema/1-0-0

Example

json
{
  "installReferrer": "https://play.google.com/store/apps/details?id=com.example.myapp&referrer=someid%3Dsomedata",
  "referrerClickTimestamp": "2023-11-03T09:55:29.920Z",
  "installBeginTimestamp": "2023-11-03T10:55:29.920Z",
  "googlePlayInstantParam": true
}

Properties and schema

Table
JSON schema

Property	Description
`installReferrer` string	Optional. The referrer URL of the installed package
`referrerClickTimestamp` string	Optional. The timestamp when referrer click happens
`installBeginTimestamp` string	Optional. The timestamp when installation begins
`googlePlayInstantParam` boolean	Required. Boolean indicating if the user has interacted with the app's instant experience in the past 7 days

json
{
  "$schema": "http://iglucentral.com/schemas/com.snowplowanalytics.self-desc/schema/jsonschema/1-0-0#",
  "description": "Represents an install referrer details for Android apps installed from the Play Store (see https://developer.android.com/reference/com/android/installreferrer/api/ReferrerDetails)",
  "self": {
    "vendor": "com.android.installreferrer.api",
    "name": "referrer_details",
    "format": "jsonschema",
    "version": "1-0-0"
  },
  "type": "object",
  "properties": {
    "installReferrer": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 4096,
      "description": "The referrer URL of the installed package"
    },
    "referrerClickTimestamp": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "The timestamp when referrer click happens"
    },
    "installBeginTimestamp": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "The timestamp when installation begins"
    },
    "googlePlayInstantParam": {
      "type": "boolean",
      "description": "Boolean indicating if the user has interacted with the app's instant experience in the past 7 days"
    }
  },
  "required": [
    "googlePlayInstantParam"
  ],
  "additionalProperties": false
}

Warehouse query

Snowflake
BigQuery
Databricks
Redshift & Postgres

sql
select
unstruct_event_com_android_installreferrer_api_referrer_details_1 referrer_details_1
from
atomic.events
where
events.collector_tstamp > getdate() - interval '1 hour'
and events.event = 'unstruct'
and events.event_name = 'referrer_details'
and events.event_vendor = 'com.android.installreferrer.api'

sql
select
unstruct_event_com_android_installreferrer_api_referrer_details_1_0_0
from
PIPELINE_NAME.events events
where
events.collector_tstamp > timestamp_sub(current_timestamp(), interval 1 hour)
and events.event = 'unstruct'
and events.event_name = 'referrer_details'
and events.event_vendor = 'com.android.installreferrer.api'

sql
select
unstruct_event_com_android_installreferrer_api_referrer_details_1
from
atomic.events events
where
events.collector_tstamp > timestampadd(HOUR, -1, current_timestamp())
and events.event = 'unstruct'
and events.event_name = 'referrer_details'
and events.event_vendor = 'com.android.installreferrer.api'
and unstruct_event_com_android_installreferrer_api_referrer_details_1 is not null

sql
select
"referrer_details_1".*
from
atomic.events events
join atomic.com_android_installreferrer_api_referrer_details_1 "referrer_details_1"
  on "referrer_details_1".root_id = events.event_id and "referrer_details_1".root_tstamp = events.collector_tstamp
where
events.collector_tstamp > getdate() - interval '1 hour'
and "referrer_details_1".root_tstamp > getdate() - interval '1 hour'
and events.event = 'unstruct'
and events.event_name = 'referrer_details'
and events.event_vendor = 'com.android.installreferrer.api'

Foreground and background

Foreground and background events capture when the user switches to or away from your app. A foreground event fires when the app becomes visible on screen, while a background event fires when the user switches to another app or returns to the home screen.

The mobile trackers can track these events automatically. They also attach a lifecycle entity to all events, indicating whether the app was visible when each event occurred.

This table shows the support for mobile lifecycle event tracking across the main client-side Snowplow tracker SDKs. The server-side trackers don't include lifecycle event tracking. Depending on your tracker and version, lifecycle autotracking may be enabled by default.

Tracker	Supported	Since version	Auto-tracking	Notes
Web	❌
iOS	✅	3.0.0	✅
Android	✅	3.0.0	✅
React Native	✅	0.1.0	✅	Only relevant for mobile events
Flutter	✅	0.5.0	✅	Only relevant for mobile events
Roku	❌
Google Tag Manager	❌

Foreground event

The foreground event is tracked each time the app becomes visible on the screen. The foregroundIndex property counts how many times the app has been foregrounded since installation.

application_foreground

Event

Schema for an application foreground event

Schema URIiglu:com.snowplowanalytics.snowplow/application_foreground/jsonschema/1-0-0

Example

json
{
  "foregroundIndex": 1
}

Properties and schema

Table
JSON schema

Property	Description
`foregroundIndex` integer	Optional.

json
{
  "$schema": "http://iglucentral.com/schemas/com.snowplowanalytics.self-desc/schema/jsonschema/1-0-0#",
  "description": "Schema for an application foreground event",
  "self": {
    "vendor": "com.snowplowanalytics.snowplow",
    "name": "application_foreground",
    "format": "jsonschema",
    "version": "1-0-0"
  },
  "type": "object",
  "properties": {
    "foregroundIndex": {
      "type": "integer",
      "minimum": 0,
      "maximum": 2147483647
    }
  },
  "additionalProperties": false
}

Warehouse query

Snowflake
BigQuery
Databricks
Redshift & Postgres

sql
select
unstruct_event_com_snowplowanalytics_snowplow_application_foreground_1 application_foreground_1
from
atomic.events
where
events.collector_tstamp > getdate() - interval '1 hour'
and events.event = 'unstruct'
and events.event_name = 'application_foreground'
and events.event_vendor = 'com.snowplowanalytics.snowplow'

sql
select
unstruct_event_com_snowplowanalytics_snowplow_application_foreground_1_0_0
from
PIPELINE_NAME.events events
where
events.collector_tstamp > timestamp_sub(current_timestamp(), interval 1 hour)
and events.event = 'unstruct'
and events.event_name = 'application_foreground'
and events.event_vendor = 'com.snowplowanalytics.snowplow'

sql
select
unstruct_event_com_snowplowanalytics_snowplow_application_foreground_1
from
atomic.events events
where
events.collector_tstamp > timestampadd(HOUR, -1, current_timestamp())
and events.event = 'unstruct'
and events.event_name = 'application_foreground'
and events.event_vendor = 'com.snowplowanalytics.snowplow'
and unstruct_event_com_snowplowanalytics_snowplow_application_foreground_1 is not null

sql
select
"application_foreground_1".*
from
atomic.events events
join atomic.com_snowplowanalytics_snowplow_application_foreground_1 "application_foreground_1"
  on "application_foreground_1".root_id = events.event_id and "application_foreground_1".root_tstamp = events.collector_tstamp
where
events.collector_tstamp > getdate() - interval '1 hour'
and "application_foreground_1".root_tstamp > getdate() - interval '1 hour'
and events.event = 'unstruct'
and events.event_name = 'application_foreground'
and events.event_vendor = 'com.snowplowanalytics.snowplow'

Background event

The background event is tracked when the app is no longer visible, such as when the user switches to another app or returns to the home screen. The backgroundIndex property counts how many times the app has been backgrounded since installation.

application_background

Event

Schema for an application background event

Schema URIiglu:com.snowplowanalytics.snowplow/application_background/jsonschema/1-0-0

Example

json
{
  "backgroundIndex": 1
}

Properties and schema

Table
JSON schema

Property	Description
`backgroundIndex` integer	Optional.

json
{
  "$schema": "http://iglucentral.com/schemas/com.snowplowanalytics.self-desc/schema/jsonschema/1-0-0#",
  "description": "Schema for an application background event",
  "self": {
    "vendor": "com.snowplowanalytics.snowplow",
    "name": "application_background",
    "format": "jsonschema",
    "version": "1-0-0"
  },
  "type": "object",
  "properties": {
    "backgroundIndex": {
      "type": "integer",
      "minimum": 0,
      "maximum": 2147483647
    }
  },
  "additionalProperties": false
}

Warehouse query

Snowflake
BigQuery
Databricks
Redshift & Postgres

sql
select
unstruct_event_com_snowplowanalytics_snowplow_application_background_1 application_background_1
from
atomic.events
where
events.collector_tstamp > getdate() - interval '1 hour'
and events.event = 'unstruct'
and events.event_name = 'application_background'
and events.event_vendor = 'com.snowplowanalytics.snowplow'

sql
select
unstruct_event_com_snowplowanalytics_snowplow_application_background_1_0_0
from
PIPELINE_NAME.events events
where
events.collector_tstamp > timestamp_sub(current_timestamp(), interval 1 hour)
and events.event = 'unstruct'
and events.event_name = 'application_background'
and events.event_vendor = 'com.snowplowanalytics.snowplow'

sql
select
unstruct_event_com_snowplowanalytics_snowplow_application_background_1
from
atomic.events events
where
events.collector_tstamp > timestampadd(HOUR, -1, current_timestamp())
and events.event = 'unstruct'
and events.event_name = 'application_background'
and events.event_vendor = 'com.snowplowanalytics.snowplow'
and unstruct_event_com_snowplowanalytics_snowplow_application_background_1 is not null

sql
select
"application_background_1".*
from
atomic.events events
join atomic.com_snowplowanalytics_snowplow_application_background_1 "application_background_1"
  on "application_background_1".root_id = events.event_id and "application_background_1".root_tstamp = events.collector_tstamp
where
events.collector_tstamp > getdate() - interval '1 hour'
and "application_background_1".root_tstamp > getdate() - interval '1 hour'
and events.event = 'unstruct'
and events.event_name = 'application_background'
and events.event_vendor = 'com.snowplowanalytics.snowplow'

Lifecycle entity

When lifecycle autotracking is enabled, this entity is automatically attached to all events. It indicates whether the app was in the foreground or background when the event occurred.

application_lifecycle

Entity

Entity that indicates the visibility state of the app (foreground, background)

Schema URIiglu:com.snowplowanalytics.mobile/application_lifecycle/jsonschema/1-0-0

Example

json
{
  "isVisible": true,
  "index": 2
}

Properties and schema

Table
JSON schema

Property	Description
`isVisible` boolean	Required. Indicates if the app is in foreground state (true) or background state (false)
`index` integer	Optional. Represents the foreground index or background index (tracked with com.snowplowanalytics.snowplow application_foreground and application_background events.

json
{
  "$schema": "http://iglucentral.com/schemas/com.snowplowanalytics.self-desc/schema/jsonschema/1-0-0#",
  "description": "Entity that indicates the visibility state of the app (foreground, background)",
  "self": {
    "vendor": "com.snowplowanalytics.mobile",
    "name": "application_lifecycle",
    "format": "jsonschema",
    "version": "1-0-0"
  },
  "type": "object",
  "properties": {
    "isVisible": {
      "description": "Indicates if the app is in foreground state (true) or background state (false)",
      "type": "boolean"
    },
    "index": {
      "description": "Represents the foreground index or background index (tracked with com.snowplowanalytics.snowplow application_foreground and application_background events.",
      "type": "integer",
      "minimum": 0,
      "maximum": 2147483647
    }
  },
  "required": [
    "isVisible"
  ],
  "additionalProperties": false
}

Install events​

application_install

Android referrer details entity​

referrer_details

Foreground and background​

Foreground event​

application_foreground

Background event​

application_background

Lifecycle entity​

application_lifecycle

Want to see a custom demo?

Install events

Android referrer details entity

Foreground and background

Foreground event

Background event

Lifecycle entity