Page

How it works

The page method represents pageviews. It helps you record the pages that people visit on your website. By recording page events, you can better understand the parts of your website that people use. You might even follow up with people who have visited particular pages to see if they’re still interested in a product, online class, and so on.

Our JavaScript client automatically captures page events on load, but you’ll need to invoke page calls manually if you use our server-side libraries, you have a single page app, or you want to augment the call with special properties. You’ll also send your own page calls if you use one of our server-side libraries.

A typical call

The page method changes significantly depending on whether you use our JavaScript client or send page calls another way.

If you use the JavaScript client, we’ll automatically capture page events on page load with the page URL and other common properties. You can invoke page calls manually if you have a single page app or want to override properties that we typically capture. By default, the call is simply cioanalytics.page(). You can also send the page category, name, and so on. But, in general, page calls are relatively straightforward and, more importantly, automatic.

If you use one of our server-side libraries (NodeJS, Python, and Go), you’ll need to send your own page calls. You’ll need to include a userId or anonymousId in your call, and you can also include a properties object with information about the page—including a number of reserved properties that we’ve enumerated below. Below is an example from our NodeJS library, but you should check the documentation for the SDK you install for more information about the page method.

cioanalytics.page({
  userId: '019mr8mf4r',
  category: 'Docs',
  name: 'Customer.io Pipelines',
  properties: {
    url: 'https://customer.io/cdp/',
    path: '/cdp/',
    title: 'Pipelines',
    referrer: 'https://customer.io'
  }
});

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 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",
  "type": "page",
  "name": "Home",
  "properties": {
    "category": "string",
    "url": "https://www.example.com/page",
    "title": "Welcome | ACME, Inc.",
    "referrer": "http://www.google.com/search/?q=sfgiants",
    "path": "/page",
    "search": "?q=sfgiants"
  },
  "integrations": {
    "All": true
  },
  "messageId": "022bb90c-bbac-11e4-8dfc-aa07a5b093db",
  "receivedAt": "2015-02-23T22:28:55.387Z",
  "sentAt": "2015-02-23T22:28:55.111Z",
  "timestamp": "2015-02-23T22:28:55.111Z",
  "version": 1.1,
  "context": {
    "active": true,
    "ip": "8.8.8.8",
    "locale": "string",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML like Gecko) Chrome/40.0.2214.115 Safari/537.36",
    "channel": "browser",
    "campaign": {
      "name": "string",
      "source": "string",
      "medium": "string",
      "term": "string",
      "content": "string"
    },
    "page": {
      "name": "string",
      "path": "string",
      "referrer": "string",
      "search": "string",
      "title": "string",
      "url": "string",
      "keywords": [
        "string"
      ]
    }
  },
  "anonymousId": "507f191e810c19729de860ea",
  "channel": "browser"
}

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.
contextobject
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.
- activeboolean
  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.
- campaignobject
  Contains information about the campaign that resulted in the API call, gathered from, or mapping to, UTM parameters (e.g. utm_source).
  - contentstring
  - mediumstring
    The type of traffic a person/event originates from, like email, or referral.
  - namestring
    The campaign name.
  - sourcestring
    The source of traffic—like the name of your email list, Facebook, Google, etc.
  - termstring
    The keyword term(s) a user came from.
  - Additional UTM Parameters *string
- channelstring
  The channel the event originated from.
  Accepted values: browser, server, mobile
- ipstring
  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).
- localestring
  The locale string for the current user, e.g. en-US.
- pageobject
  Contains information about the current page in the browser. This is automatically collected by our JavaScript source.
  - keywordsarray of [ strings ]
    A list/array of keywords describing the page's content. The keywords are likely the same as, or similar to, the keywords you would find in an HTML meta tag for SEO purposes. This property is mainly used by content publishers that rely heavily on pageview tracking. This isn't automatically collected.
  - namestring
    The name of the page. Reserved for future use.
  - pathstring
    The path portion of the page's URL. Equivalent to the canonical path which defaults to location.pathname from the DOM API.
  - referrerstring
    The previous page's full URL. Equivalent to document.referrer from the DOM API.
  - searchstring
    The query string portion of the page's URL. Equivalent to location.search from the DOM API.
  - titlestring
    The page's title. Equivalent to document.title from the DOM API.
  - urlstring
    A page's full URL. We first look for the canonical URL. If the canonical URL is not provided, we'll use location.href from the DOM API.
- userAgentstring
  The user agent of the device making the request
integrationsobject
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.
- Enabled/Disabled integrations *boolean
messageIdstring
A unique identifier for a Data Pipelines call, ensuring that each individual event is unique. This is set by Customer.io
namestring
The name of the page.
originalTimestampstring(date-time)
In general, you can use timestamp rather than this field if you want to back-date events. This is the timestamp on the client device you invoke a call or the timestamp value you manually passed in a server-side library call.
propertiesobject
Additional page properties. Analytics.js automatically collects url, title, referrer, path, and search properties. But, if you use our other sources or you write your own integration, you should consider sending these properties yourself. Destination actions that take page events often rely on the url and title properties.
- categorystring
  The category of the page. This might be useful if you have a single page routes or have a flattened URL structure.
- pathstring
  The path of the page. This defaults to location.pathname, but can be overridden.
- referrerstring
  The referrer of the page, if applicable. This defaults to document.referrer, but can be overridden.
- searchstring
  The search query in the URL, if present. This defaults to location.search, but can be overridden.
- titlestring
  The title of the page. This defaults to document.title, but can be overridden.
- urlstring
  The URL of the page. This defaults to a canonical url if available, and falls back to document.location.href.
- Page Properties *any type
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 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.

Page properties

In page calls, you can send properties that describe the page. We have a number of reserved properties that we’ve defined below. For example, we always expect path to be a page’s URL path, and referrer to be the previous page’s URL. As with track calls you can also send custom properties beyond the reserved properties described below.

You should only use reserved properties for their intended meaning.

keywordsarray of [ strings ]
A list/array of keywords describing the page's content. The keywords are likely the same as, or similar to, the keywords you would find in an HTML meta tag for SEO purposes. This property is mainly used by content publishers that rely heavily on pageview tracking. This isn't automatically collected.
namestring
The name of the page. Reserved for future use.
pathstring
The path portion of the page's URL. Equivalent to the canonical path which defaults to location.pathname from the DOM API.
referrerstring
The previous page's full URL. Equivalent to document.referrer from the DOM API.
searchstring
The query string portion of the page's URL. Equivalent to location.search from the DOM API.
titlestring
The page's title. Equivalent to document.title from the DOM API.
urlstring
A page's full URL. We first look for the canonical URL. If the canonical URL is not provided, we'll use location.href from the DOM API.

Updated September 14, 2026