Overview

The Page event method helps you understand which web pages are being visited. It collects information related to the specific web page that a user is currently viewing and includes that information as data within the Page event payload.

Page events are a foundational piece of web-based event tracking. They are fired automatically with the Analytics.js snippet that MetaRouter builds for you. We recommend that you keep it in most use cases, but you may remove the event call and trigger the Page event from your event code as well. The most common use cases for this would either be to reduce your total event volume or to fire a Page event multiple times on a single page if you use a single-page application.

How It Works

The Page event fires either via the default snippet code or via code you add to your website. If you are manually adding a Page event to your website code, the function will look like this:

analytics.page([category], [name], [properties], [options], [callback]);

This function will produce a JSON payload that includes information about the page currently being viewed. It will include fields common to all Analytics.js calls, and also include anything you specify within the call.

Example

This is an example call that we could make, with the options and callback functions empty:

analytics.page ("documentation", "Documentation Homepage", {test_type: "A"})

This call could produce this payload, with common fields removed:

{
  "type": "page",
  "name": "Documentation Homepage",
  "properties": {
    "title": "metarouter documentation homepage",
    "url": "http://www.example.com/",
		"category": "documentation",
		"test_type": "A"
  }
}

With common fields, the event could look like this:

{
  "timestamp": "2024-01-10T23:08:40.090Z",
  "integrations": {},
  "anonymousId": "f8cc0f85-cb4d-4f73-b16f-c251384fdf74",
  "type": "page",
  "properties": {
    "category": "documentation"
		"path": "/",
    "referrer": "",
    "search": "",
    "title": "metarouter documentation homepage",
    "url": "https://www.example.com/",
    "name": "Docs Homepage",
		"test_type": "A"
  },
  "context": {
    "page": {
      "path": "/",
      "referrer": "",
      "search": "",
      "title": "metarouter documentation homepage",
      "url": "https://www.example.com/"
    },
    "providers": {},
    "globalPrivacyControl": false,
    "consent": {
      "optOut": {
        "C0001": false,
        "C0002": false,
        "C0003": false,
        "C0004": false,
        "C0005": false
      }
    },
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
    "locale": "en-US",
    "library": {
      "name": "analytics.js",
      "version": "npm:next-1.51.3-mr.3"
    }
  },
  "messageId": "05b0eb33e6948947f15973724147e34d",
  "writeKey": "example_writekey",
  "sentAt": "2024-01-10T23:08:40.095Z",
  "_metadata": {
    "bundled": [],
    "unbundled": [],
    "bundledIds": []
  }
}

Overriding Fields

You can override fields that are typically automatically populated by setting them in your calls. For the example above, your event call could be:

analytics.page ("documentation", "Documentation Homepage", 
	{
		test_type: "A", 
		url: "https://www.example.com/#section4"
	})

Properties

Properties represent any additional information you might want to track about the pages that your users visit. Some properties are populated via the common fields, but you may also add your own custom properties as well if you would like to track anything else about the website page view.

This is a list of common properties. We recommend using these whenever one of these fields covers what you are trying to track.

Property	Data Type	Description
`name`	String	Name of the current page.
`path`	String	Path of the current page’s URL. Equivalent to `canonical path` which defaults to `location.pathname` from the DOM API.
`referrer`	String	The previous page that referred the user to the current page. Equivalent to `document.referrer` from the DOM API.
`search`	String	Query string that a user used to find the current page. Equivalent to `location.search` from the DOM API.
`title`	String	The current page’s title. Equivalent to `document.title` from the DOM API.
`url`	String	The current page’s full URL. Analytics.js uses the canonical URL. If this isn’t available, it uses `location.href` from the DOM API.
`keywords`	Array of Strings	A list/array of keywords describing the page’s content. The keywords would most likely be 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.

Options

The options object can be included in order to change some behaviors during the event call.

Property	Data Type	Default	Description
`maxage`	Number	365	Max age in days
`domain`	String	Inferred from document.location	The domain
`samesite`	String	Lax	An indicator of how cookies should be handled with regard to SameSite restrictions. Valid values are “Strict”, “Lax”, and “None”
`path`	String	/	The URL path
`secure`	Boolean	undefined (false)	An indication of the protocol for the request

Callback

By including a function in the callback parameter, it is possible to receive feedback after the event call is completed. The function will be passed as a single parameter, which returns an object describing the results of the event call:

Property	Data Type	Description
`attempts`	Number	The number of attempts which were made to deliver the event.
`event`	Object	The event which was sent
`logger`	Object	Logging data which was collected during the event’s delivery
`stats`	Object	Statistics around the amount of time which was spent during each phase of event delivery