Configuration

This page documents the configuration options for Datafly.js: init parameters, where pipeline settings are configured, the context API, transport behaviour and helper methods.

init() options

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

import datafly from '@datafly/collector';
 
datafly.init({
  pipelineKey: '3f2a9c1e-7b4d-4e8a-9c6f-1d2e3f4a5b6c',
  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’s key, a UUID shown on the pipeline overview in the management UI
`endpoint`	`string`	(required)	Your Datafly Signal collect endpoint (your first-party subdomain, e.g., `https://data.example.com`)
`batchSize`	`number`	(none)	Accepted for compatibility but currently unused: events are sent one per request (see Transport details)
`flushInterval`	`number`	(none)	Accepted for compatibility but currently unused
`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 you install with the script tag, you don’t call init() yourself. The build served for your pipeline already calls init() with the pipeline key, collect endpoint and the pipeline’s consent, identity and module settings baked in, then sends the first page view.

Script tag

The script tag takes no data-* attributes; nothing in the collector reads them. Everything is configured on the pipeline in the management UI and baked into the build:

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

Setting	Where to change it
Pipeline key	Part of the script URL. Each pipeline has its own build
Collect endpoint	Settings → Environments (or the pipeline’s endpoint override)
Script filename	Collector tab, Script filename. Cosmetic: the key in the URL selects the build
Global variable	Collector tab, JS global namespace. `window.datafly` stays available alongside a custom name
Automatic page views	Collector tab, Page tracking (Standard, SPA or None)

See Installation for the full install and delivery options.

Pipeline configuration

There is no per-source configuration object and no per-vendor section in the collector. Settings live on the pipeline and its integrations in the management UI:

What	Where it is configured	How it reaches the browser
Script filename, global variable, page tracking, automatic `session_start` / `first_visit` / `user_engagement` events, anonymous ID cookie name and domain	Pipeline Collector tab	Baked into the collector build
Consent provider and categories	Pipeline Consent tab	Baked into the collector build
Cross-domain identity, link decoration, ID syncs	Pipeline Identity tab	Baked into the collector build
Destinations (GA4 measurement ID, Meta pixel ID, Google Ads conversion ID, API credentials and so on)	Integrations, attached to the pipeline	Not sent to the browser. Used server-side when events are delivered

Changing a collector, consent or identity setting rebuilds the collector automatically, unless Rebuild automatically is off in the Collector tab. A downloaded copy must be downloaded again and redeployed. See How an update reaches your site.

To add metadata such as environment or app version to events, send it as event properties.

Context API

The context API allows you to set custom key-value pairs that are merged into every event’s context object. Context values are set at runtime from your JavaScript code.

⚠️

Custom context keys are currently dropped by the ingestion gateway, which only accepts its defined context fields, so they do not reach your pipeline or destinations. Until that changes, send values you need downstream as event properties.

context.set()

datafly.context.set(key, value)

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

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

context.unset()

Remove a previously set context key:

datafly.context.unset('experiment_id');

context.clear()

Remove all custom context values:

datafly.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" }.

Debugging

The collector has no debug or console-logging option. To check what it sends:

Use your browser’s Network tab and look for POST requests to /v1/p, /v1/t and /v1/i on your collect endpoint. The request body is the event.
In the management UI, turn on debugging for the pipeline in the Event Debugger to trace an event through consent, processing and delivery to each destination.

Pipeline keys

Each pipeline has one pipeline key, a UUID shown on the pipeline overview (for example 3f2a9c1e-7b4d-4e8a-9c6f-1d2e3f4a5b6c). The key is public: it appears in the collector URL and identifies which pipeline an event belongs to. Keys have no live or test prefixes, so use a separate pipeline (with its own domain allowlist and integrations) for staging.

Transport details

Setting	Value	Description
Delivery	One request per event	Each event is sent as soon as it is created
Transport	`XMLHttpRequest` with credentials	Sends and receives the first-party cookies on your collect endpoint
Endpoint paths	`/v1/p`, `/v1/t`, `/v1/i`	Page views, track events and identify calls
Auth header	`Authorization: Bearer {pipelineKey}`	Pipeline key on every request
Calls before initialisation	Held	`page()`, `track()`, `identify()` and `group()` calls made before initialisation has finished are sent, in order, once it has (up to 1,000)
Queue	`localStorage`, one per pipeline	Every event is kept until the gateway acknowledges it, so it survives a reload; all tabs of a site share the queue without removing each other’s events. Up to 1,000 events, oldest dropped first
Concurrency	Up to 6 requests in flight per tab	Each answer sends the next waiting event
Retry	Exponential backoff	Network errors, `5xx` and `429` are retried, honouring `Retry-After`, for as long as the page is open (every 5 minutes after 10 failures); a success sends everything waiting straight away
Refusals	Kept or dropped by status	`401`, `403`, `404` and `405` (a pipeline key, allowed domain or route to correct) keep the events and retry every 5 minutes; `400` and `413` drop that one event
Warnings	`console.warn`	Every dropped event (refused, unserialisable, over the queue limit) and a queue that cannot be saved is reported with a `[datafly]` warning
Unload flush	`navigator.sendBeacon` to `/v1/batch`	On `visibilitychange` (hidden) and `pagehide`, events the gateway has not yet acknowledged are sent as `text/plain` JSON batches of up to 500 events and about 50 KB each, with the key as a `pipeline_key` query parameter. Events created while the page is hidden or unloading, such as `user_engagement`, are included. They stay queued until acknowledged

Helper methods

flush()

Force an immediate flush of all queued events:

datafly.flush();

getAnonymousId()

Get the current anonymous ID:

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

getUserId()

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

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

getConsent()

Read the current consent state:

const consent = datafly.getConsent();
// Keyed by your consent provider's category codes, e.g. { C0001: true, C0002: false }
// Returns {} when the pipeline has no consent provider

Cross-Domain Identity Migrating from analytics.js