Skip to content

Commit 80450a3

Browse files
sileskysilesky
committed
update web setup
1 parent b99a151 commit 80450a3

File tree

1 file changed

+218
-50
lines changed

1 file changed

+218
-50
lines changed

‎src/connections/auto-instrumentation/web-setup.md‎

Lines changed: 218 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -5,39 +5,151 @@ hidden: true
55

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

8-
You'll learn how to add Auto-Instrumentation sources, integrate dependencies, and ensure that your setup captures and processes data as intended.
8+
You'll learn how to add Auto-Instrumentation sources, integrate dependencies, and ensure that your setup captures and processes data as intended.
99

1010
> info "Auto-Instrumentation Private Beta"
11-
> 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.
11+
> 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.
1212
1313
> success "Enable Auto-Instrumentation"
1414
> To enable Auto-Instrumentation in your Segment workspace, reach out to your dedicated account manager.
1515
1616
## Step 1: Add a source and get its write key
1717

18-
You'll first need to add a source and copy its write key:
18+
You'll first need to add a source and copy its write key:
1919

2020
1. In your Segment workspace, navigate to **Connections > Auto-Instrumentation** and click **Add source**.
2121
2. Select a source, give the source a name, and click **Save**.
22-
3. Return to **Connections > Sources** to view your sources.
22+
3. Return to **Connections > Sources** to view your sources.
2323
4. In the **My sources** table, find and click the new source you just set up.
24-
5. In the **Initialize the Client** section, look for and copy the `writeKey` displayed in the code block.
24+
5. In the **Initialize the Client** section, look for and copy the `writeKey` displayed in the code block.
2525

2626
## Step 2: Add dependencies and initialization code
2727

28-
Next, you'll need to add the Signals SDKs to your web environment.
28+
Next, you'll need to add the Signals SDKs to your web environment.
29+
30+
Choose one of the following installation methods based on your setup:
31+
32+
### Option A: Snippet Users (HTML)
33+
34+
For websites using the Segment snippet, add the SignalsPlugin using a CDN:
35+
36+
```html
37+
<head>
38+
<title>My Website</title>
39+
40+
<!-- Load Segment (find and replace '<YOUR_WRITE_KEY>') -->
41+
<script>
42+
!(function () {
43+
var i = "analytics",
44+
analytics = (window[i] = window[i] || []);
45+
if (!analytics.initialize)
46+
if (analytics.invoked)
47+
window.console &&
48+
console.error &&
49+
console.error("Segment snippet included twice.");
50+
else {
51+
analytics.invoked = !0;
52+
analytics.methods = [
53+
"trackSubmit",
54+
"trackClick",
55+
"trackLink",
56+
"trackForm",
57+
"pageview",
58+
"identify",
59+
"reset",
60+
"group",
61+
"track",
62+
"ready",
63+
"alias",
64+
"debug",
65+
"page",
66+
"screen",
67+
"once",
68+
"off",
69+
"on",
70+
"addSourceMiddleware",
71+
"addIntegrationMiddleware",
72+
"setAnonymousId",
73+
"addDestinationMiddleware",
74+
"register",
75+
];
76+
analytics.factory = function (e) {
77+
return function () {
78+
if (window[i].initialized)
79+
return window[i][e].apply(window[i], arguments);
80+
var n = Array.prototype.slice.call(arguments);
81+
if (
82+
[
83+
"track",
84+
"screen",
85+
"alias",
86+
"group",
87+
"page",
88+
"identify",
89+
].indexOf(e) > -1
90+
) {
91+
var c = document.querySelector("link[rel='canonical']");
92+
n.push({
93+
__t: "bpc",
94+
c: (c && c.getAttribute("href")) || void 0,
95+
p: location.pathname,
96+
u: location.href,
97+
s: location.search,
98+
t: document.title,
99+
r: document.referrer,
100+
});
101+
}
102+
n.unshift(e);
103+
analytics.push(n);
104+
return analytics;
105+
};
106+
};
107+
for (var n = 0; n < analytics.methods.length; n++) {
108+
var key = analytics.methods[n];
109+
analytics[key] = analytics.factory(key);
110+
}
111+
analytics.load = function (key, n) {
112+
var t = document.createElement("script");
113+
t.type = "text/javascript";
114+
t.async = !0;
115+
t.setAttribute("data-global-segment-analytics-key", i);
116+
t.src =
117+
"https://cdn.segment.com/analytics.js/v1/" +
118+
key +
119+
"/analytics.min.js";
120+
var r = document.getElementsByTagName("script")[0];
121+
r.parentNode.insertBefore(t, r);
122+
analytics._loadOptions = n;
123+
};
124+
// Replace with your Segment write key.
125+
analytics._writeKey = "<YOUR_WRITE_KEY>";
126+
analytics.SNIPPET_VERSION = "5.2.0";
127+
analytics.page();
128+
}
129+
})();
130+
</script>
131+
132+
<!-- Register SignalsPlugin -->
133+
<script src="https://cdn.jsdelivr.net/npm/@segment/analytics-signals@latest/dist/umd/analytics-signals.umd.js"></script>
134+
<script>
135+
var signalsPlugin = new SignalsPlugin()
136+
analytics.register);
137+
analytics.load(analytics._writeKey);
138+
</script>
139+
</head>
140+
```
29141

