Skip to content

Commit 6463153

Browse files
alanjcharlesalanjcharles
committed
add web setup guide to auto-inst [netlify-build]
1 parent b1943e0 commit 6463153

File tree

5 files changed

+258
-62
lines changed

5 files changed

+258
-62
lines changed

‎Gemfile.lock

+10-5
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,7 @@ GEM
4545
ffi (1.15.5)
4646
filesize (0.2.0)
4747
forwardable-extended (2.6.0)
48+
google-protobuf (3.23.2-arm64-darwin)
4849
google-protobuf (3.23.2-x86_64-darwin)
4950
http_parser.rb (0.8.0)
5051
httpclient (2.8.3)
@@ -87,7 +88,9 @@ GEM
8788
rb-fsevent (~> 0.10, >= 0.10.3)
8889
rb-inotify (~> 0.9, >= 0.9.10)
8990
mercenary (0.4.0)
90-
nokogiri (1.15.2-x86_64-darwin)
91+
nokogiri (1.13.10-arm64-darwin)
92+
racc (~> 1.4)
93+
nokogiri (1.13.10-x86_64-darwin)
9194
racc (~> 1.4)
9295
pathutil (0.16.2)
9396
forwardable-extended (~> 2.6)
@@ -101,10 +104,12 @@ GEM
101104
rb-inotify (0.10.1)
102105
ffi (~> 1.0)
103106
rexml (3.2.5)
104-
rouge (4.1.2)
107+
rouge (3.30.0)
105108
ruby2_keywords (0.0.5)
106109
safe_yaml (1.0.5)
107-
sass-embedded (1.62.1-x86_64-darwin)
110+
sass-embedded (1.58.3-arm64-darwin)
111+
google-protobuf (~> 3.21)
112+
sass-embedded (1.58.3-x86_64-darwin)
108113
google-protobuf (~> 3.21)
109114
terminal-table (3.0.2)
110115
unicode-display_width (>= 1.1.1, < 3)
@@ -119,7 +124,7 @@ GEM
119124
webrick (1.8.1)
120125

121126
PLATFORMS
122-
ruby
127+
arm64-darwin-23
123128
x86_64-darwin-19
124129
x86_64-darwin-20
125130

@@ -141,4 +146,4 @@ DEPENDENCIES
141146
wdm (~> 0.1.0)
142147

143148
BUNDLED WITH
144-
2.2.18
149+
2.4.5

‎src/connections/auto-instrumentation/index.md

+45-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,25 @@
11
---
22
title: Auto-Instrumentation
33
hidden: true
4+
sources:
5+
- name: Android
6+
url: /connections/auto-instrumentation/kotlin-setup/
7+
logo:
8+
url: https://cdn.filepicker.io/api/file/9BoiIqVRFmsAuBbMMy9D
9+
mark:
10+
url: https://cdn.filepicker.io/api/file/9BoiIqVRFmsAuBbMMy9D
11+
- name: Apple
12+
url: /connections/auto-instrumentation/swift-setup/
13+
logo:
14+
url: https://cdn.filepicker.io/api/file/qWgSP5cpS7eeW2voq13u
15+
mark:
16+
url: https://cdn.filepicker.io/api/file/qWgSP5cpS7eeW2voq13u
17+
- name: Web
18+
url: /connections/auto-instrumentation/web-setup/
19+
logo:
20+
url: https://cdn.filepicker.io/api/file/aRgo4XJQZausZxD4gZQq
21+
mark:
22+
url: https://cdn.filepicker.io/api/file/aRgo4XJQZausZxD4gZQq
423
---
524

625
Auto-Instrumentation simplifies tracking in your websites and apps by eliminating the need for a traditional Segment instrumentation.
@@ -29,10 +48,35 @@ Some Auto-Instrumentation advantages include:
2948

3049
## How it works
3150

32-
After you [integrate the Analytics SDK and Signals SDK into your application](/docs/connections/auto-instrumentation/setup/), Segment begins to passively monitor user activity like button clicks, page navigation, and network data. Segment captures these events as "signals" and sends them to your Auto-Instrumentation source in real time.
51+
Once you integrate the Analytics SDK and Signals SDK into your website or application, Segment begins to passively monitor user activity like button clicks, page navigation, and network data. Segment captures these events as "signals" and sends them to your Auto-Instrumentation source in real time.
3352

