Configuration

This page documents all configuration options for Datafly.js, including init parameters, per-source settings, vendor configuration, and the context API.

init() options

When using the npm package, pass a configuration object to init():

import datafly from '@datafly/collector';
 
datafly.init({
  pipelineKey: 'dk_live_abc123',
  endpoint: 'https://data.example.com',
  batchSize: 10,
  flushInterval: 1000,
  crossDomain: {
    hubUrl: 'https://id.company.com/resolve',
    linkedDomains: ['brand-a.com', 'brand-b.com'],
  },
});

Options reference

Option	Type	Default	Description
`pipelineKey`	`string`	(required)	The pipeline key for this source, issued from the management UI. Format: `dk_live_...` or `dk_test_...`
`endpoint`	`string`	(required)	The Ingestion Gateway URL (your first-party subdomain, e.g., `https://data.example.com`)
`batchSize`	`number`	`10`	Maximum number of events per batch request
`flushInterval`	`number`	`1000`	Auto-flush interval in milliseconds
`crossDomain`	`CrossDomainConfig`	`undefined`	Cross-domain identity configuration (see below)

CrossDomainConfig

Option	Type	Default	Description
`hubUrl`	`string`	(required)	The Identity Hub resolve endpoint URL
`linkedDomains`	`string[]`	`[]`	List of domains to link (sent to hub for informational purposes)

When using the script tag method, the pipelineKey and endpoint are automatically resolved from the script tag’s data-pipeline-key attribute and src origin. Additional configuration (batch size, cross-domain, etc.) is loaded from the per-source config stored on the server.

Script tag attributes

When loading Datafly.js via script tag, the following attributes are supported:

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

Attribute	Default	Description
`src`	(required)	URL to the Datafly.js script on your subdomain
`data-pipeline-key`	(required)	The pipeline key for this source
`data-global`	`_df`	The name of the global variable exposed on `window`

Custom global variable

If _df conflicts with another library on your page, change the global variable name:

<script src="https://data.example.com/d.js" data-pipeline-key="dk_live_abc123" data-global="_myAnalytics"></script>
<script>
  _myAnalytics.page();
  _myAnalytics.track('Button Clicked');
</script>

Custom script filename

The default script filename is d.js. This is configured per source in the management UI under Sources > Build Settings > Script Filename. The filename is intentionally short and generic to minimise the chance of being blocked by ad blockers.

You can change it to any filename:

Filename	URL
`d.js` (default)	`https://data.example.com/d.js`
`collector.js`	`https://data.example.com/collector.js`
`t.js`	`https://data.example.com/t.js`

Per-source configuration

Each source has a configuration stored in PostgreSQL that controls its behaviour. This is managed through the management UI or the Management API.

Source config structure

{
  "source_id": "src_abc123",
  "name": "Production Website",
  "pipeline_key": "dk_live_abc123",
  "endpoint": "https://data.example.com",
  "global_variable": "_df",
  "script_filename": "d.js",
  "vendors": {
    "ga4": {
      "enabled": true,
      "measurement_id": "G-XXXXXXXXXX"
    },
    "meta": {
      "enabled": true,
      "pixel_id": "1234567890"
    },
    "tiktok": {
      "enabled": false,
      "pixel_id": null
    },
    "pinterest": {
      "enabled": true,
      "tag_id": "1234567890"
    },
    "snapchat": {
      "enabled": false,
      "pixel_id": null
    },
    "linkedin": {
      "enabled": false,
      "partner_id": null
    },
    "google_ads": {
      "enabled": true,
      "conversion_id": "AW-1234567890"
    }
  },
  "consent": {
    "mode": "auto",
    "default_state": {
      "analytics": false,
      "marketing": false,
      "functional": false
    }
  },
  "cross_domain": {
    "enabled": false,
    "hub_url": null,
    "linked_domains": []
  },
  "client_tags": {},
  "debug": false
}

Vendor configuration

Each vendor can be enabled or disabled per source, with vendor-specific metadata:

Google Analytics 4

{
  "ga4": {
    "enabled": true,
    "measurement_id": "G-XXXXXXXXXX"
  }
}

Field	Description
`measurement_id`	Your GA4 Measurement ID (found in GA4 > Admin > Data Streams)

Meta (Facebook)

{
  "meta": {
    "enabled": true,
    "pixel_id": "1234567890"
  }
}

