You're in the right place! Segment documentation is now part of Twilio Docs. The content you are used to is still here—just in a new home with a refreshed look.

Auto-Instrumentation Setup

This guide outlines the steps required to set up the Signals SDK in your JavaScript website.

Learn how to connect an existing source, integrate dependencies, turn on Auto-Instrumentation, and verify that your setup captures and processes data as intended.

(information)

Auto-Instrumentation in public beta

Auto-Instrumentation is in public beta, and Segment is actively working on this feature. Some functionality may change before it becomes generally available.

(information)

Regional availability

Auto-Instrumentation isn't supported in EU workspaces.

Step 1: Get your source write key

You need the writeKey from an existing Segment source. To find it:

In your Segment workspace, go to Connections > Sources.
Select your source.
From the source's overview tab, go to Settings > API Keys.
Copy the writeKey shown in the code block.

Step 2: Add dependencies and initialization code

Next, add the Signals SDKs to your web environment.

Choose the installation method that matches your setup:

Option A: For websites loading Segment through the HTML snippet.
Option B: For projects using npm, yarn, or pnpm.

Option A: Websites using the Segment snippet (HTML)

(warning)

Warning

Include only one Segment snippet per page. Replacing your existing snippet prevents duplicate analytics.load() calls.

If your site uses the standard Segment snippet, replace it with the following version, which includes the Signals SDK:

1<head>
2  <title>My Website</title>
3  <!-- Replace <YOUR_WRITE_KEY> in 'data-segment-write-key' -->
4  <script data-segment-write-key="<YOUR_WRITE_KEY>">
5    !(function () {
6      var i = "analytics",
7        analytics = (window[i] = window[i] || []);
8      if (!analytics.initialize)
9        if (analytics.invoked)
10          window.console &&
11            console.error &&
12            console.error("Segment snippet included twice.");
13        else {
14          analytics.invoked = !0;
15          analytics.methods = [
16            "trackSubmit",
17            "trackClick",
18            "trackLink",
19            "trackForm",
20            "pageview",
21            "identify",
22            "reset",
23            "group",
24            "track",
25            "ready",
26            "alias",
27            "debug",
28            "page",
29            "screen",
30            "once",
31            "off",
32            "on",
33            "addSourceMiddleware",
34            "addIntegrationMiddleware",
35            "setAnonymousId",
36            "addDestinationMiddleware",
37            "register",
38          ];
39          analytics.factory = function (e) {
40            return function () {
41              if (window[i].initialized)
42                return window[i][e].apply(window[i], arguments);
43              var n = Array.prototype.slice.call(arguments);
44              if (
45                [
46                  "track",
47                  "screen",
48                  "alias",
49                  "group",
50                  "page",
51                  "identify",
52                ].indexOf(e) > -1
53              ) {
54                var c = document.querySelector("link[rel='canonical']");
55                n.push({
56                  __t: "bpc",
57                  c: (c && c.getAttribute("href")) || void 0,
58                  p: location.pathname,
59                  u: location.href,
60                  s: location.search,
61                  t: document.title,
62                  r: document.referrer,
63                });
64              }
65              n.unshift(e);
66              analytics.push(n);
67              return analytics;
68            };
69          };
70          for (var n = 0; n < analytics.methods.length; n++) {
71            var key = analytics.methods[n];
72            analytics[key] = analytics.factory(key);
73          }
74          analytics._writeKey = document.currentScript.getAttribute("data-segment-write-key");
75
76          var r = document.getElementsByTagName("script")[0];
77          analytics.load = function (key, n) {
78            var t = document.createElement("script");
79            t.type = "text/javascript";
80            t.async = !0;
81            t.setAttribute("data-global-segment-analytics-key", i);
82            t.src =
83              "https://cdn.segment.com/analytics.js/v1/" +
84              key +
85              "/analytics.min.js";
86            r.parentNode.insertBefore(t, r);
87            analytics._loadOptions = n;
88          };
89
90          analytics.loadWithSignals = function (key, n) {
91            window.signalsPluginReady = function(SignalsPlugin) {
92              var signalsPlugin = new SignalsPlugin();
93              analytics.register(signalsPlugin);
94              analytics.load(key, n);
95            };
96            var signalsScript = document.createElement("script");
97            signalsScript.type = "text/javascript";
98            signalsScript.src =
99              "https://cdn.jsdelivr.net/npm/@segment/analytics-signals@latest/dist/umd/analytics-signals.umd.js";
100            signalsScript.async = !0;
101            r.parentNode.insertBefore(signalsScript, r);
102          };
103
104          analytics.loadWithSignals(analytics._writeKey);
105          analytics.page();
106        }
107    })();
108  </script>
109</head>