3453
In Segment, the Auto-Instrumentation source lets you view raw signals. You can then [use this data to create detailed analytics events](/docs/connections/auto-instrumentation/configuration/) based on those signals, enriching your insights into user behavior and applicatino performance.
3554

55+
## Setup Guides
56+
57+
<div class="auto-instrumentation-catalog">
58+
<div class="auto-insturmentation__section markdown" id="{{ category | slugify }}">
59+
<div class="flex flex--wrap waffle waffle--xlarge">
60+
{% assign category = "source" %}
61+
{% assign resources = page.sources %}
62+
{% for resource in resources %}
63+
<div class="flex__column flex__column--6">
64+
<a class="thumbnail-integration flex flex--middle" href="{{ site.baseurl }}/{{ resource.url }}">
65+
<div class="thumbnail-integration__content">
66+
<div class="flex flex--wrap flex--middle waffle waffle--xlarge@medium">
67+
<div class="flex__column flex__column--12 flex__column--2@medium thumbnail-integration__logo-wrapper">
68+
<img class="thumbnail-integration__logo image" alt="{{resource.name}}" src="{{resource.mark.url}}" />
69+
</div>
70+
<h5 class="flex__column flex__column--12 flex__column--10@medium">{{ resource.name }}</h5>
71+
</div>
72+
</div>
73+
</a>
74+
</div>
75+
{% endfor %}
76+
</div>
77+
</div>
78+
</div>
79+
3680
## Privacy
3781

3882
Auto-Instrumentation removes personally identifiable information (PII) from breadcrumbs before they get sent to Segment. No user data is visible to Segment.

‎src/connections/auto-instrumentation/setup.md renamed to ‎src/connections/auto-instrumentation/kotlin-setup.md

+2-56
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: Auto-Instrumentation Setup
33
hidden: true
44
---
55

6-
This guide outlines the steps required to set up the Signals SDK in your applications using Swift or Kotlin.
6+
This guide outlines the steps required to set up the Signals SDK in your Android OS applications using Kotlin.
77

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

@@ -25,61 +25,7 @@ You'll first need to add a source and copy its write key:
2525

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

28-
Next, you'll need to add the Signals SDKs to your Swift and Kotlin development environments.
29-
30-
### Swift
31-
32-
Follow these steps to integrate the Signals SDK into your Swift application:
33-
34-
1. Use Swift Package Manager to add the Signals SDK from the following repository:
35-
36-
```zsh
37-
https://github.com/segmentio/Signals-swift.git
38-
```
39-
40-
2. Add the initialization code:
41-
42-
```swift
43-
// Configure Analytics with your settings
44-
{... <analytics config>....}
45-
46-
// Set up the Signals SDK configuration
47-
let config = Signals.Configuration(
48-
writeKey: "<WRITE_KEY>", // Replace <WRITE_KEY> with the write key you previously copied
49-
maximumBufferSize: 100,
50-
useSwiftUIAutoSignal: true,
51-
useNetworkAutoSignal: true
52-
)
53-
54-
// Locate and set the fallback JavaScript file for edge functions
55-
let fallbackURL = Bundle.main.url(forResource: "MyEdgeFunctions", withExtension: "js")
56-
57-
// Apply the configuration and add the Signals plugin
58-
Signals.shared.useConfiguration(config)
59-
Analytics.main.add(plugin: LivePlugins(fallbackFileURL: fallbackURL))
60-
Analytics.main.add(plugin: Signals.shared)
61-
```
62-
63-
Verify that you replaced `<WRITE_KEY>` with the actual write key you copied in Step 1.
64-
65-
#### SwiftUI projects
66-
67-
If your app is written in SwiftUI, you'll need to add a `TypeAlias.swift` file to your project that captures interaction and navigation Signals, like in this example:
68-
69-
```swift
70-
import Foundation
71-
import Signals
72-
73-
typealias Button = SignalButton
74-
typealias NavigationStack = SignalNavigationStack
75-
typealias NavigationLink = SignalNavigationLink
76-
typealias TextField = SignalTextField
77-
typealias SecureField = SignalSecureField
78-
```
79-
80-
### Kotlin
81-
82-
Follow these steps to integrate the Signals SDK into your Kotlin application:
28+
Next, you'll need to add the Signals SDKs to your Kotlin application.
8329

