Mobile app lifecycle events

How it works

Our Mobile App Lifecycle Event specification helps you send events in a uniform format that automatically maps data to the integrations we support. Following this spec makes it easier to use data from your mobile apps without having to re-map your incoming data each time you set up a new integration.

These events typically contain information about your app version and build. If you use our SDKs, we capture some of the following events automatically. Some, like Application Crashed, are events you’ll send manually.

Our mobile SDKs send lifecycle events automatically

If you use one of our mobile SDKs, we automatically capture the following events by default.

• Application Installed
• Application Opened
• Application Backgrounded
• Application Foregrounded
• Application Updated

These events can help you understand your customer’s lifecycle—like the time they spend in the app (time from opened to backgrounded), how often they update the app, and so on.

You’ll notice that our mobile SDKs don’t capture events like Application Crashed automatically. That’s because the app must be open for us to send events from your app to Customer.io.

These are the minimum required versions of our mobile SDKs to capture application lifecycle events. If you’re running an earlier version, update the SDK to take advantage of these events and other features!

Application Installed

Our CDP-enabled SDKs send this event the first time a user opens your application. If the user never opens your app, we won’t be able to collect this event. This event doesn’t wait for the SDK to capture attribution or automation information, and is collected automatically. Platforms like Facebook and Google require discrete install events to correctly attribute installs to ads served through their platforms.

{
  "userId": "019mr8mf4r",
  "type": "track",
  "event": "Application Installed",
  "properties": {
    "version": "1.2.3", "build": "1234"
  }
}

Application Opened

Send this event when a user launches your mobile application—after the first open. The first open results in an Application Installed event, so we only send this event on subsequent opens. Like the Application Installed event, this event also does not wait for the SDK to capture attribution information but it can include information about referring applications or deep link URLs if available when the app opens.

{
  "userId": "019mr8mf4r",
  "type": "track",
  "event": "Application Opened",
  "properties": {
    "from_background": false,
    "referring_application": "GMail",
    "url": "url://location"
  }
}

Application Backgrounded

Send this event when a user backgrounds the application upon applicationDidEnterBackground ↗.

{
  "userId": "019mr8mf4r",
  "type": "track",
  "event": "Application Backgrounded",
  "properties": {}
}

Application Foregrounded

Send this event when your audience returns to your app after previously backgrounding it. This event is distinct from Application Opened in that the app is considered opened already, even if it’s in the background.

{
  "userId": "019mr8mf4r",
  "type": "track",
  "event": "Application Foregrounded",
  "properties": {}
}

Application Updated

This event fires when the user opens your app after updating your app. Our CDP-enabled SDKs automatically collect this event rather than the “Application Opened” event after someone updates your app.

{
  "userId": "019mr8mf4r",
  "type": "track",
  "event": "Application Updated",
  "properties": {
    "previous_version": "1.1.2",
    "previous_build": "1234",
    "version": "1.2.0",
    "build": "1456"
  }
}

Application Uninstalled

You can send this event when a user uninstalls your app. Like similar events that happen outside of your app itself, our CDP-enabled SDKs cannot capture this event automatically.

However, some direct-mode destinations detect this for you using silent push notifications through their own SDKs. You might also be able to send these events to Customer.io using callbacks.

{
  "userId": "019mr8mf4r",
  "type": "track",
  "event": "Application Uninstalled",
  "properties": {}
}

Application Crashed

You can send this event when you receive a crash notification from your app, but it is not meant to supplant traditional crash reporting tools. By tracking crashes this way, you can analyze which types of users are impacted by crashes and how those crashes affect their engagement. You may also want to send messages to users who experience crashes through other messaging channels.

Like similar events that happen outside of your app itself, our CDP-enabled SDKs cannot capture this event automatically. But you might be able to capture this kind of event with a callback or a webhook.

{
  "userId": "019mr8mf4r",
  "type": "track",
  "event": "Application Crashed",
  "properties": {}
}