Snowplow Signals Plugin

Browser Plugin to be used with @snowplow/browser-tracker.

This plugin allows receiving and reacting to Snowplow Signals interventions.

Maintainer quick start

Build with Node.js.

Setup repository

git clone https://github.com/snowplow-incubator/signals-browser-plugin.git
npm install

Package Installation

With npm:

npm install @snowplow/signals-browser-plugin

Usage

Initialize your tracker with the SignalsPlugin, add a handler, and request interventions:

import { newTracker } from '@snowplow/browser-tracker';
import {
  SignalsPlugin,
  addInterventionHandlers,
  subscribeToInterventions,
} from '@snowplow/signals-browser-plugin';

newTracker('sp1', '{{collector_url}}', {
  appId: 'my-app-id',
  plugins: [SignalsPlugin()],
});

addInterventionHandlers({
  myHandler(intervention) {
    console.log('intervention received!', intervention);
  },
});

subscribeToInterventions({
  endpoint: '00000000-0000-0000-0000-000000000000.svc.snplow.net',
});

Configuration

Plugin Configuration

The plugin can be configured with the following options:

• handlers: Object containing handler functions to be called when interventions are received
• measurement: Configure defaults for the built-in events the plugin generates when interventions are received
  • delivery, dispatch_accept, dispatch_error: Set to false or a boolean-returning function to disable tracking events when interventions are received or handled
  • context: Set to an array of entities or entity-generating callbacks to add custom context to events generated by the plugin

Handlers

Handlers can be provided in the initial configuration via the handlers setting, or added dynamically after configuration using addInterventionHandlers().

Each handler function will receive the intervention instance payload and the associated BrowserTracker instance.

Handlers can also be removed via removeInterventionHandlers(), which takes an array of handler IDs.

Subscribing

Call subscribeToInterventions() to configure the fetcher and make a request for interventions.

It will automatically adjust its subscription to account for updated entity IDs; by default it extracts the standard domain_userid and domain_sessionid entities.

It takes the following options:

• endpoint (required): your Signals API URI to connect to; until this option is provided no connection will be made and no interventions will be received
• apiPath: The path to request from endpoint when fetching interventions. Defaults to /api/v1/interventions
• entityTargets: Configures how to extract entity IDs from Snowplow events that get observed (see below)
• entityIds: Object mapping explicit entity ID configurations to request, as an object
• connectionTimeoutMs: How long to wait for the initial network request to be accepted before aborting (default 2500 milliseconds)

You can call this function multiple times to update these settings, previous connections will be closed if necessary.

Entity Targets

The entityTargets setting lets you declare rules for entity IDs to extract from events that the Snowplow tracker generates.

You specify a map of entity name to a string (or array of strings) containing JSON Pointers that configure how to find the value to use as an ID. For arrays, if a JSON Pointer does not return a result, the next pointer in the array is tried until a value is found.

The JSON pointers are evaluated against Payload instances, so the fields use their Tracker Protocol names.

For convenience, the plugin will map enriched field-names to their Tracker Protocol equivalents so either work. The fields available are only those present in the actual event however, so values added during enrichment like geo_country will not work, beyond basic examples like event_name or page_urlpath which will be computed and work.

Entities and self-describing event payloads are mapped in a version independent manner, accessible under their tracker protocol fields, followed by vendor and name. Single-element arrays will be treated as scalars for convenience.

For example, the default entity IDs could alternatively be explicitly configured via:

{
  "domain_userid": ["duid", "domain_userid", "/context/com.snowplowanalytics.snowplow/client_session/userId"],
  "domain_sessionid": ["sid", "domain_sessionid", "/cx/com.snowplowanalytics.snowplow/client_session/sessionId"]
}

duid and domain_userid would both lookup the duid field so are redundant, but if not found the client_session entity will be examined. If the found value is null or undefined, the entity will be ignored until a later event supplies a matching value to use as ID.

Copyright and license

Licensed and distributed under the Apache 2 License (An OSI Approved License).

Copyright (c) 2025 Snowplow Analytics Ltd.

All rights reserved.