npm package: @snowplow/signals-browser-plugin
Description: Snowplow Signals Interventions SDK
Author: Snowplow Analytics Ltd
Latest version: 0.2.2

# Snowplow Signals Plugin

[![npm version][npm-image]][npm-url]
[![License][license-image]](LICENSE)

Browser Plugin to be used with [`@snowplow/browser-tracker`](https://github.com/snowplow/snowplow-javascript-tracker).

This plugin allows receiving and reacting to [Snowplow Signals](https://docs.snowplow.io/docs/signals/) interventions.

## Maintainer quick start

Build with [Node.js](https://nodejs.org/).

### Setup repository

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

## Package Installation

With npm:

```bash
npm install @snowplow/signals-browser-plugin
```

## Usage

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

```js
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](https://datatracker.ietf.org/doc/html/rfc6901) 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](https://docs.snowplow.io/docs/events/going-deeper/event-parameters/) 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:

```json
{
  "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](LICENSE) ([An OSI Approved License][osi]).

Copyright (c) 2025 Snowplow Analytics Ltd.

All rights reserved.

[npm-url]: https://www.npmjs.com/package/@snowplow/signals-browser-plugin
[npm-image]: https://img.shields.io/npm/v/@snowplow/signals-browser-plugin
[docs]: https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/javascript-tracker/
[osi]: https://opensource.org/license/apache-2-0
[license-image]: https://img.shields.io/npm/l/@snowplow/signals-browser-plugin