Screen

How it works

The screen method represents screenviews in your mobile apps—like a page call, but specifically for apps. It helps you record the screens that people visit as they use your app. By recording screen events, you can better understand the parts of your app that people use. You might even follow up with people who’ve visited particular screens to see if they’re still interested in a product, need help with something, and so on.

 See our API documentation for code samples

This page can help you better understand when and how to use this API method. But, if you already know how it works and are ready to get started, you can go straight to our Data Pipelines API documentation and start writing code.

A typical call

A screen call is relatively straightforward. It contains a userId and a name for the screen. The userId is a unique identifier for the person viewing the screen. The name is the screen the person viewed.

You can also send properties with any screen event. These are just additional details about the screen that you want to know about in your downstream destinations. For example, if you have a screen that shows a list of items, you might send the number of items in the list as a property.

{
  "type": "screen",
  "userId": "97980cfea0067",
  "name": "Activity Feed",
  "properties": {
    "Feed Type": "public"
  }
}

The full payload

While your requests are typically short, our libraries capture much more information. This helps us provide context, not only for the person performing the event, but the source of the call. The example below shows the full payload as you’ll see it in Data Pipelines.

Customer.io and our libraries typically populate integrations and timestamp values as shown in the payload below. If you use our JavaScript or mobile libraries, they’ll also populate context for you. If you use our server-side libraries, you’ll need to populate context yourself.

See common fields for more information about context, integrations, and timestamps in source payloads.

{
  "userId": "97980cfea0067",
  "name": "feed",
  "properties": {
    "feed_count": 45,
    "unseen_count": 10,
    "subscriptions": [
      "baseball",
      "basketball"
    ]
  },
  "integrations": {
    "All": true
  },
  "messageId": "022bb90c-bbac-11e4-8dfc-aa07a5b093db",
  "timestamp": "2015-02-23T22:28:55.111Z",
  "context": {
    "active": true,
    "ip": "8.8.8.8",
    "locale": "string",
    "userAgent": "string",
    "channel": "browser",
    "app": {
      "name": "string",
      "version": "string",
      "build": "string",
      "namespace": "string"
    },
    "device": {
      "id": "string",
      "advertisingId": "string",
      "manufacturer": "string",
      "model": "string",
      "name": "string",
      "type": "android",
      "version": "string"
    },
    "network": {
      "bluetooth": true,
      "carrier": "string",
      "cellular": true,
      "wifi": true
    },
    "os": {
      "name": "string",
      "version": "string"
    }
  },
  "anonymousId": "507f191e810c19729de860ea",
  "receivedAt": "2015-02-23T22:28:55.387Z",
  "sentAt": "2015-02-23T22:28:55.111Z",
  "type": "screen",
  "version": 1.1
}
  • name string
    The name of the screen the person visited.
    • Screen Properties* any type
  • type string
    The event type. This is set automatically by the request method/endpoint.

    Accepted values:screen

  • userId string
    Required The unique identifier for a person. This value should be unique across systems, so you recognize the same person in your sources and destinations.
      • Enabled/Disabled integrations* boolean
    • messageId string
      A unique identifier for a Data Pipelines call, ensuring that each individual event is unique. This is set by Customer.io
    • originalTimestamp string  (date-time)
    • receivedAt string  (date-time)
      The ISO-8601 timestamp when Data Pipelines receives an event.
    • sentAt string  (date-time)
      The ISO-8601 timestamp when a library sends an event to Data Pipelines.
    • timestamp string  (date-time)
      The ISO-8601 timestamp when the event originally took place. This is mostly useful when you backfill data past events. If you’re not backfilling data, you can leave this field empty and we’ll use the current time or server time.
    • type string
      The type of source event. This is implicit and set by Customer.io based on the endpoint/method you use (e.g. identify).

      Accepted values:identify,group,track,page,screen,alias

    • version number
      The version of the API that received the event, automatically set by Customer.io.
      • active boolean

        Whether a user is active.

        This is usually used to flag an .identify() call to just update the traits but not “last seen.”

      • channel string
        The channel the event originated from.

        Accepted values:browser,server,mobile

      • ip string
        The user’s IP address. This isn’t captured by our libraries, but by our servers when we receive client-side events (like from our JavaScript source).
      • locale string
        The local string for the current user, e.g. en-US.
      • userAgent string
        The user agent of the device making the request
        • build string
          The specific build number in the app.
        • name string
          The name of the app.
        • namespace string
          The app’s namespace.
        • version string
          The version of the app the call originated from.
        • advertisingId string
          The advertising ID is a unique, anonymous ID for advertising.
        • id string
          The device ID.
        • manufacturer string
          The device manufacturer.
        • model string
          The device model.
        • name string
          The device name.
        • type string
          The device type—android, iOS, etc.

          Accepted values:android,ios

        • version string
          The firmware version for the device.
        • bluetooth boolean
          Lets you know if bluetooth is enabled on a device.
        • carrier string
          The cellular carrier the phone uses.
        • cellular boolean
          Indicates whether the device’s cellular connection is enabled or not.
        • wifi boolean
          Indicates whether a device’s wifi connection is enabled or not.
        • name string
          The operating system running on the device.
        • version string
          The version of the OS running on the device.

Screen calls with our mobile libraries

Our mobile libraries use the Journeys Track API. If you enable Journeys as a source, we’ll convert these calls to the shape used by Data Pipelines. This allows you to send data to Data Pipelines from our mobile libraries without any additional work.

Because we automatically track screens from our mobile libraries, this saves you the trouble of writing your own code and calls.

Copied to clipboard!
  Contents
Is this page helpful?