30-
Follow these steps to integrate the Signals SDK into your website:
142+
### Option B: NPM Users
31143

32-
1. Add the Signals SDK to your project:
144+
1. Add the Signals SDK to your project:
33145

34146
```bash
35-
# npm
36-
npm install @segment/analytics-signals
37-
# yarn
38-
yarn add @segment/analytics-signals
39-
# pnpm
40-
pnpm install @segment/analytics-signals
147+
# npm
148+
npm install @segment/analytics-signals
149+
# yarn
150+
yarn add @segment/analytics-signals
151+
# pnpm
152+
pnpm install @segment/analytics-signals
41153
```
42154

43155
2. Add the initialization code and configuration options:
@@ -47,21 +159,23 @@ Follow these steps to integrate the Signals SDK into your website:
47159
48160
```ts
49161
// analytics.js/ts
50-
import { AnalyticsBrowser } from '@segment/analytics-next'
51-
import { SignalsPlugin } from '@segment/analytics-signals'
162+
import { AnalyticsBrowser } from "@segment/analytics-next";
163+
import { SignalsPlugin } from "@segment/analytics-signals";
164+
165+
export const analytics = new AnalyticsBrowser();
52166

53-
const analytics = new AnalyticsBrowser()
54-
const signalsPlugin = new SignalsPlugin()
55-
analytics.register(signalsPlugin)
167+
const signalsPlugin = new SignalsPlugin();
168+
169+
analytics.register(signalsPlugin);
56170

57171
analytics.load({
58-
writeKey: '<YOUR_WRITE_KEY>'
59-
})
172+
writeKey: "<YOUR_WRITE_KEY>",
173+
});
60174
```
61175

62-
Verify that you replaced `<WRITE_KEY>` with the actual write key you copied in Step 1.
176+
Verify that you replaced `<YOUR_WRITE_KEY>` with the actual write key you copied in Step 1.
63177

64-
4. Build and run your app.
178+
3. Build and run your app.
65179

66180
## Step 3: Verify and deploy events
67181

@@ -92,48 +206,102 @@ https://my-website.com?segment_signals_debug=false
92206

93207
### Advanced
94208

95-
#### Emitting custom signals
209+
#### Emitting custom signals
210+
96211
If you need to listen for data that is unavailable to the Signals plugin by default, you can create and emit a custom signal:
97212

98213
```ts
99-
import { signalsPlugin } from './analytics' // assuming you exported your plugin instance.
214+
var signalsPlugin = new SignalsPlugin(); // or use the global variable if you registered it globally
215+
signalsPlugin.addSignal({ someData: 'foo' })
100216

101-
signalsPlugin.addSignal({
102-
type: 'userDefined',
103-
data: { foo: 'bar' }
104-
})
217+
218+
// emits a signal with the following shape
219+
{
220+
type: 'userDefined'
221+
data: { someData: 'foo', ... }
222+
}
105223
```
106224

107225
#### Listening to signals
226+
108227
```ts
109-
const signalsPlugin = new SignalsPlugin()
110-
signalsPlugin.onSignal((signal) => console.log(signal))
228+
const signalsPlugin = new SignalsPlugin();
229+
signalsPlugin.onSignal((signal) => console.log(signal));
111230
```
112231

