Installation

Datafly.js is installed with one script tag. Each pipeline gets its own build of the collector with the pipeline key, collect endpoint, consent settings and optional modules baked in, so there is nothing to configure in the page itself.

Script tag (recommended)

In the management UI, open your pipeline, go to the Collector tab, choose Cluster-served delivery and click Build Collector. Copy the Script Tag it shows and paste it into the <head> of every page:

<script src="https://collect.example.com/js/<pipeline_key>/df_example.js" defer></script>

• collect.example.com is your collect endpoint (set in Settings → Environments, or overridden per pipeline).
• <pipeline_key> is the pipeline’s key (a UUID), shown on the pipeline overview.
• df_example.js is the script filename. It is cosmetic and can be changed in the Collector tab.

What the tag does

When the script loads, it:

1. Calls datafly.init() with the configuration baked into the build (pipeline key, collect endpoint, consent, identity and module settings)
2. Sends a page view once initialisation completes
3. Sends a page view on every single-page-app route change (history.pushState, history.replaceState or popstate that changes the URL), with the previous URL as the page referrer
4. Emits session_start when a new session begins and first_visit on a visitor’s first session (each can be switched off in the Collector tab)
5. Exposes the datafly global, so your own code can call datafly.track(), datafly.identify() and datafly.group()

Page tracking

The Page tracking setting in the Collector tab controls automatic page views. It is baked into the build, so rebuild the collector after changing it.

Calling the API from your code

The datafly global exists once the script has run, and track(), identify() and group() throw if they are called before initialisation has finished. Call them from your application code or from handlers for user actions, not from an inline script in the <head>:

document.querySelector('#signup-form').addEventListener('submit', () => {
  datafly.track('sign_up', { method: 'email' });
});

Global variable

The default global variable is datafly. You can set a different name per pipeline in the Collector tab (JS global namespace). The build then exposes the collector under both window.datafly and your chosen name, so existing datafly.* calls keep working.

Delivery methods

The Collector tab offers two ways to serve the built script.

Cluster-served (recommended)

Your collect endpoint serves the latest build at /js/<pipeline_key>/<filename>, and browsers pick up a new build when their cached copy expires.

• Cache TTL is set in the Collector tab (default 5 minutes). After it expires, an ETag check avoids re-downloading an unchanged file.
• You can put a CDN in front of your collect endpoint. It respects the same cache headers.

How an update reaches your site

With Rebuild automatically on (the default), the collector is rebuilt:

• within seconds of a change to the pipeline’s collector, identity or consent settings or its integrations, and when a pipeline version is published or rolled back;
• after a Datafly Signal update that changes Datafly.js, about a minute after the new release starts. A collector that the previous release rebuilt while the update was rolling out is picked up within 15 minutes.

The collect endpoint serves each new build as soon as it is stored. Browsers, and any CDN in front of the collect endpoint, keep the copy they have for the Cache TTL, so a visitor can run the previous build for up to that long. With a long TTL, such as 30 days, purge your CDN to reach new visitors sooner; browsers that already hold the file keep it until it expires.

Turn Rebuild automatically off to rebuild only when you press Build Collector. The Latest Build panel then says when the build uses an earlier version of Datafly.js.

Download (self-hosted)

Build the collector, download the .js or .js.gz file and host it on your own web server or CDN, then reference it with a single tag:

<script src="https://www.example.com/df_example.js" async></script>

The downloaded file is a snapshot of the configuration at build time. Automatic rebuilds update the file the Collector tab offers for download, not the copy on your site, so download and redeploy it whenever you change the pipeline’s integrations, consent, identity or collector settings, and after a Datafly Signal update.

Single-page apps

No router integration is needed. With page tracking set to Standard, the collector hooks the History API and sends a page view whenever the URL changes, whether the navigation comes from React Router, the Next.js App Router, Vue Router, Angular or plain history.pushState. Calls that leave the URL unchanged (for example scroll restoration) are ignored.

If you would rather send page views from your router yourself (for example to wait until a view has rendered its title), set Page tracking to None, rebuild, and call datafly.page() on each navigation, including the first load.

For Next.js, the tag can go in your root layout:

// app/layout.jsx (Next.js App Router)
import Script from 'next/script';
 
export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Script
          src="https://collect.example.com/js/<pipeline_key>/df_example.js"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

Verifying installation

After adding the tag to your site:

1. Open your browser’s Developer Tools and go to the Network tab
2. Load a page. You should see the script request (/js/<pipeline_key>/<filename> on your collect domain, or your self-hosted URL) return 200
3. Look for a POST to /v1/p on your collect endpoint. That is the page view. On a new session you will also see POST /v1/t requests for session_start (and first_visit for a new visitor)
4. In a single-page app, navigate to another route and check for another POST /v1/p

Events are sent one per request: page views to /v1/p, track events to /v1/t and identify calls to /v1/i. A POST /v1/batch only appears when the page is hidden or closed while some events have not yet been acknowledged by the gateway.