Verify that you only have one snippet in your site, then move on to Step 4: Verify and deploy events.

Option B: Install with a package manager

Add the Signals SDK to your project:

1# npm
2npm install @segment/analytics-signals
3# yarn
4yarn add @segment/analytics-signals
5# pnpm
6pnpm install @segment/analytics-signals

Add the initialization code and configuration options:

(success)

Success!

see configuration options for a complete list.

1// analytics.js/ts
2import { AnalyticsBrowser } from "@segment/analytics-next";
3import { SignalsPlugin } from "@segment/analytics-signals";
4
5export const analytics = new AnalyticsBrowser();
6
7const signalsPlugin = new SignalsPlugin();
8
9analytics.register(signalsPlugin);
10
11analytics.load({
12  writeKey: "<YOUR_WRITE_KEY>",
13});

Verify that you replaced <YOUR_WRITE_KEY> with the actual write key you copied in Step 1.

Build and run your app.

Step 3: Turn on Auto-Instrumentation in your source

Next, return to the source settings to turn on Auto-Instrumentation:

Go to Connections > Sources.
Select the source you used in Step 1.
From the source's overview tab, go to Settings > Analytics.js.
Toggle Auto-Instrumention on.

Step 4: Verify and deploy events

After integrating the SDK and running your app, verify that Segment is collecting signals:

In your Segment workspace, go to Connections > Sources and select the source you used for Auto-Instrumentation.
In the source overview, look for the Event Builder tab. If the tab doesn't appear:
- Make sure you've installed the SDK correctly.
- Verify that Auto Instrumentation is enabled in Settings > Analytics.js.
Open the Event Builder and follow the on-screen instructions to start signal detection.
- To collect signals in the UI, visit your site in a browser using the query string:?segment_signals_debug=true.
Interact with your app to trigger signals: click buttons, navigate pages, submit forms, and so on. Segment collects and displays these as signals in real time.
From the signals list, click Configure event to define a new event based on one or more signals. After configuring the event, click Publish event rules.

Debugging

Enable debug mode

User activity is not collected by default after SDK installation. To collect activity for use in building event rules, append the segment_signals_debug=true URL parameter.

https://my-website.com?segment_signals_debug=true

Loading the site with this debug URL parameter stays active in session storage until the tab or window is closed. Within a session the URL parameter does not need to be present on each page load.

You can turn off debugging by doing:

https://my-website.com?segment_signals_debug=false

Advanced

Signal redaction and debug visibility

The Signals SDK automatically hides sensitive values in user interactions before sending them to Segment.

To protect user data, the SDK replaces real values with safe, generic placeholders: strings become "XXX", numbers become 999, and booleans become true.

Redaction applies to everything the SDK collects, including:

Form submissions and text inputs
Clickable elements and their text content
Request bodies for tracked network calls
Certain DOM attributes observed by mutation listeners

If you're troubleshooting and want to see real values while debugging, you can disable redaction temporarily by adding this to your site URL:

?segment_signals_debug=true&segment_signals_disable_redaction=true

Use this only in a safe testing environment: disabling redaction can expose real user information (PII).

