Migrating from analytics.js

Many sites send events through the window.analytics interface: an inline snippet that queues calls, then a library that loads and sends them. The calls look like this:

analytics.page();
analytics.track('Product Added', { product_id: 'sku-1', price: 19.99 });
analytics.identify('user-7', { plan: 'pro' });

With analytics.js compatibility switched on, Datafly.js takes over window.analytics. Your site’s snippet and every existing call keep working unchanged. Moving to Datafly Signal is a change to one script tag.

What carries over

Your site does	Datafly Signal does
Queues calls in the snippet before the library loads	Replays the queue, in order, once the collector is ready
`analytics.page([category], [name], [properties])`	Sends a page view. `name` and `category` are added to the properties
`analytics.track(event, [properties])`	Sends a track event with the same name and properties
`analytics.identify([userId], [traits])`	Identifies the user. Traits-only calls keep the current user
`analytics.group(groupId, [traits])`	Sends a group call
`analytics.alias(userId)`	Links the current visitor to `userId` (an identify)
`analytics.reset()`	Forgets the signed-in user and their traits. The visitor ID is kept
`analytics.setAnonymousId(id)`	Uses `id` as the visitor ID, applied before the first event
`analytics.addSourceMiddleware(fn)`	Runs `fn({ payload, next })` on every call. `payload.obj` is the event; change `payload.obj.properties` and call `next(payload)`. A middleware that never calls `next` drops the event
`analytics.ready(fn)`	Calls `fn` once the collector is ready
`analytics.user()`	Returns `id()`, `anonymousId()` and `traits()`
`analytics.trackLink` / `trackForm`	Tracks clicks and form submits on the given elements
Code that kept a reference to the snippet’s stub	Reaches Datafly Signal too: the stub’s methods are rewired

Destination middleware, load, debug and on/off are accepted and ignored: delivery happens server-side, where each integration’s blueprint does the work client-side destinations used to do.

Set it up

Switch on analytics.js compatibility

In the management UI, open Pipelines → your pipeline → Collector. Under Migration on-ramp, tick analytics_compat, then build the collector.

Your site’s snippet already calls analytics.page() on load, so with compatibility on the collector doesn’t send its own first page view. Page views on single-page-app route changes still follow the pipeline’s page tracking setting.

Keep your visitor ID

If your site already sets its own visitor ID cookie and passes it to analytics.setAnonymousId(), set Who sets the anonymous ID cookie to Your website (Signal reads it) and enter that cookie’s name. Datafly Signal then uses the same ID from the first event, so visitor history carries on without a break.

Swap the script tag

Keep the inline snippet. Change the <script src> that loaded your previous library to the Datafly.js collector URL for the pipeline. If your snippet loads the library itself with analytics.load('<key>'), remove that call and add the Datafly.js <script> tag after the snippet.

Point collection at your first-party domain

Serve the collector from your first-party collection subdomain (for example collect.yourdomain.com, an A record). If you already have a collection subdomain, repoint it to the Datafly Signal gateway.

Check events in the Event Debugger

Turn on debug mode for the pipeline and browse the site. Every existing call appears with its original name and properties, including anything your source middleware adds.

Load Datafly.js directly in the page, never as a tag inside a tag manager. A tag manager is often blocked by ad blockers, and anything it loads is blocked with it.

Running both side by side

To compare counts before cutting over, leave your current library on window.analytics and give Datafly Signal another global. Set Global name (shown once compatibility is on) to, for example, shopAnalytics. Then copy each call to it from a source middleware your site already runs:

analytics.addSourceMiddleware(({ payload, next }) => {
  const e = payload.obj;
  if (window.shopAnalytics) {
    if (e.type === 'page') window.shopAnalytics.page(e.properties);
    if (e.type === 'track') window.shopAnalytics.track(e.event, e.properties);
  }
  next(payload);
});

Both platforms see the same events under the same visitor ID. At cut-over, set the global name back to analytics, swap the script tag and remove the middleware.

If Datafly.js finds a library that is already loaded (not a snippet stub) on the global it was given, it leaves it alone and logs a warning.

Configuration Overview