Native Mobile Spec

The Segment Native Mobile Spec includes the following semantic events:

Application Lifecycle Events

• Application Installed
• Application Opened
• Application Backgrounded
• Application Foregrounded
• Application Updated
• Application Uninstalled
• Application Crashed

Campaign Events

• Install Attributed
• Push Notification Received
• Push Notification Tapped
• Push Notification Bounced
• Deep Link Opened
• Deep Link Clicked

Segment recommends using the above event names if you're going to be integrating the events yourself. This will ensure that they can be mapped effectively in downstream tools.

Mobile applications live within a fairly bounded lifecycle. To understand and communicate effectively with your users, it's crucial to instrument the core flows associated with installing and opening your app. The following events allow you to get a picture of top-line metrics such as DAUs, MAUs, and Screen Views per session. Automatic lifecycle event tracking is optional - you can learn how to enable and disable them in Segment's docs for each library below:

• iOS
• Swift
• Android
• Kotlin
• React Native

The following events will be tracked automatically when lifecycle events are enabled in all mobile libraries:

• Application Installed
• Application Opened
• Application Updated

In Kotlin, Swift, and React Native, the following additional events are tracked:

• Application Backgrounded

In Swift, the following event is also tracked:

• Application Foregrounded

This event fires when a user first opens your mobile application. If the user never opens your app after installing, Segment will not collect this event. This event doesn't wait for attribution or campaign information to be received, and is collected automatically by Segment's SDKs. Advertising providers like Facebook and Google require discrete install events to correctly attribute installs to ads served through their platform.

1
{
2
  "userId": "019mr8mf4r",
3
  "type": "track",
4
  "event": "Application Installed",
5
  "properties": {
6
    "version": "1.2.3", "build": "1234"
7
  }
8
}

This event fires when a user launches or foregrounds your mobile application after the first open. It will fire after the Application Installed event and again after the app is re-opened after being closed. This event does not wait for attribution information to be received, but may include information about referring applications or deep link URLs if available to the application upon open.

1
{
2
  "userId": "019mr8mf4r",
3
  "type": "track",
4
  "event": "Application Opened",
5
  "properties": {
6
    "from_background": false,
7
    "referring_application": "GMail",
8
    "url": "url://location"
9
  }
10
}

This event should be sent when a user backgrounds the application upon applicationDidEnterBackground.

1
{
2
  "userId": "019mr8mf4r",
3
  "type": "track",
4
  "event": "Application Backgrounded",
5
  "properties": {}
6
}

This event is fired when a user opens the app or brings it back into the foreground of their device. This is only collected by the Swift library.

1
{
2
  "userId": "019mr8mf4r",
3
  "type": "track",
4
  "event": "Application Foregrounded",
5
  "properties": {}
6
}

This event fires when a user updates the application. Segment's SDK will automatically collect this event instead of an "Application Opened" event when we determine that the Open is first since an update.

1
{
2
  "userId": "019mr8mf4r",
3
  "type": "track",
4
  "event": "Application Updated",
5
  "properties": {
6
    "previous_version": "1.1.2",
7
    "previous_build": "1234",
8
    "version": "1.2.0",
9
    "build": "1456"
10
  }
11
}

Fire this event when a user uninstalls the application. Some destination partners will detect this for you using Silent Push Notifications through their SDK. Visit the documentation for your destination to see if this is available. If supported, you might be able to send these events to Segment using a callback.

1
{
2
  "userId": "019mr8mf4r",
3
  "type": "track",
4
  "event": "Application Uninstalled",
5
  "properties": {}
6
}

You can send this event when you receive a crash notification from your app, but it is not meant to replace traditional crash reporting tools. By tracking crashes as an analytics event with device and user information, you can analyze the which types of users are impacted by crashes and how those crashes, in turn, affect their engagement. You may also want to target those customers with tailored communications in other channels if they've encountered several crashes. Segment does not collect this event. To capture the event, use a destination that collects this data and route that event back to Segment through a webhook or other callback.

1
{
2
  "userId": "019mr8mf4r",
3
  "type": "track",
4
  "event": "Application Crashed",
5
  "properties": {}
6
}

As the walls between apps become increasingly lowered, capturing information about the content and campaigns that drive users to engage with your app is critical to building more targeted, relevant, personalized experiences for your users.

Segment does not collect any campaign events automatically unless configured to do so.

When Segment or an integrated partner can discern the source of an install, we'll collect an Install Attributed event. This event may be sent to Segment using server-to-server connection from your attribution provider, or directly on the device using packaged destinations. In either case, this will happen after install, and does not apply to all installs, which is why it is a discrete event.

1
{
2
  "userId": "019mr8mf4r",
3
  "type": "track",
4
  "event": "Install Attributed",
5
  "properties": {
6
    "provider": "Tune/Kochava/Branch/AppsFlyer",
7
    "campaign": {
8
      "source": "Network/FB/AdWords/MoPub/Source",
9
      "name": "Campaign Name",
10
      "content": "Organic Content Title",
11
      "ad_creative": "Red Hello World Ad",
12
      "ad_group": "Red Ones"
13
    }
14
  }
15
}

This event can be sent when a push notification is received in the app. It can be automatically enabled on iOS.

1
{
2
  "userId": "019mr8mf4r",
3
  "type": "track",
4
  "event": "Push Notification Received",
5
  "properties": {
6
    "campaign": {
7
      "medium": "Push",
8
      "source": "Vendor Name",
9
      "name": "Referral Flow",
10
      "content": "Your friend invited you to play a match."
11
    }
12
  }
13
}

This event can be sent when a user taps on a push notification associated with your app. It can be automatically enabled on iOS.

1
{
2
  "userId": "019mr8mf4r",
3
  "type": "track",
4
  "event": "Push Notification Tapped",
5
  "properties": {
6
    "action": "Accept",
7
    "campaign": {
8
      "medium": "Push",
9
      "source": "Vendor Name",
10
      "name": "Referral Flow",
11
      "content": "Your friend invited you to play a match."
12
    }
13
  }
14
}

This event fires when a push notification from a provider bounces. If your push notification provider forwards push lifecycle events to Segment, they should include this event in their suite.

1
{
2
  "userId": "019mr8mf4r",
3
  "type": "track",
4
  "event":"Push Notification Bounced",
5
  "properties": {
6
    "action": "Accept",
7
    "campaign": {
8
      "medium": "Push",
9
      "source": "Vendor Name",
10
      "name": "Referral Flow",
11
      "content": "Your friend invited you to play a match."
12
    }
13
  }
14
}

When your application is opened using a referring link, Segment or your packaged deep link partner can fire this event on your behalf. If the deep link has additional data associated with it, either passed through the third party service or as annotations in launchOption, you may want to include those values as properties here as well.

This event is fired in addition to the associated Application Opened event.

1
{
2
  "userId": "019mr8mf4r",
3
  "type": "track",
4
  "event": "Deep Link Opened",
5
  "properties": {
6
    "provider": "Branch Metrics",
7
    "url": "app://landing"
8
  }
9
}

This event may be provided by deep link providers postback mechanisms or an internal redirect service if you use one in order to provide a waypoint funnel step between your content or advertisement and the resulting app open.

1
{
2
  "userId": "019mr8mf4r",
3
  "type": "track",
4
  "event": "Deep Link Clicked",
5
  "properties": {
6
    "provider": "Branch Metrics",
7
    "url": "brnch.io/1234"
8
  }
9
}