113-
### Emitting Signals
232+
#### Middleware / Plugins
233+
234+
You can drop or modify signals using middleware:
235+
236+
```ts
237+
import { SignalsPlugin, SignalsMiddleware } from "@segment/analytics-signals";
238+
239+
class MyMiddleware implements SignalsMiddleware {
240+
process(signal: Signal) {
241+
// drop all instrumentation signals
242+
if (signal.type === "instrumentation") {
243+
return null;
244+
} else {
245+
return signal;
246+
}
247+
}
248+
}
249+
250+
const signalsPlugin = new SignalsPlugin({
251+
middleware: [new MyMiddleware()],
252+
});
253+
analytics.register(signalsPlugin);
254+
```
255+
256+
#### Sandbox Strategies
257+
258+
If getting CSP errors, you can use the experimental 'global' sandbox strategy:
259+
114260
```ts
115-
const signalsPlugin = new SignalsPlugin()
116-
signalsPlugin.addSignal({
117-
type: 'userDefined',
118-
data: { foo: 'bar' }
119-
})
261+
new SignalsPlugin({ sandboxStrategy: "global" });
120262
```
121263

122264
## Configuration Options
123265

124-
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.
125-
126-
| `Option` | Required | Value | Description |
127-
| ------------------- | -------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
128-
| `writeKey` | Yes | string | Source write key |
129-
| `maxBufferSize` | No | number | The number of signals to be kept for JavaScript inspection. This buffer is first-in, first-out. Default is `1000`. |
130-
| `processSignal` | No | string | Override the default signal processing function from the edge function. If this is set, the edge function will not be used.
131-
| `enableDebugLogging` | No | boolean | Enable debug logs.
132-
| `disableSignalRedaction` | No | boolean | Disable default Signal data redaction.
133-
| `apiHost` | No | string | Override the default signals API host. Default is `signals.segment.io/v1`.
134-
| `functionHost` | No | string | Override the default edge host. Default is `cdn.edgefn.segment.com`
135-
| `flushAt` | No | number | How many signals to flush at once when sending to the signals API. Default is `5` . |
136-
| `flushInterval` | No | number | How many ms to wait before flushing signals to the API. The default is `2000`. |
266+
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.
267+
268+
| `Option` | Required | Value | Description |
269+
| ------------------------ | -------- | -------------------- | ------------------------------------------------------------------------------------------------------------------ |
270+
| `maxBufferSize` | No | number | The number of signals to be kept for JavaScript inspection. This buffer is first-in, first-out. Default is `1000`. |
271+
| `enableDebugLogging` | No | boolean | Enable debug logs. |
272+
| `disableSignalRedaction` | No | boolean | Disable default Signal data redaction. |
273+
| `apiHost` | No | string | Override the default signals API host. Default is `signals.segment.io/v1`. |
274+
| `functionHost` | No | string | Override the default edge host. Default is `cdn.edgefn.segment.com` |
275+
| `flushAt` | No | number | How many signals to flush at once when sending to the signals API. Default is `5` . |
276+
| `flushInterval` | No | number | How many ms to wait before flushing signals to the API. The default is `2000`. |
277+
| `middleware` | No | SignalsMiddleware[] | Array of middleware to process signals before they are sent. |
278+
| `sandboxStrategy` | No | 'global' \| 'iframe' | Sandbox strategy for signal collection. Use 'global' if getting CSP errors. Default is 'iframe'. |
279+
280+
## Core Signal Types
281+
282+
Auto-Instrumentation collects different types of signals automatically:
283+
284+
### `interaction`
285+
286+
Interaction signals emit in response to a user interaction (clicks, form submissions, etc.)
287+
288+
### `instrumentation`
289+
290+
Instrumentation signals emit whenever a Segment event is emitted.
291+
292+
### `navigation`
293+
294+
Navigation signals emit whenever the URL changes.
295+
296+
> Note: you can also rely on the initial analytics.page() call, which you can access as an Instrumentation signal.
297+
298+
### `network`
299+
300+
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:
301+
302+
- Initiated using the `fetch` API
303+
- First party domain (e.g if on `foo.com`, then `foo.com/api/products`, but not `bar.com/api/products`)
304+
- Contains the content-type: `application/json`
137305

138306
## Next steps
139307

0 commit comments

Comments
 (0)