Skip to content

Commit 65a4f20

Browse files
pwsegpwseg
authored
Merge pull request #6594 from segmentio/auto-instrumentation-pilot
Auto-Instrumentation Pilot [DOC-915]
2 parents bf3c27c + e30c503 commit 65a4f20

File tree

4 files changed

+490
-0
lines changed

4 files changed

+490
-0
lines changed

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

Lines changed: 313 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,313 @@
1+
---
2+
title: Signals Implementation Guide
3+
hidden: true
4+
---
5+
6+
This guide is a reference to configuring and using signals in the Signals SDK with Auto-Instrumentation. On this page, you'll find details on:
7+
8+
- Setting up and managing signal types in the Signals SDK
9+
- Creating custom rules to capture and translate signals into actionable analytics events
10+
- Example rules that you can use as a basis for further customization
11+
12+
This guide assumes that you've already added the Signals SDK to your application. If you haven't yet, see the [Auto-Instrumentation Setup](/docs/connections/auto-instrumentation/setup/) guide for initial setup.
13+
14+
> info "Auto-Instrumentation Pilot"
15+
> 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.
16+
17+
> success "Enable Auto-Instrumentation"
18+
> To enable Auto-Instrumentation in your Segment workspace, reach out to your dedicated account manager.
19+
20+
## Signals configuration
21+
22+
Using the Signals Configuration object, you can control the destination, frequency, and types of signals that Segment automatically tracks within your application. The following tables detail the configuration options for both Signals-Swift and Signals-Kotlin.
23+
24+
### Signals-Swift
25+
26+
| `Option` | Required | Value | Description |
27+
| ---------------------- | -------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
28+
| `writeKey` | Yes | String | Source write key |
29+
| `maximumBufferSize` | No | Integer | The number of signals to be kept for JavaScript inspection. This buffer is first-in, first-out. Default is `1000`. |
30+
| `relayCount` | No | Integer | Relays signals to Segment every Xth event. Default is `20`. |
31+
| `relayInterval` | No | TimeInterval | Relays signals to segment every X seconds. Default is `60`. |
32+
| `broadcasters` | No | `SignalBroadcaster` | An array of broadcasters. These objects forward signal data to their destinations, like `WebhookBroadcaster` or `DebugBroadcaster` writing to the developer console. Default is `SegmentBroadcaster`. |
33+
| `useUIKitAutoSignal` | No | Bool | Tracks UIKit component interactions automatically. Default is `false`. |
34+
| `useSwiftUIAutoSignal` | No | Bool | Tracks SwiftUI component interactions automatically. Default is `false`. |
35+
| `useNetworkAutoSignal` | No | Bool | Tracks network events automatically. Default is `false`. |
36+
| `allowedNetworkHosts` | No | Array | An array of allowed network hosts. |
37+
| `blockedNetworkHosts` | No | Array | An array of blocked network hosts. |
38+
39+
40+
### Signals-Kotlin
41+
42+
| `Option` | Required | Value | Description |
43+
| ------------------- | -------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
44+
| `writeKey` | Yes | String | Source write key |
45+
| `maximumBufferSize` | No | Integer | The number of signals to be kept for JavaScript inspection. This buffer is first-in, first-out. Default is `1000`. |
46+
| `broadcastInterval` | No | Integer | Broadcasts signals to Segment every X event. Default is `60`. |
47+
| `broadcasters` | No | `List<SignalBroadcaster>` | An array of broadcasters. These objects forward signal data to their destinations, like `WebhookBroadcaster` or `DebugBroadcaster` writing to the developer console. Default is `SegmentBroadcaster`. |
48+
49+
50+
## Converting signals to events
51+
52+
After you set up the Signals SDK to capture the signals you want to target, you can create rules in your Segment workspace to translate the captured signals into traditional Segment analytics events. These rules are deployed in your application the next time a user launches your app.
53+
54+
### Getting started with rule creation
55+
56+
1. In your Segment workspace, go to to **Connections > Auto-Instrumentation** and click on a source.
57+
2. Click **Create Rules**.
58+
59+
### Using the Rules Editor
60+
61+
The Rules Editor is where you define rules that transform raw signal data into analytics events. In the editor, you write functions that convert signals into events and then call them in the `processSignal()` function.
62+
63+
The Rules Editor also lets you test your rules with recent signals to verify that they produce the data you need before you deploy.
64+
65+
The following example tracks all Screen events:
66+
67+
```javascript
68+
function screenCall(currentSignal) {
69+
if (currentSignal.type == SignalType.Navigation && currentSignal.data.action == NavigationAction.Entering) {
70+
analytics.screen(currentSignal.data.screen, null, null)
71+
}
72+
}
73+
74+
function processSignal(signal) {
75+
screenCall(signal)
76+
}
77+
```
78+
79+
## Signal definitions
80+
81+
Signals come in various types, each associated with specific data that you can use to create analytics events. This section contains code samples that detail each signal type. Because Segment has standardized these definitions across both the Signals-Swift and Signals-Kotlin libraries, they're useful when you create rules in your Segment workspace.
82+
83+
### Base signal
84+
85+
The Base Signal serves as the foundation for all other signal types. It's defined by the `RawSignal<T>` interface, where `T` represents the data type associated with the signal.
86+
87+
This interface ensures that every signal inherits essential properties:
88+
89+
```java
90+
interface RawSignal<T> {
91+
var anonymousId: String //
92+
var type: SignalType // Specifies the signal category.
93+
var timestamp: String // The exact time when the signal was generated.
94+
var index: Int // An integer representing the signal's position.
95+
var data: T // The specific data of type `T` associated with the signal.
96+
}
97+
```
98+
99+
### Signal Types
100+
101+
The Signal Type enum defines the different types of signals the SDK can collect:
102+
103+
```java
104+
enum SignalType {
105+
Interaction, // User interactions like clicks or touches.
106+
Navigation, // Navigation events.
107+
Network, // Network requests and responses.
108+
LocalData, // Data loaded from local or other external sources.
109+
Instrumentation, // Events generated from Segment Track/Screen/... events.
110+
UserDefined // Custom events defined by the user.
111+
}
112+
```
113+
114+
### Interaction signals
115+
116+
The SDK collects Interaction signals when you enable one of the `UIAutoSignal` options, like `useSwiftUIAutoSignal: true`. These signals primarily track user interactions with UI components:
117+
118+
```java
119+
class InteractionData {
120+
var component: String // The type of UI component interacted with, like "Button" or "Image".
121+
var title: String? // Optional title of the component, if applicable.
122+
var data: Object? // Additional data related to the interaction, if any.
123+
}
124+
125+
class InteractionSignal extends RawSignal<InteractionData> {
126+
type = SignalType.UIInteraction // Sets the signal type to UI Interaction.
127+
}
128+
```
129+
130+
### Navigation signals
131+
132+
The SDK collects Navigation signals when you enable one of the `UIAutoSignal` options, like `useSwiftUIAutoSignal: true`. These signals are generated when a user interacts with navigation components in your application's UI, giving you insight into how users move through and interact with your application:
133+
134+
```java
135+
enum NavigationAction {
136+
Forward, // Navigation to the next item or page
137+
Backward, // Navigation to the previous item or page
138+
Modal, // Opening a modal window
139+
Entering, // Entering a new screen
140+
Leaving, // Leaving a screen
141+
Page, // Navigation involving a full page
142+
Popup // Interaction with a popup
143+
}
144+
145+
class NavigationData {
146+
var action: NavigationAction // The type of navigation action performed.
147+
var screen: String // The screen or component name involved in the navigation.
148+
}
149+
150+
class NavigationSignal extends RawSignal<NavigationData> {
151+
type = SignalType.Navigation // Sets the signal type to Navigation.
152+
}
153+
```
154+
155+
### Network signals
156+
157+
The SDK collects Network signals when you enable the `useNetworkAutoSignal` option in your Signals Configuration, like `useNetworkAutoSignal: true`. These signals are generated when your application makes network requests:
158+
159+
```java
160+
enum NetworkAction {
161+
Request, // A network request is made.
162+
Response // A response is received.
163+
}
164+
165+
class NetworkData {
166+
var action: NetworkAction // The type of network action, either Request or Response.
167+
var url: String // The URL involved in the network action.
168+
var statusCode: Int? // The HTTP status code of the response, if applicable.
169+
var data: Object? // Additional data associated with the network action.
170+
}
171+
172+
class NetworkSignal extends RawSignal<NetworkData> {
173+
type = SignalType.Network // Sets the signal type to Network.
174+
}
175+
```
176+
177+
### Local Data signals
178+
179+
The SDK collects Local Data Signals when data gets loaded from local soures, like SQLite databases or local caches. These signals help track how your application manages local data:
180+
181+
```java
182+
enum LocalDataAction {
183+
Loaded, // Data was loaded from a local source.
184+
Updated, // Existing data was updated.
185+
Saved, // New data was saved locally.
186+
Deleted, // Data was deleted from a local source.
187+
Undefined // Any other unspecified local data action.
188+
}
189+
190+
class LocalData {
191+
var action: LocalDataAction // The type of action performed on the local data.
192+
var identifier: String // A unique identifier for the data, like "Loaded User Info".
193+
var data: Object? // Additional details or data associated with the action.
194+
}
195+
196+
class LocalDataSignal extends RawSignal<LocalData> {
197+
type = SignalType.LocalData // Sets the signal type to LocalData.
198+
}
199+
```
200+
201+
### Instrumentation signals
202+
203+
The SDK collects Instrumentation Signals when [traditional Segment analytics events](/docs/connections/spec/) are invoked:
204+
205+
```java
206+
enum EventType {
207+
Track, //
208+
Screen, //
209+
Identify, //
210+
Group, //
211+
Alias, //
212+
Unknown // Any other unspecified event type.
213+
}
214+
215+
class InstrumentationData {
216+
type: EventType // The type of Segment event.
217+
rawEvent: Object? // Additional details of the event.
218+
}
219+
220+
class InstrumentationSignal extends RawSignal<InstrumentationData> {
221+
type = SignalType.Instrumentation // Sets the signal type to Instrumentation.
222+
}
223+
```
224+
225+
### User-defined signals
226+
227+
You can also define your own signals. Use the following example as an implementation guideline:
228+
229+
```java
230+
interface MyCustomData {
231+
var event: String // A custom event description or identifier.
232+
}
233+
234+
class MyCustomSignal extends RawSignal<MyCustomData> {
235+
type = SignalType.UserDefined // Sets the signal type to User Defined.
236+
}
237+
```
238+
239+
## Example rule implementations
240+
241+
You can use the Signals data definitions on this page to create tracking rules.
242+
243+
### Example: Identify users
244+
245+
Building off of the screen tracking example, you could create a rule that identifies users:
246+
247+
```javascript
248+
function detectIdentify(currentSignal) {
249+
var loginType;
250+
251+
// Check if the signal is related to network activity on a login URL
252+
if (currentSignal.type == SignalType.Network && currentSignal.data.url.includes("login")) {
253+
loginType = "login";
254+
}
255+
256+
// If a login type was detected, identify the user
257+
if (loginType) {
258+
var traits = new Object();
259+
traits.loggedIn = true; // Set user status to logged in
260+
let loginData = currentSignal.data.data.content; // Extract login data from the signal
261+
traits.userName = loginData.userName; // Capture the user's name
262+
263+
if (loginType === "login") {
264+
var userId = loginData.userId; // Get userID from login data
265+
analytics.identify(userId, traits); // Identify the user with the Identify call
266+
}
267+
}
268+
}
269+
270+
//...other functions
271+
272+
function processSignal(signal) {
273+
//...other functions
274+
detectIdentify(signal); // Process the Identify call based on incoming signals
275+
}
276+
```
277+
278+
279+
### Example: Track `Add to Cart` events
280+
281+
This rule shows how you could implement the core ordering events from [the e-commerce Spec](/docs/connections/spec/ecommerce/v2/#core-ordering-overview):
282+
283+
```javascript
284+
function trackAddToCart(currentSignal) {
285+
// Check if the signal is an interaction with the "Add To Cart" button
286+
if (currentSignal.type == SignalType.Interaction && currentSignal.data.title == "Add To Cart") {
287+
var properties = new Object(); // Initialize an object to store event properties
288+
289+
// Find the network response signal for additional data
290+
let network = signals.find(currentSignal, SignalType.Network, (signal) => {
291+
return signal.data.action === NetworkAction.Response;
292+
});
293+
294+
if (network) {
295+
// Extract and assign product details from the network response
296+
properties.price = network.data.data.content.price; // Product price
297+
properties.currency = network.data.data.content.currency ?? "USD"; // Currency, defaulting to USD if undefined
298+
properties.productId = network.data.data.content.id; // Product ID
299+
properties.productName = network.data.data.content.title; // Product name
300+
}
301+
302+
// Track the "Add To Cart" event with the defined properties
303+
analytics.track(currentSignal.data.title, properties);
304+
}
305+
}
306+
307+
//...other functions
308+
309+
function ProcessSignals(signal) {
310+
//...other functions
311+
trackAddToCart(signal); // Process the "Add To Cart" tracking based on incoming signals
312+
}
313+
```

‎src/connections/auto-instrumentation/images/autoinstrumentation_signals.png

99.3 KB
Loading

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

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
title: Auto-Instrumentation
3+
hidden: true
4+
---
5+
6+
Auto-Instrumentation simplifies tracking in your websites and apps by eliminating the need for a traditional Segment instrumentation.
7+
8+
> info "Auto-Instrumentation Pilot"
9+
> 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.
10+
11+
> success "Enable Auto-Instrumentation in your workspace"
12+
> To enable Auto-Instrumentation in your Segment workspace, reach out to your dedicated account manager.
13+
14+
## Background
15+
16+
Gathering actionable and timely data is crucial to the success of your business. However, collecting this data in real time has historically proven to be challenging.
17+
18+
As your business needs change, keeping instrumentation up-to-date across all of your digital properties can be time-consuming, often taking weeks or months. This delay can lead to lost insights, frustration for your marketers and developers, and open-ended support of your Segment instrumentation.
19+
20+
## Auto-Instrumentation as a solution
21+
22+
With just a few lines of code, Auto-Instrumentation handles device tracking for you, helping you focus on collecting the data that's essential to your business and letting your marketers and data analysts gather and update data without relying on engineering teams.
23+
24+
Some Auto-Instrumentation advantages include:
25+
26+
- **JavaScript-based instrumentation logic**: Configure and refine your instrumentation logic entirely within JavaScript, simplifying the development process and reducing dependencies on other environments.
27+
- **Rapid iteration**: Update your instrumentation logic without the need to constantly release new versions of your mobile app, enabling faster iterations and improvements.
28+
- **Bypass update delays**: Avoid the typical delays associated with app update cycles and app store approvals. Auto-Instrumentation lets you update your tracking setups or fix errors immediately, ensuring your data collection remains accurate and timely.
29+
30+
## How it works
31+
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.
33+
34+
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.
35+
36+
## Privacy
37+
38+
Auto-Instrumentation removes personally identifiable information (PII) from breadcrumbs before they get sent to Segment. No user data is visible to Segment.

0 commit comments

Comments
 (0)