Deferred trackers

Adding a tracker

Each tracker is a JSON block that the browser never runs. data-defer-tracker names the adapter, and the block's JSON is the adapter's config.

<script type="application/json" data-defer-tracker="ga4">
  { "id": "G-XXXXXXX" }
</script>

Register the adapters a site uses before app.run(), importing them from the same module specifier the component loads from, because the registry lives in that module. Only the adapters you import are bundled.

import { registerTrackerAdapter } from '@parallelogram-js/core/components/DeferTracker';
import ga4 from '@parallelogram-js/core/adapters/ga4';

registerTrackerAdapter('ga4', ga4);

app.components.add(
  '[data-defer-tracker]',
  () => import('@parallelogram-js/core/components/DeferTracker')
);

Blocks must sit inside the element the framework observes, which is the body by default. Blocks in <head> or elsewhere are never mounted, and the first tracker to start logs a warning listing them.

Which scripts can load

Tracker blocks are markup, and adapters give the scripts they load the page's CSP nonce, so a block injected into a page could otherwise load any script. Limit what blocks can load when registering adapters.

import { registerTrackerAdapter } from '@parallelogram-js/core/components/DeferTracker';
import gtm from '@parallelogram-js/core/adapters/gtm';
import plausible from '@parallelogram-js/core/adapters/plausible';

registerTrackerAdapter('gtm', gtm, { ids: ['GTM-XXXXXX'] });
registerTrackerAdapter('plausible', plausible, { origins: ['https://stats.example.com'] });

• With ids, a block whose tracker id (its id, site, domain or scriptId) isn't listed gets the status error, logs a warning naming the tracker and id, and its adapter isn't called. Without ids, any id is accepted.
• A block's src loads only from the page's own origin, the vendor's origin that the adapter declares, or an origin listed in origins. Any other src gets the status error and a warning, and nothing loads. Fathom declares https://cdn.usefathom.com and Plausible https://plausible.io. A custom adapter declares its own as boot.origins.
• Register Tag Manager with ids: a container's Custom HTML tags run any script, so without them a block can load any container. DeferTracker logs a warning once when gtm starts without ids.

When trackers start

Trackers start on the first pointerdown, touchstart, keydown or click on the window. Without interaction, they start after a fallback: once the page's load event has fired, then 5 seconds, then the browser's next idle period, waiting at most 2 seconds for it where requestIdleCallback is supported.

configureDeferTracker() changes these, and must be called before the first tracker mounts.

data-defer-tracker-status on each block moves through pending, awaiting-consent, loading, booted, duplicate and error, and the block dispatches defer-tracker:booted or defer-tracker:error.

Consent

Give a block a consent category in its config and pass a resolver to setTrackerConsent(). The tracker waits, with the status awaiting-consent, until the resolver returns true for its category.

<script type="application/json" data-defer-tracker="meta-pixel">
  { "id": "1234567890", "consent": "marketing" }
</script>

import {
  setTrackerConsent,
  reevaluateTrackerConsent,
} from '@parallelogram-js/core/components/DeferTracker';

setTrackerConsent(category => consentBanner.allows(category), { requireCategory: true });

consentBanner.onChange(() => reevaluateTrackerConsent());

Waiting trackers check again when consent:granted is emitted on the event bus, or when reevaluateTrackerConsent() is called, which works without a bus. A resolver that throws counts as not granted. Without requireCategory, a block with no consent field starts without asking; with it, the block waits too, so a missing or misspelt field fails closed.

Consent is checked again before each page step, so a tracker stops recording later pages once consent is withdrawn. A vendor script that has already loaded can't be unloaded, so also call the vendor's own consent update, such as gtag('consent', 'update', …), or use an adapter's consentDefault so the vendor starts in a denied state.

Several blocks and later pages

A tracker is identified by its adapter name and its config's id, site, domain or scriptId, so two properties of the same kind both start. Each adapter's script loads once per page session.

• A second block for a tracker already on the page goes to the adapter's block step when its config differs, such as a Google Ads conversion beside a remarketing block with the same id. A repeated block, or a block for an adapter without a block step, is marked duplicate.
• When the router shows a new page, the adapter's page step runs for each tracker still on the page, for page views and conversions the vendor script doesn't record itself. A block for a loaded tracker that mounts on a later page runs the page step instead of starting the tracker again.

Adapters

Every adapter is at @parallelogram-js/core/adapters/<name>, and every block also accepts consent. Register each one under the name in the first column.

consentDefault for the Google adapters and Bing is an object such as { "ad_storage": "denied" }, queued before the tag starts.

Writing an adapter

An adapter is a function that starts the vendor's tracking for a block, with optional steps attached to it as properties. In this example, loadScript stands for your own function that adds a script and returns a Promise that settles when it loads.

function statsAdapter(config, { logger, eventBus, nonce }) {
  if (!config.id) {
    throw new Error('stats: no id in config');
  }
  window.stats = window.stats || [];
  window.stats.push(['init', config.id]);
  return loadScript('https://stats.example/script.js', nonce);
}

statsAdapter.page = (config, ctx, { url, mounted }) => {
  window.stats.push(['page', url]);
};

registerTrackerAdapter('stats', statsAdapter);

ctx holds the component's logger and eventBus, and the nonce for scripts the adapter adds. Steps that record something shared by every tag of a kind, such as a page view through one global queue, should record it once per address.

Functions

These are exported from @parallelogram-js/core/components/DeferTracker.