Helper Methods

Beyond the four core methods (page(), track(), identify(), group()), Datafly.js exposes a set of helpers for inspecting state, controlling delivery timing, and clearing identity on logout.

All helpers are available on the global datafly object after installation.

flush()

Forces any queued events to be sent to the Ingestion Gateway immediately, bypassing the configured batching interval.

datafly.flush();

Use this when you need to guarantee delivery before navigating away or unloading the page — for example, before a hard redirect or a window.location.replace(). Datafly.js already flushes automatically on pagehide and beforeunload, so manual flush() is rarely required.

flush() returns a Promise that resolves once the in-flight batch has been acknowledged by the Ingestion Gateway:

await datafly.flush();
window.location.href = '/checkout';

reset()

Clears the visitor’s local identity state. Call this when a user logs out so the next session is treated as a new anonymous visitor.

datafly.reset();

reset() clears:

• The local _dfid cookie
• Any cached user_id from a prior identify() call
• Cached enrichment results in IndexedDB
• In-memory consent state (will be re-read from your CMP on the next event)

It does not delete server-side identity records — those expire naturally based on TTL. If a returning visitor on the same device logs in as the same user, server-side enrichment data may still be associated.

getAnonymousId()

Returns the current anonymous visitor ID (the value of the _dfid cookie).

const anonId = datafly.getAnonymousId();
// e.g. "anon_8f7a3e2b9c1d4f56"

Useful for cross-system correlation when you want to link a Signal-tracked event to a record in your own backend.

getUserId()

Returns the user ID set by the most recent identify() call, or null if the visitor is anonymous.

const userId = datafly.getUserId();
if (userId) {
  console.log('Logged in as', userId);
}

getConsent()

Returns the current consent state as an object reflecting the visitor’s choices.

const consent = datafly.getConsent();
// { ad_storage: 'granted', analytics_storage: 'granted', ad_user_data: 'denied', ad_personalization: 'denied' }

The shape matches Google Consent Mode v2. Values are 'granted' or 'denied'. Consent state is read from your CMP on each call — see Consent Management for how Signal integrates with OneTrust, Cookiebot, Cookie Information, and others.

onEnrichmentReady()

Returns a Promise that resolves once any in-flight server-proxied enrichment (CDP partner lookup, identity-graph resolution) has completed and the result is available in the local cache.

await datafly.onEnrichmentReady();
datafly.track('purchase', { value: 49.99, currency: 'GBP' });

Use this only when a conversion can fire on the first page event of a session (e.g. one-click deep-link checkouts). Standard browse-then-convert flows don’t need it because enrichment will normally have completed by the time a conversion event fires later in the session. See Server-Proxied Enrichment for context.

onProfileReady() / refreshProfile()

If you’ve configured a CDP partner integration that exposes profile attributes to the browser (Amperity, Acxiom, etc.), use these to gate render on the profile fetch:

await datafly.onProfileReady();
const persona = datafly.profile.amperity?.Persona;
if (persona === 'Value Hunter') {
  document.querySelector('#hero').dataset.variant = 'promo';
}
 
// After a logged-in identify, re-fetch to pick up richer attributes.
datafly.identify('user-123', { email: '[email protected]' });
await datafly.refreshProfile();

See Server-Side Partner Enrichment for setup.

TypeScript

All helpers are typed in the @datafly/collector package:

import datafly from '@datafly/collector';
 
declare global {
  interface Window {
    datafly: typeof datafly;
  }
}
 
const userId: string | null = datafly.getUserId();
const consent: ConsentState = datafly.getConsent();
await datafly.flush();