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. 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": [
  "integrations": {
    "All": true
  "messageId": "022bb90c-bbac-11e4-8dfc-aa07a5b093db",
  "timestamp": "2015-02-23T22:28:55.111Z",
  "context": {
    "active": true,
    "ip": "",
    "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
    • active boolean

      Whether a user is active.

      This is usually used when you send an .identify() call to update the traits independently of when you’ve “last seen” a user.

    • 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 locale 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.
    • 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
  • name string
    Required The name of the screen the person visited.
  • 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 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.
  • version number
    The version of the API that received the event, automatically set by

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!
Is this page helpful?
Chat with AI