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 your Signal endpoint 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 Signal:

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 anonymous-identity 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.

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 Identity 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: 'alice@example.com' });
await datafly.refreshProfile();

See Identity 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();