8430
1. Update your module’s Gradle build file to add the right dependencies:
8531

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

+92
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
---
2+
title: Auto-Instrumentation Setup
3+
hidden: true
4+
---
5+
6+
This guide outlines the steps required to set up the Signals SDK in your Apple OS applications using Swift.
7+
8+
You'll learn how to add Auto-Instrumentation sources, integrate dependencies, and ensure that your setup captures and processes data as intended.
9+
10+
> info "Auto-Instrumentation Pilot"
11+
> Auto-Instrumentation is currently in pilot and is governed by Segment's [First Access and Beta Preview Terms](https://www.twilio.com/en-us/legal/tos){:target="_blank"}. Segment doesn't recommend Auto-Instrumentation for use in a production environment, as Segment is actively iterating on and improving the user experience.
12+
13+
> success "Enable Auto-Instrumentation"
14+
> To enable Auto-Instrumentation in your Segment workspace, reach out to your dedicated account manager.
15+
16+
## Step 1: Add a source and get its write key
17+
18+
You'll first need to add a source and copy its write key:
19+
20+
1. In your Segment workspace, navigate to **Connections > Auto-Instrumentation** and click **Add source**.
21+
2. Select a source, give the source a name, and click **Save**.
22+
3. Return to **Connections > Sources** to view your sources.
23+
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.
25+
26+
## Step 2: Add dependencies and initialization code
27+
28+
Next, you'll need to add the Signals SDKs to your Swift applicatiion.
29+
30+
1. Use Swift Package Manager to add the Signals SDK from the following repository:
31+
32+
```zsh
33+
https://github.com/segmentio/Signals-swift.git
34+
```
35+
36+
2. Add the initialization code:
37+
38+
```swift
39+
// Configure Analytics with your settings
40+
{... <analytics config>....}
41+
42+
// Set up the Signals SDK configuration
43+
let config = Signals.Configuration(
44+
writeKey: "<WRITE_KEY>", // Replace <WRITE_KEY> with the write key you previously copied
45+
maximumBufferSize: 100,
46+
useSwiftUIAutoSignal: true,
47+
useNetworkAutoSignal: true
48+
)
49+
50+
// Locate and set the fallback JavaScript file for edge functions
51+
let fallbackURL = Bundle.main.url(forResource: "MyEdgeFunctions", withExtension: "js")
52+
53+
// Apply the configuration and add the Signals plugin
54+
Signals.shared.useConfiguration(config)
55+
Analytics.main.add(plugin: LivePlugins(fallbackFileURL: fallbackURL))
56+
Analytics.main.add(plugin: Signals.shared)
57+
```
58+
59+
Verify that you replaced `<WRITE_KEY>` with the actual write key you copied in Step 1.
60+
61+
#### SwiftUI projects
62+
63+
If your app is written in SwiftUI, you'll need to add a `TypeAlias.swift` file to your project that captures interaction and navigation Signals, like in this example:
64+
65+
```swift
66+
import Foundation
67+
import Signals
68+
69+
typealias Button = SignalButton
70+
typealias NavigationStack = SignalNavigationStack
71+
typealias NavigationLink = SignalNavigationLink
72+
typealias TextField = SignalTextField
73+
typealias SecureField = SignalSecureField
74+
```
75+
## Step 3: Verify and deploy events
76+
77+
Next, you'll need to verify signal emission and [create rules](/docs/connections/auto-instrumentation/configuration/#example-rule-implementations) to convert those signals into events:
78+
79+
1. In your Segment workspace, return to **Connections > Auto-Instrumentation** and click on the new source you created.
80+
2. Verify that signals appear as expected on the dashboard.
81+
82+
![Signals successfully appearing in the Segment UI](images/autoinstrumentation_signals.png "Signals successfully appearing in the Segment UI")
83+
84+
3. Click **Create Rules**.
85+
4. In the Rules Editor, add a rule that converts signal data into an event.
86+
5. Click **Preview**, then click **Save & Deploy**.
87+
88+
Segment displays `Rule updated successfully` to verify that it saved your rule.
89+
90+
## Next steps
91+
92+
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 examples rules.

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