For persistent setups or automated testing, you can also control this behavior in code with:

new SignalsPlugin({ disableSignalRedaction: true })

For more information, see the configuration options table.

Emitting custom signals

If you need to listen for data that is unavailable to the Signals plugin by default, you can create and emit a custom signal:

1var signalsPlugin = new SignalsPlugin(); // or use the global variable if you registered it globally
2signalsPlugin.addSignal({ someData: 'foo' })
3
4
5// emits a signal with the following shape
6{
7  type: 'userDefined'
8  data: { someData: 'foo', ...  }
9}

Listening to signals

1const signalsPlugin = new SignalsPlugin();
2signalsPlugin.onSignal((signal) => console.log(signal));

Middleware / Plugins

You can drop or modify signals using middleware:

1import { SignalsPlugin, SignalsMiddleware } from "@segment/analytics-signals";
2
3class MyMiddleware implements SignalsMiddleware {
4  process(signal: Signal) {
5    // drop all instrumentation signals
6    if (signal.type === "instrumentation") {
7      return null;
8    } else {
9      return signal;
10    }
11  }
12}
13
14const signalsPlugin = new SignalsPlugin({
15  middleware: [new MyMiddleware()],
16});
17analytics.register(signalsPlugin);

Sandbox strategies

If you get CSP errors, you can use the experimental 'global' sandbox strategy:

new SignalsPlugin({ sandboxStrategy: "global" });

Configuration options

Using the Signals Configuration object, you can control the destination, frequency, and types of signals that Segment automatically tracks within your application. The following table details the configuration options for Signals Web.

`Option`	Required	Value	Description
`maxBufferSize`	No	number	The number of signals to be kept for JavaScript inspection. This buffer is first-in, first-out. Default is `1000`.
`enableDebugLogging`	No	boolean	Enable debug logs.
`disableSignalRedaction`	No	boolean	Disable default Signal data redaction.
`apiHost`	No	string	Override the default signals API host. Default is `signals.segment.io/v1`.
`functionHost`	No	string	Override the default edge host. Default is `cdn.edgefn.segment.com`
`flushAt`	No	number	How many signals to flush at once when sending to the signals API. Default is `5` .
`flushInterval`	No	number	How many ms to wait before flushing signals to the API. The default is `2000`.
`middleware`	No	SignalsMiddleware[]	Array of middleware to process signals before they are sent.
`sandboxStrategy`	No	'global' \| 'iframe'	Sandbox strategy for signal collection. Use 'global' if getting CSP errors. Default is 'iframe'.

Core Signal Types

Auto-Instrumentation collects different types of signals automatically:

`interaction`

Interaction signals emit in response to a user interaction (like clicks or form submissions)

`instrumentation`

Instrumentation signals emit whenever a Segment event is emitted.

`network`

Network signals emit when an HTTP Request is made, or an HTTP Response is received. To emit a network signal, the network activity must have the following requirements:

Initiated using the fetch API
First party domain (for example, if on foo.com, then foo.com/api/products, but not bar.com/api/products)
Contains the content-type: application/json

Troubleshooting

Here are the most common misconfigurations preventing signals from reaching Segment.

Not enabling signals with the URL parameter: You must start each debug session by appending ?segment_signals_debug=true to your URL parameters.
Running debug mode with an ad blocker: An active ad blocker prevents signals from reaching Segment. Disable your ad blocker and start a new session.
Content Security Policies: In addition to the default Analytics.js Content Security Policies, you must add cdn.jsdelivr.net to your allowlist, or https://cdn.jsdelivr.net/npm/@segment/analytics-signals@latest/dist/umd/analytics-signals.umd.js if your policies require the full path.

Next steps

This guide walked you through initial Signals SDK/Auto-Instrumentation setup. Next, read the Auto-Instrumentation Signals Implementation Guide, which dives deeper into Signals and offers example rules.