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/5] 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/5] 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/5] 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/5] 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/5] 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 ```