Customer.io

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 that have 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 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 profile 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 profile performing the event, but the source of the call. The example below shows the full payload as you’ll see it in Customer.io.

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
}
One of:
  • userIdstringrequired
    The unique identifier for a person. This value should be unique across systems, so you recognize the same person in your sources _and_ destinations.
  • typestring
    The event type. This is set automatically by the request method/endpoint.
    Accepted values: screen
  • namestringrequired
    The name of the screen the person visited.
  • propertiesobject
    Additional properties for your screen.
  • Contains a list of booleans indicating the integrations that are enabled (true) or disabled (false). By default, all integrations are enabled (returning an empty object). Set "All": false to reverse this behavior.
  • messageIdstring
    A unique identifier for a Data Pipelines call, ensuring that each individual event is unique. This is set by Customer.io
  • receivedAtstring(date-time)
    The ISO-8601 timestamp when Data Pipelines receives an event.
  • sentAtstring(date-time)
    The ISO-8601 timestamp when a library sends an event to Data Pipelines.
  • timestampstring(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.
  • versionnumber
    The version of the API that received the event, automatically set by Customer.io.
  • A dictionary of context about a source call/event, like the user’s IP address or locale. Context is automatically collected by our source libraries.