Page

Updated

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’ve visited particular pages to see if they’re still interested in a product, online class, and so on.

Our JavaScript source 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.

 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

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

If you use the JavaScript source, 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 analytics.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 source library you install for more information about the page method.

analytics.page({
  userId: '019mr8mf4r',
  category: 'Docs',
  name: 'Customer.io Data Pipelines',
  properties: {
    url: 'https://customer.io/cdp/',
    path: '/cdp/',
    title: 'Data 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 Data Pipelines.

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": "http://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"
}
    • 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
      • content string
      • medium string
        The type of traffic a person/event originates from, like email, or referral.
      • name string
        The campaign name.
      • source string
        The source of traffic—like the name of your email list, Facebook, Google, etc.
      • term string
        The keyword term(s) a user came from.
      • Additional UTM Parameters* string
      • keywords array 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.
      • name string
        The name of the page. Reserved for future use.
      • path string
        The path portion of the page’s URL. Equivalent to the canonical path which defaults to location.pathname from the DOM API.
      • referrer string
        The previous page’s full URL. Equivalent to document.referrer from the DOM API.
      • search string
        The query string portion of the page’s URL. Equivalent to location.search from the DOM API.
      • title string
        The page’s title. Equivalent to document.title from the DOM API.
      • url string
        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.
    • Enabled/Disabled integrations* boolean
  • messageId string
    A unique identifier for a Data Pipelines event, ensuring that each individual event is unique.
  • name string
    Required The name of the page.
    • category string
      The category of the page. This might be useful if you have a single page routes or have a flattened URL structure.
    • Page Properties* any type
      Additional properties tha tyou want to send with the page event. By default, we capture `url`, `title`, and stuff.
  • 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
    Required The event type. This is set automatically by the request method/endpoint.

    Accepted values:page

  • 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 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.

 Our JavaScript library automatically captures most properties

Our analytics.js library automatically captures the title, path, url, referrer, and search properties in page calls.

  • keywords array 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.
  • name string
    The name of the page. Reserved for future use.
  • path string
    The path portion of the page’s URL. Equivalent to the canonical path which defaults to location.pathname from the DOM API.
  • referrer string
    The previous page’s full URL. Equivalent to document.referrer from the DOM API.
  • search string
    The query string portion of the page’s URL. Equivalent to location.search from the DOM API.
  • title string
    The page’s title. Equivalent to document.title from the DOM API.
  • url string
    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.
Copied to clipboard!
  Contents
Is this page helpful?