Customer.io

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

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 and start writing code.

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 profile 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.
  • typestringrequired
    The event type. This is set automatically by the request method/endpoint.
    Accepted values: page
  • namestringrequired
    The name of the page.
  • propertiesobject
    Additional properties for your event.
    • categorystring
      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 that you want to send with the page event. By default, we capture url, title, and stuff.
  • 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.

    • 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.
    • userAgentstring
      The user agent of the device making the request
    • channelstring
      The channel the event originated from.
      Accepted values: browser, server, mobile
    • campaignobject
      Contains information about the campaign that resulted in the API call, gathered from, or mapping to, UTM parameters (e.g. utm_source).
      • namestring
        The campaign name.
      • sourcestring
        The source of traffic—like the name of your email list, Facebook, Google, etc.
      • mediumstring
        The type of traffic a person/event originates from, like email, or referral.
      • termstring
        The keyword term(s) a user came from.
      • contentstring
      • Additional UTM Parameters *string
    • pageobject
      Contains information about the current page in the browser. This is automatically collected by our JavaScript source.
      • 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.
      • 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.
  • 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 event, ensuring that each individual event is unique.
  • 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 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.
  • 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.

Our JavaScript library automatically captures most properties

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

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