Event: Screen

The screen method can record whenever a user sees a screen, the mobile equivalent of page, in your mobile app, along with any properties about the screen.

How to make a screen call

You can call screen or page using one of our data tracking libraries.

Here’s the payload of a typical screen call, without any common field:

{
  "type": "screen",
  "name": "Dashboard",
  "properties": {
    "tab": "Advanced Stats"
  }
}

Screen fields

Beyond the common fields, the screen call takes the following fields:

FieldTypeDescription
name optionalStringName of the screen. See the Name field docs for more detail.
properties optionalObjectFree-form dictionary of properties of the screen, like name. See the Properties field docs for a list of reserved property names.
category optionalStringThe category of the page. Useful for things like ecommerce where many pages often live under a larger category.

Identities

The User ID is a unique identifier for the user performing the actions. Check out the User ID docs for more detail.

The Anonymous ID can be any pseudo-unique identifier, for cases where you don’t know who the user is, but you still want to tie them to an event. Check out the Anonymous ID docs for more detail.

Note: In our browser and mobile libraries a User ID is automatically added from the state stored by a previous identify call, so you do not need to add it yourself. They will also automatically handle Anonymous ID’s under the covers.

Name

Each screen can be tagged with an optional name. For example, many apps have a “Signup” screen that can be useful to tag so that you can see users as they move through your funnel.

Properties and reserved keywords

Properties are extra pieces of information that describe the screen. They can be anything you want.

We’ve reserved some properties that have semantic meanings, and we handle them in special ways.

You must only use reserved properties for their intended meaning.

Reserved properties we have standardized:

PropertyTypeDescription
nameStringName of the screen.
category optionalStringThe category of the page. Useful for things like ecommerce where many pages often live under a larger category.

Example

Here’s a complete example of a screen call:

{
  "anonymousId": "f9ecad88-7bcb-411b-bcdd-fd048b27d691",
  "channel": "mobile",
  "context": {
    "ip": "8.8.8.8"
  },
  "messageId": "c6e8b2a4-f428-43a1-b396-bf6a60319797",
  "name": "Home",
  "category": "cornestone-pages",
  "properties": {
    "variation": "no advanced stats"
  },
  "receivedAt": "2017-02-09T12:08:32.387Z",
  "sentAt": "2017-02-23T22:28:55.111Z",
  "timestamp": "2017-02-23T22:28:55.111Z",
  "type": "screen",
  "userId": "97980cfea0067",
  "version": "1.1"
}

Not using Plainflow yet? Get your free account here. 👈