+109
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
---
2+
title: Auto-Instrumentation Setup
3+
hidden: true
4+
---
5+
6+
This guide outlines the steps required to set up the Signals SDK in your JavaScript website.
7+
8+
You'll learn how to add Auto-Instrumentation sources, integrate dependencies, and ensure that your setup captures and processes data as intended.
9+
10+
> info "Auto-Instrumentation Pilot"
11+
> Auto-Instrumentation is currently in pilot and is governed by Segment's [First Access and Beta Preview Terms](https://www.twilio.com/en-us/legal/tos){:target="_blank"}. Segment doesn't recommend Auto-Instrumentation for use in a production environment, as Segment is actively iterating on and improving the user experience.
12+
13+
> success "Enable Auto-Instrumentation"
14+
> To enable Auto-Instrumentation in your Segment workspace, reach out to your dedicated account manager.
15+
16+
## Step 1: Add a source and get its write key
17+
18+
You'll first need to add a source and copy its write key:
19+
20+
1. In your Segment workspace, navigate to **Connections > Auto-Instrumentation** and click **Add source**.
21+
2. Select a source, give the source a name, and click **Save**.
22+
3. Return to **Connections > Sources** to view your sources.
23+
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.
25+
26+
## Step 2: Add dependencies and initialization code
27+
28+
Next, you'll need to add the Signals SDKs to your web environment.
29+
30+
Follow these steps to integrate the Signals SDK into your website:
31+
32+
1. Add the Signals SDK to your project:
33+
34+
```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
41+
```
42+
43+
2. Add the initialization code:
44+
45+
```ts
46+
// analytics.js/ts
47+
import { AnalyticsBrowser } from '@segment/analytics-next'
48+
import { SignalsPlugin } from '@segment/analytics-signals'
49+
50+
const analytics = new AnalyticsBrowser()
51+
const signalsPlugin = new SignalsPlugin()
52+
analytics.register(signalsPlugin)
53+
54+
analytics.load({
55+
writeKey: '<YOUR_WRITE_KEY>'
56+
})
57+
```
58+
59+
Verify that you replaced `<WRITE_KEY>` with the actual write key you copied in Step 1.
60+
61+
4. Build and run your app.
62+
63+
## Step 3: Verify and deploy events
64+
65+
Next, you'll need to verify signal emission and [create rules](/docs/connections/auto-instrumentation/configuration/#example-rule-implementations) to convert those signals into events:
66+
67+
1. In your Segment workspace, return to **Connections > Auto-Instrumentation** and click on the new source you created.
68+
2. Verify that signals appear as expected on the dashboard.
69+
70+
![Signals successfully appearing in the Segment UI](images/autoinstrumentation_signals.png "Signals successfully appearing in the Segment UI")
71+
72+
3. Click **Create Rules**.
73+
4. In the Rules Editor, add a rule that converts signal data into an event.
74+
5. Click **Preview**, then click **Save & Deploy**.
75+
76+
Segment displays `Rule updated successfully` to verify that it saved your rule.
77+
78+
### Debugging
79+
#### Enable debug mode
80+
Values sent to the signals API are redacted by default.
81+
This adds a local storage key. To disable redaction, add a magic query string:
82+
```
83+
https://my-website.com?segment_signals_debug=true
84+
```
85+
You can *turn off debugging* by doing:
86+
```
87+
https://my-website.com?segment_signals_debug=false
88+
```
89+
90+
### Advanced
91+
92+
#### Listening to signals
93+
```ts
94+
const signalsPlugin = new SignalsPlugin()
95+
signalsPlugin.onSignal((signal) => console.log(signal))
96+
```
97+
98+
### Emitting Signals
99+
```ts
100+
const signalsPlugin = new SignalsPlugin()
101+
signalsPlugin.addSignal({
102+
type: 'userDefined',
103+
data: { foo: 'bar' }
104+
})
105+
```
106+
107+
## Next steps
108+
109+
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 examples rules.

0 commit comments

Comments
 (0)