Skip to content

Commit 5f8957e

Browse files
wenxi-zengwenxi-zeng
committed
add signal spec
1 parent 0ddedd1 commit 5f8957e

File tree

1 file changed

+308
-0
lines changed

1 file changed

+308
-0
lines changed

‎src/connections/spec/signals.md‎

Lines changed: 308 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,308 @@
1+
---
2+
title: 'Spec: Signals'
3+
---
4+
5+
This page is a guide for developers who want to track events with Segment's Auto-Instrumentation. It explains structure and definition of Signals.
6+
7+
8+
## Overview
9+
10+
Signals provides automated user activity tracking through a sophisticated breadcrumb system. It captures crucial user interactions and allows you to transform them into meaningful analytics events using JavaScript.
11+
12+
### Key Features
13+
14+
- **Comprehensive Activity Tracking**
15+
- User interface interactions
16+
- Network activity monitoring (inbound/outbound)
17+
- Local data access patterns
18+
- Integration with existing analytics events
19+
- **Enterprise-Grade Privacy**
20+
- Built-in PII protection
21+
- Automatic data obfuscation in release builds
22+
- Configurable privacy rules
23+
- **Flexible Event Generation**
24+
- Transform breadcrumbs into Segment events using JavaScript
25+
- Create custom event generation rules
26+
- Process and filter data in real-time
27+
28+
## Signal Types
29+
30+
There are 6 different types of Signals:
31+
32+
- **Interaction Signal** - Captures user interactions with interface elements such as clicks, form submissions, and input changes
33+
- **Navigation Signal** - Tracks navigation events and screen/page transitions in web and mobile applications
34+
- **Network Signal** - Monitors HTTP requests and responses, including API calls and data fetching operations
35+
- **Local Data Signal** - Records local data storage operations like creating, reading, updating, or deleting data
36+
- **Instrumentation Signal** - Captures existing analytics events and instrumentation data from Segment Analytics
37+
- **User Defined Signal** - Allows for custom signal types with application-specific data and properties
38+
39+
### Base Signal Properties
40+
41+
All signals include these base properties:
42+
43+
| Property | Type | Description |
44+
|----------|------|-------------|
45+
| `type` | `string` | The category of signal: `'interaction'`, `'navigation'`, `'network'`, `'localData'`, `'instrumentation'`, or `'userDefined'` |
46+
| `anonymousId` | `string` | Anonymous identifier for the user |
47+
| `timestamp` | `string` | ISO timestamp when the signal was created |
48+
| `index` | `number` | Sequential index for signal ordering |
49+
| `data` | `any` | Signal-specific data. Each type has different shape of data. See specific Signal for details |
50+
| `context` | `Context` | Runtime context information |
51+
52+
**Example:**
53+
```json
54+
{
55+
"type": "interaction",
56+
"anonymousId": "user-abc123",
57+
"timestamp": "2024-01-15T14:30:00.000Z",
58+
"index": 42,
59+
"data": { "eventType": "click" },
60+
"context": { "app": { "name": "ShopApp" } }
61+
}
62+
```
63+
64+
#### Content Properties
65+
66+
The `Context` type is defined as follow:
67+
68+
| Property | Type | Description |
69+
|----------|------|-------------|
70+
| `app.name` | `string` | Application name |
71+
| `app.version` | `string` | Application version |
72+
| `app.build` | `string` | Application build identifier |
73+
| `app.namespace` | `string` | Application namespace |
74+
| `library.name` | `string` | Signals library name |
75+
| `library.version` | `string` | Signals library version |
76+
| `signalsRuntime` | `string` | Signals Runtime version identifier |
77+
78+
**Example:**
79+
```json
80+
{
81+
"app": {
82+
"name": "ShopApp",
83+
"version": "2.1.0",
84+
"build": "build-456",
85+
"namespace": "com.shop.mobile"
86+
},
87+
"library": {
88+
"name": "@segment/signals-runtime",
89+
"version": "1.0.0"
90+
},
91+
"signalsRuntime": "1.0.0"
92+
}
93+
```
94+
95+
96+
#### Web-Specific Properties
97+
98+
Web signals include additional page context:
99+
100+
| Property | Type | Description |
101+
|----------|------|-------------|
102+
| `page.url` | `string` | Full URL of the current page |
103+
| `page.path` | `string` | Path portion of the URL |
104+
| `page.search` | `string` | Query string parameters |
105+
| `page.hostname` | `string` | Hostname of the current page |
106+
| `page.hash` | `string` | Hash fragment of the URL |
107+
| `page.referrer` | `string` | Referrer URL |
108+
| `page.title` | `string` | Page title |
109+
110+
**Example:**
111+
```json
112+
{
113+
"page": {
114+
"url": "https://shop.com/products/laptop",
115+
"path": "/products/laptop",
116+
"search": "?color=silver&size=15",
117+
"hostname": "shop.com",
118+
"hash": "#reviews",
119+
"referrer": "https://google.com/search",
120+
"title": "Gaming Laptop - ShopApp"
121+
}
122+
}
123+
```
124+
125+
### Specific Signal Properties
126+
#### Interaction Signals
127+
128+
Capture user interactions with interface elements.
129+
130+
##### Web
131+
132+
| Property | Type | Description |
133+
|----------|------|-------------|
134+
| `eventType` | `'click' \| 'submit' \| 'change'` | The type of interaction event |
135+
| `target` | `TargetedHTMLElement` | The HTML element that was interacted with |
136+
| `submitter` | `TargetedHTMLElement` (optional) | For submit events, the element that triggered submission |
137+
| `listener` | `'contenteditable' \| 'onchange' \| 'mutation'` | For change events, the listener type that detected the change |
138+
| `change` | `JSONValue` | For change events, the specific change that occurred |
139+
140+
**Example:**
141+
```json
142+
{
143+
"eventType": "click",
144+
"target": {
145+
"id": "add-to-cart-btn",
146+
"attributes": {
147+
"data-product-id": "laptop-15",
148+
"class": "btn btn-primary"
149+
}
150+
}
151+
}
152+
```
153+
154+
##### Mobile
155+
156+
| Property | Type | Description |
157+
|----------|------|-------------|
158+
| `eventType` | `string` | The type of interaction event |
159+
| `target.component` | `string` | The component that was interacted with |
160+
| `target.title` | `string` | The title or label of the target component |
161+
| `target.data` | `any` | Additional data associated with the target |
162+
163+
**Example:**
164+
```json
165+
{
166+
"eventType": "tap",
167+
"target": {
168+
"component": "ProductCard",
169+
"title": "Premium Headphones",
170+
"data": {
171+
"productId": "headphones-pro",
172+
"price": 299.99
173+
}
174+
}
175+
}
176+
```
177+
178+
#### Navigation Signals
179+
180+
Track navigation and screen changes.
181+
182+
##### Web
183+
184+
| Property | Type | Description |
185+
|----------|------|-------------|
186+
| `currentUrl` | `string` | The current URL after navigation |
187+
| `previousUrl` | `string` (optional) | The previous URL before navigation |
188+
| `hash` | `string` | The hash portion of the URL |
189+
| `search` | `string` | The query string portion of the URL |
190+
| `path` | `string` | The path portion of the URL |
191+
| `changedProperties` | `('path' \| 'search' \| 'hash')[]` (optional) | Properties that changed during navigation |
192+
193+
**Example:**
194+
```json
195+
{
196+
"currentUrl": "https://shop.com/checkout",
197+
"previousUrl": "https://shop.com/cart",
198+
"path": "/checkout",
199+
"search": "",
200+
"hash": "",
201+
"changedProperties": ["path"]
202+
}
203+
```
204+
205+
##### Mobile
206+
207+
| Property | Type | Description |
208+
|----------|------|-------------|
209+
| `previousScreen` | `string` (optional) | The previous screen identifier |
210+
| `currentScreen` | `string` | The current screen identifier |
211+
212+
**Example:**
213+
```json
214+
{
215+
"previousScreen": "ProductList",
216+
"currentScreen": "ProductDetail"
217+
}
218+
```
219+
220+
#### Network Signals
221+
222+
Monitor network requests and responses.
223+
224+
| Property | Type | Description |
225+
|----------|------|-------------|
226+
| `action` | `'request' \| 'response'` | Whether this is a request or response signal |
227+
| `url` | `string` | The URL of the network request |
228+
| `body` | `object` | The request/response body |
229+
| `contentType` | `string` | The content type of the request/response |
230+
| `method` | `'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH' \| 'HEAD' \| 'OPTIONS'` | HTTP method (request only) |
231+
| `status` | `number` | HTTP status code (response only) |
232+
| `ok` | `boolean` | Whether the response was successful (response only) |
233+
| `requestId` | `string` | Unique identifier linking requests and responses |
234+
235+
**Example:**
236+
```json
237+
{
238+
"action": "request",
239+
"url": "https://api.shop.com/products",
240+
"method": "GET",
241+
"body": {},
242+
"contentType": "application/json",
243+
"requestId": "req-abc123"
244+
}
245+
```
246+
247+
#### Local Data Signals
248+
249+
Track local data storage operations.
250+
251+
| Property | Type | Description |
252+
|----------|------|-------------|
253+
| `action` | `'created' \| 'read' \| 'updated' \| 'deleted' \| 'undefined'` | The type of data operation performed |
254+
| `identifier` | `string` | Unique identifier for the data being operated on |
255+
| `data` | `string` | The data content or reference |
256+
257+
**Example:**
258+
```json
259+
{
260+
"action": "created",
261+
"identifier": "cart-item-laptop-001",
262+
"data": "{\"productId\":\"laptop-001\",\"quantity\":1,\"price\":1299.99}"
263+
}
264+
```
265+
266+
#### Instrumentation Signals
267+
268+
Capture analytics events and instrumentation data.
269+
270+
| Property | Type | Description |
271+
|----------|------|-------------|
272+
| `type` | `'track' \| 'page' \| 'screen' \| 'identify' \| 'group' \| 'alias'` | The type of analytics event |
273+
| `rawEvent` | `RawEvent` | The raw event data from Segment Analytics |
274+
275+
**Example:**
276+
```json
277+
{
278+
"type": "track",
279+
"rawEvent": {
280+
"event": "Product Viewed",
281+
"properties": {
282+
"productId": "laptop-001",
283+
"category": "Electronics",
284+
"price": 1299.99,
285+
"brand": "TechCorp"
286+
}
287+
}
288+
}
289+
```
290+
291+
#### User Defined Signals
292+
293+
Allow for custom signal types with arbitrary data.
294+
295+
| Property | Type | Description |
296+
|----------|------|-------------|
297+
| `[key: string]` | `any` | Custom properties defined by the application |
298+
299+
**Example:**
300+
```json
301+
{
302+
"customEventType": "product_recommendation",
303+
"recommendationEngine": "ml-v2",
304+
"products": ["laptop-001", "mouse-pro", "keyboard-mech"],
305+
"userId": "user-12345",
306+
"confidence": 0.85
307+
}
308+
```

0 commit comments

Comments
 (0)