Mobile app install and lifecycle events

Mobile app usage lifecycle consists of several events that are important to understand how a user uses an app. These are the app install, foreground, and background events.

The app install event is tracked the first time the app is opened after installation. The background and foreground events are tracked when the user moves the app to background and foreground (the app becomes visible on the screen again). These events can be tracked automatically by our mobile trackers if configured to do so. Additionaly, the tracker attaches a LifecycleEntity to all the events tracked by the tracker reporting if the app was visible (foreground state) when the event was tracked.

note

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

• Install event
• Foreground event
• Background event
• Lifecycle context entity
• How to track?

Install event

Event: application_install

Schema for an event where a mobile application is installed.

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

Web	Mobile	Tracked automatically
❌	✅	✅

👀 Example

{}

📃 Schema properties definition

Table

Property	Type	Description	Required?

JSON schema

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

❓ How to query the event in the warehouse?

Snowflake

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'

BigQuery

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'

Databricks

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

Redshift & Postgres

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 context entity

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

Event: referrer_details

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 URI: iglu://com.android.installreferrer.api/referrer_details/jsonschema/1-0-0

Web	Mobile	Tracked automatically
❌	✅	✅

👀 Example

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

📃 Schema properties definition

Table

Property	Type	Description	Required?
installReferrer	["string","null"]	The referrer URL of the installed package	❌
referrerClickTimestamp	["string","null"]	The timestamp when referrer click happens	❌
installBeginTimestamp	["string","null"]	The timestamp when installation begins	❌
googlePlayInstantParam	"boolean"	Boolean indicating if the user has interacted with the app's instant experience in the past 7 days	✅

JSON schema

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

❓ How to query the event in the warehouse?

Snowflake

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'

BigQuery

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'

Databricks

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

Redshift & Postgres

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'

How to track?

See the documentation for the Android tracker for more information how to track the entity.

Foreground event

Event: application_foreground

Schema for an application foreground event

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

Web	Mobile	Tracked automatically
❌	✅	✅

👀 Example

{
  "foregroundIndex": 1
}

📃 Schema properties definition

Table

Property	Type	Description	Required?
foregroundIndex	"integer"		❌

JSON schema

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

❓ How to query the event in the warehouse?

Snowflake

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'

BigQuery

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'

Databricks

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

Redshift & Postgres

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

Event: application_background

Schema for an application background event

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

Web	Mobile	Tracked automatically
❌	✅	✅

👀 Example

{
  "backgroundIndex": 1
}

📃 Schema properties definition

Table

Property	Type	Description	Required?
backgroundIndex	"integer"		❌

JSON schema

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

❓ How to query the event in the warehouse?

Snowflake

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'

BigQuery

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'

Databricks

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

Redshift & Postgres

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 context entity

Context entity: application_lifecycle

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

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

Web	Mobile	Tracked automatically
❌	✅	✅

👀 Example

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

📃 Schema properties definition

Table

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

JSON schema

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

How to track?

• iOS and Android tracker documentation.
• React Native tracker documentation.