Field	Description
`pixel_id`	Your Meta Pixel ID (found in Events Manager)

TikTok

{
  "tiktok": {
    "enabled": true,
    "pixel_id": "CXXXXXXXXXXXXXXXXX"
  }
}

Field	Description
`pixel_id`	Your TikTok Pixel ID (found in TikTok Events Manager)

{
  "pinterest": {
    "enabled": true,
    "tag_id": "1234567890"
  }
}

Field	Description
`tag_id`	Your Pinterest Tag ID (found in Pinterest Ads Manager)

Snapchat

{
  "snapchat": {
    "enabled": true,
    "pixel_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

Field	Description
`pixel_id`	Your Snapchat Pixel ID (found in Snap Ads Manager)

{
  "linkedin": {
    "enabled": true,
    "partner_id": "1234567"
  }
}

Field	Description
`partner_id`	Your LinkedIn Partner ID (found in LinkedIn Campaign Manager)

Google Ads

{
  "google_ads": {
    "enabled": true,
    "conversion_id": "AW-1234567890"
  }
}

Field	Description
`conversion_id`	Your Google Ads Conversion ID (found in Google Ads > Tools > Conversions)

Client tags

Client tags are custom key-value pairs that are added to every event sent from this source. Use them to tag events with metadata such as environment, version, or business unit:

{
  "client_tags": {
    "environment": "production",
    "app_version": "2.4.1",
    "business_unit": "ecommerce",
    "region": "eu-west"
  }
}

Client tags appear in the event payload under context.client_tags:

{
  "type": "track",
  "event": "Order Completed",
  "context": {
    "client_tags": {
      "environment": "production",
      "app_version": "2.4.1",
      "business_unit": "ecommerce",
      "region": "eu-west"
    }
  }
}

Context API

The context API allows you to set custom key-value pairs that are merged into every event’s context object. Unlike client tags (which are set at the source level), context values are set at runtime from your JavaScript code.

context.set()

_df.context.set(key, value)

Parameter	Type	Description
`key`	`string`	The context key
`value`	`unknown`	The context value (any serialisable type)

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

context.unset()

Remove a previously set context key:

_df.context.unset('experiment_id');

context.clear()

Remove all custom context values:

_df.context.clear();

⚠️

The library key in the context is reserved and cannot be overridden via context.set(). It always contains { name: "@datafly/collector", version: "0.1.0" }.

Debug mode

Enable debug mode to log all events to the browser console:

{
  "debug": true
}

Or when using the npm package:

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

In debug mode, Datafly.js logs:

Every event as it is enqueued
Every batch as it is sent
Consent state changes
Vendor ID collection results
Cross-domain resolution steps
Transport errors (normally silent)

⚠️

Do not enable debug mode in production. It writes verbose output to the browser console and may expose pipeline keys and event data to anyone with developer tools open.

Pipeline key formats

Pipeline keys follow a consistent format that indicates the environment:

Prefix	Environment	Description
`dk_live_`	Production	Events are processed and delivered to vendors
`dk_test_`	Testing	Events are processed but not delivered to vendors

Test pipeline keys are useful for staging environments where you want to verify event collection without sending data to live vendor accounts.

Transport details

Setting	Value	Description
Batch size	10 events max	Events are sent in batches of up to 10
Flush interval	1,000 ms	Queue is flushed every second
Primary transport	`navigator.sendBeacon`	Fire-and-forget, survives page unload
Fallback transport	`XMLHttpRequest`	Used when sendBeacon is unavailable
Endpoint path	`/v1/batch`	Batch endpoint on the Ingestion Gateway
Auth header	`Basic {base64(pipelineKey:)}`	Pipeline key sent via Authorization header (XHR) or query param (sendBeacon)
Unload flush	`visibilitychange` + `pagehide`	Events are flushed when the page is hidden or unloaded

Helper methods

flush()

Force an immediate flush of all queued events:

_df.flush();

getAnonymousId()

Get the current anonymous ID:

const anonId = _df.getAnonymousId();
// "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"

getUserId()

Get the current user ID (set via identify()):

const userId = _df.getUserId();
// "user-123" or undefined if not yet identified

getConsent()

Read the current consent state:

const consent = _df.getConsent();
// { analytics: true, marketing: false, functional: true }

Cross-Domain Identity Overview