# Screen

## How it works[](#how-it-works)

The `screen` method represents screenviews in your mobile apps—like a [page call](/integrations/data-in/source-spec/page-spec), 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 [API documentation](/integrations/api/cdp) and start writing code.

## A typical call[](#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.

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

## The full payload[](#complete-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 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](/integrations/data-in/source-spec/common-fields) for more information about context, integrations, and timestamps in source payloads.

```json
{
  "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
}
```

*   messageId string
    
    A unique identifier for a Data Pipelines call, ensuring that each individual event is unique. This is set by Customer.io
    
*   name string
    
    Required The name of the screen the person visited.
    
*   properties object
    
    Additional properties for your screen.
    
*   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`
    
*   version number
    
    The version of the API that received the event, automatically set by Customer.io.
    

*   messageId string
    
    A unique identifier for a Data Pipelines call, ensuring that each individual event is unique. This is set by Customer.io.
    
*   name string
    
    Required The name of the screen the person visited.
    
*   properties object
    
    Additional properties for your screen.
    
*   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`
    
*   version number
    
    The version of the API that received the event, automatically set by Customer.io.