From 80450a35ec657e710059fa3f74a4b9f0e0a29fc1 Mon Sep 17 00:00:00 2001 From: Seth Silesky <5115498+silesky@users.noreply.github.com> Date: Thu, 7 Aug 2025 12:50:58 -0500 Subject: [PATCH 1/9] update web setup --- .../auto-instrumentation/web-setup.md | 268 ++++++++++++++---- 1 file changed, 218 insertions(+), 50 deletions(-) diff --git a/src/connections/auto-instrumentation/web-setup.md b/src/connections/auto-instrumentation/web-setup.md index 9367132762..d006b98f42 100644 --- a/src/connections/auto-instrumentation/web-setup.md +++ b/src/connections/auto-instrumentation/web-setup.md @@ -5,39 +5,151 @@ hidden: true This guide outlines the steps required to set up the Signals SDK in your JavaScript website. -You'll learn how to add Auto-Instrumentation sources, integrate dependencies, and ensure that your setup captures and processes data as intended. +You'll learn how to add Auto-Instrumentation sources, integrate dependencies, and ensure that your setup captures and processes data as intended. > info "Auto-Instrumentation Private Beta" -> Auto-Instrumentation is currently in Private Beta and is governed by Segment's [First Access and Beta Preview Terms](https://www.twilio.com/en-us/legal/tos){:target="_blank"}. Segment is actively iterating on and improving the Auto-Instrumentation user experience. +> Auto-Instrumentation is currently in Private Beta and is governed by Segment's [First Access and Beta Preview Terms](https://www.twilio.com/en-us/legal/tos){:target="\_blank"}. Segment is actively iterating on and improving the Auto-Instrumentation user experience. > success "Enable Auto-Instrumentation" > To enable Auto-Instrumentation in your Segment workspace, reach out to your dedicated account manager. ## Step 1: Add a source and get its write key -You'll first need to add a source and copy its write key: +You'll first need to add a source and copy its write key: 1. In your Segment workspace, navigate to **Connections > Auto-Instrumentation** and click **Add source**. 2. Select a source, give the source a name, and click **Save**. -3. Return to **Connections > Sources** to view your sources. +3. Return to **Connections > Sources** to view your sources. 4. In the **My sources** table, find and click the new source you just set up. -5. In the **Initialize the Client** section, look for and copy the `writeKey` displayed in the code block. +5. In the **Initialize the Client** section, look for and copy the `writeKey` displayed in the code block. ## Step 2: Add dependencies and initialization code -Next, you'll need to add the Signals SDKs to your web environment. +Next, you'll need to add the Signals SDKs to your web environment. + +Choose one of the following installation methods based on your setup: + +### Option A: Snippet Users (HTML) + +For websites using the Segment snippet, add the SignalsPlugin using a CDN: + +```html + + My Website + + + + + + + + +``` -Follow these steps to integrate the Signals SDK into your website: +### Option B: NPM Users -1. Add the Signals SDK to your project: +1. Add the Signals SDK to your project: ```bash - # npm - npm install @segment/analytics-signals - # yarn - yarn add @segment/analytics-signals - # pnpm - pnpm install @segment/analytics-signals +# npm +npm install @segment/analytics-signals +# yarn +yarn add @segment/analytics-signals +# pnpm +pnpm install @segment/analytics-signals ``` 2. Add the initialization code and configuration options: @@ -47,21 +159,23 @@ Follow these steps to integrate the Signals SDK into your website: ```ts // analytics.js/ts -import { AnalyticsBrowser } from '@segment/analytics-next' -import { SignalsPlugin } from '@segment/analytics-signals' +import { AnalyticsBrowser } from "@segment/analytics-next"; +import { SignalsPlugin } from "@segment/analytics-signals"; + +export const analytics = new AnalyticsBrowser(); -const analytics = new AnalyticsBrowser() -const signalsPlugin = new SignalsPlugin() -analytics.register(signalsPlugin) +const signalsPlugin = new SignalsPlugin(); + +analytics.register(signalsPlugin); analytics.load({ - writeKey: '' -}) + writeKey: "", +}); ``` -Verify that you replaced `` with the actual write key you copied in Step 1. +Verify that you replaced `` with the actual write key you copied in Step 1. -4. Build and run your app. +3. Build and run your app. ## Step 3: Verify and deploy events @@ -92,48 +206,102 @@ https://my-website.com?segment_signals_debug=false ### Advanced -#### Emitting custom signals +#### 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: ```ts -import { signalsPlugin } from './analytics' // assuming you exported your plugin instance. +var signalsPlugin = new SignalsPlugin(); // or use the global variable if you registered it globally +signalsPlugin.addSignal({ someData: 'foo' }) -signalsPlugin.addSignal({ - type: 'userDefined', - data: { foo: 'bar' } -}) + +// emits a signal with the following shape +{ + type: 'userDefined' + data: { someData: 'foo', ... } +} ``` #### Listening to signals + ```ts -const signalsPlugin = new SignalsPlugin() -signalsPlugin.onSignal((signal) => console.log(signal)) +const signalsPlugin = new SignalsPlugin(); +signalsPlugin.onSignal((signal) => console.log(signal)); ``` -### Emitting Signals +#### Middleware / Plugins + +You can drop or modify signals using middleware: + +```ts +import { SignalsPlugin, SignalsMiddleware } from "@segment/analytics-signals"; + +class MyMiddleware implements SignalsMiddleware { + process(signal: Signal) { + // drop all instrumentation signals + if (signal.type === "instrumentation") { + return null; + } else { + return signal; + } + } +} + +const signalsPlugin = new SignalsPlugin({ + middleware: [new MyMiddleware()], +}); +analytics.register(signalsPlugin); +``` + +#### Sandbox Strategies + +If getting CSP errors, you can use the experimental 'global' sandbox strategy: + ```ts -const signalsPlugin = new SignalsPlugin() -signalsPlugin.addSignal({ - type: 'userDefined', - data: { foo: 'bar' } -}) +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-Kotlin. - -| `Option` | Required | Value | Description | -| ------------------- | -------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `writeKey` | Yes | string | Source write key | -| `maxBufferSize` | No | number | The number of signals to be kept for JavaScript inspection. This buffer is first-in, first-out. Default is `1000`. | -| `processSignal` | No | string | Override the default signal processing function from the edge function. If this is set, the edge function will not be used. -| `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`. | +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 (clicks, form submissions, etc.) + +### `instrumentation` + +Instrumentation signals emit whenever a Segment event is emitted. + +### `navigation` + +Navigation signals emit whenever the URL changes. + +> Note: you can also rely on the initial analytics.page() call, which you can access as an Instrumentation signal. + +### `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 (e.g if on `foo.com`, then `foo.com/api/products`, but not `bar.com/api/products`) +- Contains the content-type: `application/json` ## Next steps From 34409dbd2211cf1bc13c024cab0a2b7fa81289da Mon Sep 17 00:00:00 2001 From: Seth Silesky <5115498+silesky@users.noreply.github.com> Date: Thu, 7 Aug 2025 13:24:07 -0500 Subject: [PATCH 2/9] wip --- .../auto-instrumentation/web-setup.md | 59 +++++++++++-------- 1 file changed, 36 insertions(+), 23 deletions(-) diff --git a/src/connections/auto-instrumentation/web-setup.md b/src/connections/auto-instrumentation/web-setup.md index d006b98f42..6728812cfb 100644 --- a/src/connections/auto-instrumentation/web-setup.md +++ b/src/connections/auto-instrumentation/web-setup.md @@ -31,14 +31,16 @@ Choose one of the following installation methods based on your setup: ### Option A: Snippet Users (HTML) -For websites using the Segment snippet, add the SignalsPlugin using a CDN: +For websites using the Segment snippet, please REPLACE the regular Segment snippet with the following code, which includes the Signals SDK: + +> warning "" +> If you are currently using Segment, replace the existing Segment snippet that loads analytics.js with the modified code below. You should not have two segment snippets that call analytics.load() in your html. ```html My Website - - - - - - - ``` @@ -183,23 +188,31 @@ After integrating the SDK and running your app, verify that Segment is collectin 1. In your Segment workspace, return to **Connections > Sources**, then select the source you created for Auto-Instrumentation. 2. In the source overview, look for the **Event Builder** tab. If the tab doesn’t appear: - - Make sure you've installed the SDK correctly. - - Reach out to your Segment CSM to confirm that your workspace has the necessary feature flags enabled. + +- Make sure you've installed the SDK correctly. +- Reach out to your Segment CSM to confirm that your workspace has the necessary feature flags enabled. ![The Event Builder tab shown in the navigation bar between Debugger and Schema in a Segment Source](images/event_builder_tab.png) -3. 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` + +3. 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` + 4. 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. 5. 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 + Values sent to the signals API are redacted by default. -This adds a local storage key. To disable redaction, add a magic query string: +This adds a local storage key. To disable redaction, add a magic query string: + ``` https://my-website.com?segment_signals_debug=true ``` -You can *turn off debugging* by doing: + +You can _turn off debugging_ by doing: + ``` https://my-website.com?segment_signals_debug=false ``` @@ -305,4 +318,4 @@ Network signals emit when an HTTP Request is made, or an HTTP Response is receiv ## Next steps -This guide walked you through initial Signals SDK/Auto-Instrumentation setup. Next, read the [Auto-Instrumentation Signals Implementation Guide](/docs/connections/auto-instrumentation/configuration/), which dives deeper into Signals and offers example rules. +This guide walked you through initial Signals SDK/Auto-Instrumentation setup. Next, read the [Auto-Instrumentation Signals Implementation Guide](/docs/connections/auto-instrumentation/configuration/), which dives deeper into Signals and offers example rules. From 0db2a839687c0e988b5e8a4daf3e33890b83df4a Mon Sep 17 00:00:00 2001 From: Seth Silesky <5115498+silesky@users.noreply.github.com> Date: Fri, 8 Aug 2025 12:31:52 -0500 Subject: [PATCH 3/9] update snippet --- .../auto-instrumentation/web-setup.md | 196 +++++++++--------- 1 file changed, 99 insertions(+), 97 deletions(-) diff --git a/src/connections/auto-instrumentation/web-setup.md b/src/connections/auto-instrumentation/web-setup.md index 6728812cfb..5b6a096214 100644 --- a/src/connections/auto-instrumentation/web-setup.md +++ b/src/connections/auto-instrumentation/web-setup.md @@ -41,105 +41,107 @@ For websites using the Segment snippet, please REPLACE the regular Segment snipp My Website ``` From b91a0bceef914759ae38d75f694995b6ae683cc1 Mon Sep 17 00:00:00 2001 From: Seth Silesky <5115498+silesky@users.noreply.github.com> Date: Fri, 8 Aug 2025 12:39:59 -0500 Subject: [PATCH 4/9] wip --- src/connections/auto-instrumentation/web-setup.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/connections/auto-instrumentation/web-setup.md b/src/connections/auto-instrumentation/web-setup.md index 5b6a096214..b253a56d27 100644 --- a/src/connections/auto-instrumentation/web-setup.md +++ b/src/connections/auto-instrumentation/web-setup.md @@ -8,7 +8,7 @@ This guide outlines the steps required to set up the Signals SDK in your JavaScr You'll learn how to add Auto-Instrumentation sources, integrate dependencies, and ensure that your setup captures and processes data as intended. > info "Auto-Instrumentation Private Beta" -> Auto-Instrumentation is currently in Private Beta and is governed by Segment's [First Access and Beta Preview Terms](https://www.twilio.com/en-us/legal/tos){:target="\_blank"}. Segment is actively iterating on and improving the Auto-Instrumentation user experience. +> Auto-Instrumentation is currently in Private Beta and is governed by Segment's [First Access and Beta Preview Terms](https://www.twilio.com/en-us/legal/tos){:target="_blank"}. Segment is actively iterating on and improving the Auto-Instrumentation user experience. > success "Enable Auto-Instrumentation" > To enable Auto-Instrumentation in your Segment workspace, reach out to your dedicated account manager. @@ -139,7 +139,6 @@ For websites using the Segment snippet, please REPLACE the regular Segment snipp analytics._writeKey = document.currentScript.getAttribute("data-segment-write-key"); analytics.load(analytics._writeKey) analytics.page() - analytics.SNIPPET_VERSION = "5.2.0"; } })(); From c53144bf0846774d7456ff1218c937c25753ff27 Mon Sep 17 00:00:00 2001 From: Seth Silesky <5115498+silesky@users.noreply.github.com> Date: Fri, 8 Aug 2025 13:35:45 -0500 Subject: [PATCH 5/9] wip --- .../auto-instrumentation/web-setup.md | 187 +++++++++--------- 1 file changed, 95 insertions(+), 92 deletions(-) diff --git a/src/connections/auto-instrumentation/web-setup.md b/src/connections/auto-instrumentation/web-setup.md index b253a56d27..99e32b3565 100644 --- a/src/connections/auto-instrumentation/web-setup.md +++ b/src/connections/auto-instrumentation/web-setup.md @@ -41,106 +41,109 @@ For websites using the Segment snippet, please REPLACE the regular Segment snipp My Website ``` From 1b26af5fc4841f3866a41a563408a02756716d15 Mon Sep 17 00:00:00 2001 From: pwseg <86626706+pwseg@users.noreply.github.com> Date: Tue, 12 Aug 2025 16:16:06 -0700 Subject: [PATCH 6/9] [netlify-build] --- src/connections/auto-instrumentation/web-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/connections/auto-instrumentation/web-setup.md b/src/connections/auto-instrumentation/web-setup.md index 99e32b3565..566fb1e409 100644 --- a/src/connections/auto-instrumentation/web-setup.md +++ b/src/connections/auto-instrumentation/web-setup.md @@ -31,7 +31,7 @@ Choose one of the following installation methods based on your setup: ### Option A: Snippet Users (HTML) -For websites using the Segment snippet, please REPLACE the regular Segment snippet with the following code, which includes the Signals SDK: +For websites using the Segment snippet, you'll need to replace the regular Segment snippet with the following code, which includes the Signals SDK: > warning "" > If you are currently using Segment, replace the existing Segment snippet that loads analytics.js with the modified code below. You should not have two segment snippets that call analytics.load() in your html. From c7aa390c3715227287f00025e412c3bb60569f8d Mon Sep 17 00:00:00 2001 From: pwseg Date: Tue, 12 Aug 2025 19:34:20 -0700 Subject: [PATCH 7/9] some minor rewording --- .../auto-instrumentation/web-setup.md | 60 ++++++++++--------- 1 file changed, 32 insertions(+), 28 deletions(-) diff --git a/src/connections/auto-instrumentation/web-setup.md b/src/connections/auto-instrumentation/web-setup.md index 566fb1e409..22bec5a4dc 100644 --- a/src/connections/auto-instrumentation/web-setup.md +++ b/src/connections/auto-instrumentation/web-setup.md @@ -27,14 +27,17 @@ You'll first need to add a source and copy its write key: Next, you'll need to add the Signals SDKs to your web environment. -Choose one of the following installation methods based on your setup: +Choose the installation method that matches your setup: -### Option A: Snippet Users (HTML) +- **Option A:** For websites loading Segment through the HTML snippet. +- **Option B:** For projects using npm, yarn, or pnpm. -For websites using the Segment snippet, you'll need to replace the regular Segment snippet with the following code, which includes the Signals SDK: +### Option A: Websites using the Segment snippet (HTML) > warning "" -> If you are currently using Segment, replace the existing Segment snippet that loads analytics.js with the modified code below. You should not have two segment snippets that call analytics.load() in your html. +> 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: ```html @@ -148,41 +151,42 @@ For websites using the Segment snippet, you'll need to replace the regular Segme ``` -### Option B: NPM Users +Verify that you only have **one snippet** in your site, then move to -1. Add the Signals SDK to your project: +### Option B: Install with a package manager -```bash -# npm -npm install @segment/analytics-signals -# yarn -yarn add @segment/analytics-signals -# pnpm -pnpm install @segment/analytics-signals -``` +1. Add the Signals SDK to your project: + ```bash + # npm + npm install @segment/analytics-signals + # yarn + yarn add @segment/analytics-signals + # pnpm + pnpm install @segment/analytics-signals + ``` 2. Add the initialization code and configuration options: -> success "" -> see [configuration options](#configuration-options) for a complete list. + > success "" + > see [configuration options](#configuration-options) for a complete list. -```ts -// analytics.js/ts -import { AnalyticsBrowser } from "@segment/analytics-next"; -import { SignalsPlugin } from "@segment/analytics-signals"; + ```ts + // analytics.js/ts + import { AnalyticsBrowser } from "@segment/analytics-next"; + import { SignalsPlugin } from "@segment/analytics-signals"; -export const analytics = new AnalyticsBrowser(); + export const analytics = new AnalyticsBrowser(); -const signalsPlugin = new SignalsPlugin(); + const signalsPlugin = new SignalsPlugin(); -analytics.register(signalsPlugin); + analytics.register(signalsPlugin); -analytics.load({ - writeKey: "", -}); -``` + analytics.load({ + writeKey: "", + }); + ``` -Verify that you replaced `` with the actual write key you copied in Step 1. + Verify that you replaced `` with the actual write key you copied in Step 1. 3. Build and run your app. From 0f049fb53873a5e2fe92fdaf7073ce7369da7c25 Mon Sep 17 00:00:00 2001 From: pwseg Date: Tue, 12 Aug 2025 19:39:18 -0700 Subject: [PATCH 8/9] style guide + formatting fixes --- .../auto-instrumentation/web-setup.md | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/src/connections/auto-instrumentation/web-setup.md b/src/connections/auto-instrumentation/web-setup.md index 22bec5a4dc..4a351f3f33 100644 --- a/src/connections/auto-instrumentation/web-setup.md +++ b/src/connections/auto-instrumentation/web-setup.md @@ -196,15 +196,12 @@ After integrating the SDK and running your app, verify that Segment is collectin 1. In your Segment workspace, return to **Connections > Sources**, then select the source you created for Auto-Instrumentation. 2. In the source overview, look for the **Event Builder** tab. If the tab doesn’t appear: - -- Make sure you've installed the SDK correctly. -- Reach out to your Segment CSM to confirm that your workspace has the necessary feature flags enabled. - ![The Event Builder tab shown in the navigation bar between Debugger and Schema in a Segment Source](images/event_builder_tab.png) + - Make sure you've installed the SDK correctly. + - Reach out to your Segment CSM to confirm that your workspace has the necessary feature flags enabled. + ![The Event Builder tab shown in the navigation bar between Debugger and Schema in a Segment Source](images/event_builder_tab.png) 3. 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` - + - To collect signals in the UI, visit your site in a browser using the query string:`?segment_signals_debug=true` 4. 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. 5. 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**. @@ -276,7 +273,7 @@ analytics.register(signalsPlugin); #### Sandbox Strategies -If getting CSP errors, you can use the experimental 'global' sandbox strategy: +If you get CSP errors, you can use the experimental 'global' sandbox strategy: ```ts new SignalsPlugin({ sandboxStrategy: "global" }); @@ -304,7 +301,7 @@ Auto-Instrumentation collects different types of signals automatically: ### `interaction` -Interaction signals emit in response to a user interaction (clicks, form submissions, etc.) +Interaction signals emit in response to a user interaction (like clicks or form submissions) ### `instrumentation` @@ -321,7 +318,7 @@ Navigation signals emit whenever the URL changes. 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 (e.g if on `foo.com`, then `foo.com/api/products`, but not `bar.com/api/products`) +- 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` ## Next steps From 7d8c76fd8e08f2504ea1a20937d79598cc07c758 Mon Sep 17 00:00:00 2001 From: pwseg <86626706+pwseg@users.noreply.github.com> Date: Tue, 12 Aug 2025 20:08:50 -0700 Subject: [PATCH 9/9] link fix --- src/connections/auto-instrumentation/web-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/connections/auto-instrumentation/web-setup.md b/src/connections/auto-instrumentation/web-setup.md index 4a351f3f33..77285f0a59 100644 --- a/src/connections/auto-instrumentation/web-setup.md +++ b/src/connections/auto-instrumentation/web-setup.md @@ -151,7 +151,7 @@ If your site uses the standard Segment snippet, **replace it** with the followin ``` -Verify that you only have **one snippet** in your site, then move to +Verify that you only have **one snippet** in your site, then move to [Step 3: Verify and deploy events](#step-3-verify-and-deploy-events). ### Option B: Install with a package manager