Installation

There are several ways to add Datafly.js to your site. The recommended approach for most websites is the script tag method, which requires no build tools and works with any site.

Script tag (recommended)

Add the following snippet to the <head> of every page, before any other scripts:

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

Replace data.example.com with your configured Datafly subdomain, and dk_live_abc123 with the pipeline key from your source configuration in the Datafly management UI.

The script loads from your own subdomain as a first-party resource. This means it is not blocked by ad blockers, and cookies set by the Ingestion Gateway via Set-Cookie headers are treated as first-party by all browsers, including Safari’s ITP.

How it works

When the script loads, it:

Reads the data-pipeline-key attribute from its own script tag
Resolves the endpoint URL from the script’s src origin (e.g., https://data.example.com)
Initializes the collector and exposes the _df global variable
Makes the _df.page(), _df.track(), _df.identify(), and _df.group() methods available

Script filename

The default script filename is d.js. This is intentionally short and generic to avoid ad blocker pattern matching. The filename is configurable per source in the management UI.

Global variable

The default global variable is _df. This is configurable per source. If you change the global variable name, update all references in your tracking code accordingly.

<!-- Custom global variable name -->
<script src="https://data.example.com/d.js" data-pipeline-key="dk_live_abc123" data-global="_myTracker"></script>
<script>
  _myTracker.page();
</script>

npm package

For applications using a JavaScript bundler (webpack, Vite, Rollup, esbuild), install the npm package:

npm install @datafly/collector

Then initialize in your application entry point:

import datafly, { page, track, identify, group } from '@datafly/collector';
 
datafly.init({
  pipelineKey: 'dk_live_abc123',
  endpoint: 'https://data.example.com',
});
 
// Track initial page view
page();

ESM named exports

The npm package exports tree-shakeable named functions. You can import only the methods you need:

import { init, page, track } from '@datafly/collector';
 
init({
  pipelineKey: 'dk_live_abc123',
  endpoint: 'https://data.example.com',
});
 
page();
track('Button Clicked', { label: 'Sign Up' });

Default export

The default export is the singleton datafly instance with all methods:

import datafly from '@datafly/collector';
 
datafly.init({ pipelineKey: 'dk_live_abc123', endpoint: 'https://data.example.com' });
datafly.page();
datafly.track('Button Clicked', { label: 'Sign Up' });

TypeScript

The package ships with TypeScript declarations. All types are exported:

import type { DataflyConfig, DataflyEvent, ConsentState, VendorIDs } from '@datafly/collector';

Custom builds

For maximum performance, Datafly supports per-source custom builds. A custom build includes only the vendor modules needed for that source, reducing the script size further.

Custom builds are configured in the management UI under Sources > Build Settings. When you select which vendors a source delivers to, the build system generates a script that only includes the ID generation and collection logic for those specific vendors.

Example

If a source only delivers to GA4 and Meta, the custom build will:

Include GA4 client_id generation and _ga cookie parsing
Include Meta fbp generation and fbclid capture
Exclude TikTok, Pinterest, Snapchat, and LinkedIn modules

This results in a smaller script payload and fewer cookies being managed.

Delivery methods

There are three ways to serve the built Datafly.js script to your site:

1. Download (self-hosted)

Download the built script from the management UI and host it yourself on your web server or CDN.

Sources > [Your Source] > Build Settings > Download

Pros: Full control over hosting, caching, and deployment. Cons: You must re-download and redeploy when the script is updated.

2. Cluster-served with CDN origin

The Datafly cluster serves the script directly, and you configure your CDN (Cloudflare, CloudFront, Fastly) to use the cluster as an origin.

Your CDN (data.example.com)  --->  Datafly Cluster  --->  Built d.js

Pros: Automatic updates, CDN edge caching, no manual deployments. Cons: Requires CDN configuration.

This is the recommended approach for production deployments.

3. Direct from cluster

The Datafly cluster serves the script directly at your configured subdomain without an intermediary CDN.

data.example.com (DNS CNAME to cluster)  --->  Built d.js

Pros: Simplest setup, automatic updates. Cons: No edge caching (served from cluster region only).

⚠️

Direct-from-cluster delivery is suitable for development and low-traffic sites. For production sites with global traffic, use cluster-served with CDN origin for optimal performance.

SPA frameworks

React / Next.js

For React applications, initialize Datafly.js once in your root layout or entry component:

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

For route change tracking in SPAs, call _df.page() on each navigation. See the page() reference for details.

Vue / Nuxt

// plugins/datafly.client.js (Nuxt 3)
export default defineNuxtPlugin(() => {
  if (typeof _df !== 'undefined') {
    _df.page();
  }
});

Angular

// app.component.ts
import { Router, NavigationEnd } from '@angular/router';
 
constructor(private router: Router) {
  this.router.events.subscribe(event => {
    if (event instanceof NavigationEnd) {
      (window as any)._df?.page();
    }
  });
}

Verifying installation

After adding Datafly.js to your site, verify it is working:

Open your browser’s Developer Tools (F12)
Go to the Network tab
Load your page and look for a request to d.js from your subdomain
Check for outgoing POST requests to /v1/batch on the same subdomain
The request payload should contain a batch array with your events

You can also check the console. In debug mode, Datafly.js logs all events:

_df.init({
  pipelineKey: 'dk_live_abc123',
  endpoint: 'https://data.example.com',
  debug: true,
});

Events appear in the management UI under Sources > Live Events within a few seconds of being sent.

Overview page()