page()

The page() method records a page view event. It is automatically called once when Datafly.js loads (if using the script tag method), and should be called manually for client-side route changes in single-page applications.

Syntax

_df.page(properties?)

Parameters

Parameter	Type	Required	Description
`properties`	`Record<string, unknown>`	No	Additional properties to include with the page view

Returns

void

Basic usage

<script src="https://data.example.com/d.js" data-pipeline-key="dk_live_abc123"></script>
<script>
  _df.page();
</script>

With properties

Pass additional properties to describe the page:

_df.page({
  name: 'Products',
  category: 'shoes',
  brand: 'nike',
});

Automatically collected data

Every page() call automatically captures the following context from the browser. You do not need to pass these manually — they are included in the event’s context.page object:

Field	Source	Example
`url`	`window.location.href`	`https://example.com/products?q=shoes`
`path`	`window.location.pathname`	`/products`
`referrer`	`document.referrer`	`https://google.com/search?q=shoes`
`title`	`document.title`	`Products - Example Store`
`search`	`window.location.search`	`?q=shoes`

In addition to page context, every event also includes:

Field	Source	Example
`context.screen.width`	`screen.width`	`1920`
`context.screen.height`	`screen.height`	`1080`
`context.locale`	`navigator.language`	`en-US`
`context.timezone`	`Intl.DateTimeFormat`	`America/New_York`
`context.userAgent`	`navigator.userAgent`	`Mozilla/5.0 ...`
`context.library.name`	Constant	`@datafly/collector`
`context.library.version`	Constant	`0.1.0`

Event payload

A page() call produces an event with type: "page":

{
  "type": "page",
  "anonymousId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "context": {
    "page": {
      "url": "https://example.com/products",
      "path": "/products",
      "referrer": "https://google.com/",
      "title": "Products - Example Store",
      "search": ""
    },
    "screen": { "width": 1920, "height": 1080 },
    "locale": "en-US",
    "timezone": "America/New_York",
    "userAgent": "Mozilla/5.0 ...",
    "library": { "name": "@datafly/collector", "version": "0.1.0" }
  },
  "properties": {
    "name": "Products",
    "category": "shoes"
  },
  "timestamp": "2026-02-25T10:30:00.000Z",
  "messageId": "df-a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
}

SPA route changes

In single-page applications, the browser does not perform a full page load on navigation. You must call _df.page() on each route change to track all page views.

React Router

import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';
 
function App() {
  const location = useLocation();
 
  useEffect(() => {
    _df.page();
  }, [location]);
 
  return <Routes>{/* ... */}</Routes>;
}

Next.js App Router

'use client';
 
import { usePathname } from 'next/navigation';
import { useEffect } from 'react';
 
export function PageTracker() {
  const pathname = usePathname();
 
  useEffect(() => {
    _df.page();
  }, [pathname]);
 
  return null;
}

Vue Router

import { watch } from 'vue';
import { useRoute } from 'vue-router';
 
const route = useRoute();
 
watch(
  () => route.fullPath,
  () => {
    _df.page();
  }
);

History API (vanilla JS)

If your SPA uses the History API directly:

// Patch pushState and replaceState to fire page views
const originalPushState = history.pushState;
history.pushState = function (...args) {
  originalPushState.apply(this, args);
  _df.page();
};
 
window.addEventListener('popstate', () => {
  _df.page();
});

Custom context

You can set custom context values that will be included with every event, including page views:

_df.context.set('experiment_id', 'exp-42');
_df.context.set('page_category', 'product_listing');
_df.page();

See the Configuration reference for more on the context API.

⚠️

Do not call _df.page() before _df.init(). If Datafly.js has not been initialized, page() will throw an error. When using the script tag method with data-pipeline-key, initialization happens automatically when the script loads.

Installation track()