From 5f8957ef182a90763e12757ed984293780f1b749 Mon Sep 17 00:00:00 2001 From: Wenxi Zeng Date: Tue, 12 Aug 2025 17:08:26 -0500 Subject: [PATCH 1/5] add signal spec --- src/connections/spec/signals.md | 308 ++++++++++++++++++++++++++++++++ 1 file changed, 308 insertions(+) create mode 100644 src/connections/spec/signals.md diff --git a/src/connections/spec/signals.md b/src/connections/spec/signals.md new file mode 100644 index 0000000000..2798840891 --- /dev/null +++ b/src/connections/spec/signals.md @@ -0,0 +1,308 @@ +--- +title: 'Spec: Signals' +--- + +This page is a guide for developers who want to track events with Segment's Auto-Instrumentation. It explains structure and definition of Signals. + + +## Overview + +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. + +### Key Features + +- **Comprehensive Activity Tracking** + - User interface interactions + - Network activity monitoring (inbound/outbound) + - Local data access patterns + - Integration with existing analytics events +- **Enterprise-Grade Privacy** + - Built-in PII protection + - Automatic data obfuscation in release builds + - Configurable privacy rules +- **Flexible Event Generation** + - Transform breadcrumbs into Segment events using JavaScript + - Create custom event generation rules + - Process and filter data in real-time + +## Signal Types + +There are 6 different types of Signals: + +- **Interaction Signal** - Captures user interactions with interface elements such as clicks, form submissions, and input changes +- **Navigation Signal** - Tracks navigation events and screen/page transitions in web and mobile applications +- **Network Signal** - Monitors HTTP requests and responses, including API calls and data fetching operations +- **Local Data Signal** - Records local data storage operations like creating, reading, updating, or deleting data +- **Instrumentation Signal** - Captures existing analytics events and instrumentation data from Segment Analytics +- **User Defined Signal** - Allows for custom signal types with application-specific data and properties + +### Base Signal Properties + +All signals include these base properties: + +| Property | Type | Description | +|----------|------|-------------| +| `type` | `string` | The category of signal: `'interaction'`, `'navigation'`, `'network'`, `'localData'`, `'instrumentation'`, or `'userDefined'` | +| `anonymousId` | `string` | Anonymous identifier for the user | +| `timestamp` | `string` | ISO timestamp when the signal was created | +| `index` | `number` | Sequential index for signal ordering | +| `data` | `any` | Signal-specific data. Each type has different shape of data. See specific Signal for details | +| `context` | `Context` | Runtime context information | + +**Example:** +```json +{ + "type": "interaction", + "anonymousId": "user-abc123", + "timestamp": "2024-01-15T14:30:00.000Z", + "index": 42, + "data": { "eventType": "click" }, + "context": { "app": { "name": "ShopApp" } } +} +``` + +#### Content Properties + +The `Context` type is defined as follow: + +| Property | Type | Description | +|----------|------|-------------| +| `app.name` | `string` | Application name | +| `app.version` | `string` | Application version | +| `app.build` | `string` | Application build identifier | +| `app.namespace` | `string` | Application namespace | +| `library.name` | `string` | Signals library name | +| `library.version` | `string` | Signals library version | +| `signalsRuntime` | `string` | Signals Runtime version identifier | + +**Example:** +```json +{ + "app": { + "name": "ShopApp", + "version": "2.1.0", + "build": "build-456", + "namespace": "com.shop.mobile" + }, + "library": { + "name": "@segment/signals-runtime", + "version": "1.0.0" + }, + "signalsRuntime": "1.0.0" +} +``` + + +#### Web-Specific Properties + +Web signals include additional page context: + +| Property | Type | Description | +|----------|------|-------------| +| `page.url` | `string` | Full URL of the current page | +| `page.path` | `string` | Path portion of the URL | +| `page.search` | `string` | Query string parameters | +| `page.hostname` | `string` | Hostname of the current page | +| `page.hash` | `string` | Hash fragment of the URL | +| `page.referrer` | `string` | Referrer URL | +| `page.title` | `string` | Page title | + +**Example:** +```json +{ + "page": { + "url": "https://shop.com/products/laptop", + "path": "/products/laptop", + "search": "?color=silver&size=15", + "hostname": "shop.com", + "hash": "#reviews", + "referrer": "https://google.com/search", + "title": "Gaming Laptop - ShopApp" + } +} +``` + +### Specific Signal Properties +#### Interaction Signals + +Capture user interactions with interface elements. + +##### Web + +| Property | Type | Description | +|----------|------|-------------| +| `eventType` | `'click' \| 'submit' \| 'change'` | The type of interaction event | +| `target` | `TargetedHTMLElement` | The HTML element that was interacted with | +| `submitter` | `TargetedHTMLElement` (optional) | For submit events, the element that triggered submission | +| `listener` | `'contenteditable' \| 'onchange' \| 'mutation'` | For change events, the listener type that detected the change | +| `change` | `JSONValue` | For change events, the specific change that occurred | + +**Example:** +```json +{ + "eventType": "click", + "target": { + "id": "add-to-cart-btn", + "attributes": { + "data-product-id": "laptop-15", + "class": "btn btn-primary" + } + } +} +``` + +##### Mobile + +| Property | Type | Description | +|----------|------|-------------| +| `eventType` | `string` | The type of interaction event | +| `target.component` | `string` | The component that was interacted with | +| `target.title` | `string` | The title or label of the target component | +| `target.data` | `any` | Additional data associated with the target | + +**Example:** +```json +{ + "eventType": "tap", + "target": { + "component": "ProductCard", + "title": "Premium Headphones", + "data": { + "productId": "headphones-pro", + "price": 299.99 + } + } +} +``` + +#### Navigation Signals + +Track navigation and screen changes. + +##### Web + +| Property | Type | Description | +|----------|------|-------------| +| `currentUrl` | `string` | The current URL after navigation | +| `previousUrl` | `string` (optional) | The previous URL before navigation | +| `hash` | `string` | The hash portion of the URL | +| `search` | `string` | The query string portion of the URL | +| `path` | `string` | The path portion of the URL | +| `changedProperties` | `('path' \| 'search' \| 'hash')[]` (optional) | Properties that changed during navigation | + +**Example:** +```json +{ + "currentUrl": "https://shop.com/checkout", + "previousUrl": "https://shop.com/cart", + "path": "/checkout", + "search": "", + "hash": "", + "changedProperties": ["path"] +} +``` + +##### Mobile + +| Property | Type | Description | +|----------|------|-------------| +| `previousScreen` | `string` (optional) | The previous screen identifier | +| `currentScreen` | `string` | The current screen identifier | + +**Example:** +```json +{ + "previousScreen": "ProductList", + "currentScreen": "ProductDetail" +} +``` + +#### Network Signals + +Monitor network requests and responses. + +| Property | Type | Description | +|----------|------|-------------| +| `action` | `'request' \| 'response'` | Whether this is a request or response signal | +| `url` | `string` | The URL of the network request | +| `body` | `object` | The request/response body | +| `contentType` | `string` | The content type of the request/response | +| `method` | `'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH' \| 'HEAD' \| 'OPTIONS'` | HTTP method (request only) | +| `status` | `number` | HTTP status code (response only) | +| `ok` | `boolean` | Whether the response was successful (response only) | +| `requestId` | `string` | Unique identifier linking requests and responses | + +**Example:** +```json +{ + "action": "request", + "url": "https://api.shop.com/products", + "method": "GET", + "body": {}, + "contentType": "application/json", + "requestId": "req-abc123" +} +``` + +#### Local Data Signals + +Track local data storage operations. + +| Property | Type | Description | +|----------|------|-------------| +| `action` | `'created' \| 'read' \| 'updated' \| 'deleted' \| 'undefined'` | The type of data operation performed | +| `identifier` | `string` | Unique identifier for the data being operated on | +| `data` | `string` | The data content or reference | + +**Example:** +```json +{ + "action": "created", + "identifier": "cart-item-laptop-001", + "data": "{\"productId\":\"laptop-001\",\"quantity\":1,\"price\":1299.99}" +} +``` + +#### Instrumentation Signals + +Capture analytics events and instrumentation data. + +| Property | Type | Description | +|----------|------|-------------| +| `type` | `'track' \| 'page' \| 'screen' \| 'identify' \| 'group' \| 'alias'` | The type of analytics event | +| `rawEvent` | `RawEvent` | The raw event data from Segment Analytics | + +**Example:** +```json +{ + "type": "track", + "rawEvent": { + "event": "Product Viewed", + "properties": { + "productId": "laptop-001", + "category": "Electronics", + "price": 1299.99, + "brand": "TechCorp" + } + } +} +``` + +#### User Defined Signals + +Allow for custom signal types with arbitrary data. + +| Property | Type | Description | +|----------|------|-------------| +| `[key: string]` | `any` | Custom properties defined by the application | + +**Example:** +```json +{ + "customEventType": "product_recommendation", + "recommendationEngine": "ml-v2", + "products": ["laptop-001", "mouse-pro", "keyboard-mech"], + "userId": "user-12345", + "confidence": 0.85 +} +``` \ No newline at end of file From 81729f4aa0a08a9028f8ee6eb636a47cca8fe201 Mon Sep 17 00:00:00 2001 From: Wenxi Zeng Date: Wed, 13 Aug 2025 12:14:05 -0500 Subject: [PATCH 2/5] update versions in kotlin instruction --- .../auto-instrumentation/kotlin-setup.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/src/connections/auto-instrumentation/kotlin-setup.md b/src/connections/auto-instrumentation/kotlin-setup.md index 4ab6b7b8bc..7ad19dc8d4 100644 --- a/src/connections/auto-instrumentation/kotlin-setup.md +++ b/src/connections/auto-instrumentation/kotlin-setup.md @@ -33,25 +33,25 @@ To install Signals, add the following dependencies to your app-level Gradle buil ```groovy dependencies { // Core Analytics Kotlin library - implementation("com.segment.analytics.kotlin:android:1.19.1") + implementation("com.segment.analytics.kotlin:android:1.21.0") // Live plugin for real-time analytics - implementation("com.segment.analytics.kotlin:analytics-kotlin-live:1.1.0") + implementation("com.segment.analytics.kotlin:analytics-kotlin-live:1.3.0") // Signals core library - implementation("com.segment.analytics.kotlin.signals:core:0.5.0") + implementation("com.segment.analytics.kotlin.signals:core:0.9.0") // Optional: Jetpack Compose UI tracking - implementation("com.segment.analytics.kotlin.signals:compose:0.5.0") + implementation("com.segment.analytics.kotlin.signals:compose:0.9.0") // Optional: OkHttp3 network request tracking - implementation("com.segment.analytics.kotlin.signals:okhttp3:0.5.0") + implementation("com.segment.analytics.kotlin.signals:okhttp3:0.9.0") // Optional: Screen and route tracking for Navigation components - implementation("com.segment.analytics.kotlin.signals:navigation:0.5.0") + implementation("com.segment.analytics.kotlin.signals:navigation:0.9.0") // Optional: HttpURLConnection tracking - implementation("com.segment.analytics.kotlin.signals:java-net:0.5.0") + implementation("com.segment.analytics.kotlin.signals:java-net:0.9.0") } ``` @@ -115,7 +115,7 @@ Add the relevant plugin based on your network stack. 1. Add the dependency to your Gradle file: ```groovy - implementation("com.segment.analytics.kotlin.signals:okhttp3:0.5.0") + implementation("com.segment.analytics.kotlin.signals:okhttp3:0.9.0") ``` 2. Add the tracking plugin to your `OkHttpClient`: @@ -133,7 +133,7 @@ Retrofit is built on top of OkHttp, so the setup is similar. 1. Add the same OkHttp3 plugin shown in the previous sectiion: ```groovy - implementation("com.segment.analytics.kotlin.signals:okhttp3:0.5.0") + implementation("com.segment.analytics.kotlin.signals:okhttp3:0.9.0") ``` 2. Attach the plugin through your Retrofit client configuration: @@ -154,7 +154,7 @@ Retrofit is built on top of OkHttp, so the setup is similar. 1. Add the JavaNet plugin dependency: ```groovy - implementation("com.segment.analytics.kotlin.signals:java-net:0.5.0") + implementation("com.segment.analytics.kotlin.signals:java-net:0.9.0") ``` 2. Install the plugin at runtime: From 892480b26b776f175a0b97068898e11be866fd5f Mon Sep 17 00:00:00 2001 From: Sharon Adewusi Date: Thu, 14 Aug 2025 14:23:35 +0100 Subject: [PATCH 3/5] tidying wording + casing --- src/connections/spec/signals.md | 58 ++++++++++++++++----------------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/src/connections/spec/signals.md b/src/connections/spec/signals.md index 2798840891..a5f2ece43a 100644 --- a/src/connections/spec/signals.md +++ b/src/connections/spec/signals.md @@ -2,18 +2,19 @@ title: 'Spec: Signals' --- -This page is a guide for developers who want to track events with Segment's Auto-Instrumentation. It explains structure and definition of Signals. - +This is a guide for developers who want to track events with Segment's Auto-Instrumentation. It explains the structure and definitions of Signals. ## Overview -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. +Signals provide automated user activity tracking through a sophisticated breadcrumb system. They capture crucial user interactions and allows you to transform them into meaningful analytics events using JavaScript. + +### Key features -### Key Features +The key features of signals include: - **Comprehensive Activity Tracking** - User interface interactions - - Network activity monitoring (inbound/outbound) + - Network activity monitoring (inbound and outbound) - Local data access patterns - Integration with existing analytics events - **Enterprise-Grade Privacy** @@ -25,18 +26,18 @@ Signals provides automated user activity tracking through a sophisticated breadc - Create custom event generation rules - Process and filter data in real-time -## Signal Types +## Signal types There are 6 different types of Signals: -- **Interaction Signal** - Captures user interactions with interface elements such as clicks, form submissions, and input changes -- **Navigation Signal** - Tracks navigation events and screen/page transitions in web and mobile applications -- **Network Signal** - Monitors HTTP requests and responses, including API calls and data fetching operations -- **Local Data Signal** - Records local data storage operations like creating, reading, updating, or deleting data -- **Instrumentation Signal** - Captures existing analytics events and instrumentation data from Segment Analytics -- **User Defined Signal** - Allows for custom signal types with application-specific data and properties +- **Interaction Signal** - Captures user interactions with interface elements such as clicks, form submissions, and input changes. +- **Navigation Signal** - Tracks navigation events and [Screen](/docs/connections/spec/screen) or [Page](/docs/connections/spec/page) transitions in web and mobile applications. +- **Network Signal** - Monitors HTTP requests and responses, including API calls and data fetching operations. +- **Local Data Signal** - Records local data storage operations like creating, reading, updating, or deleting data. +- **Instrumentation Signal** - Captures existing analytics events and instrumentation data from Segment Analytics. +- **User-defined Signal** - Allows for custom signal types with application-specific data and properties. -### Base Signal Properties +### Base signal properties All signals include these base properties: @@ -61,9 +62,9 @@ All signals include these base properties: } ``` -#### Content Properties +#### Content properties -The `Context` type is defined as follow: +The `Context` type is defined as follows: | Property | Type | Description | |----------|------|-------------| @@ -92,7 +93,6 @@ The `Context` type is defined as follow: } ``` - #### Web-Specific Properties Web signals include additional page context: @@ -122,10 +122,10 @@ Web signals include additional page context: } ``` -### Specific Signal Properties -#### Interaction Signals +### Specific signal properties +#### Interaction signals -Capture user interactions with interface elements. +Interaction signals capture user interactions with interface elements. ##### Web @@ -175,9 +175,9 @@ Capture user interactions with interface elements. } ``` -#### Navigation Signals +#### Navigation signals -Track navigation and screen changes. +Navigation signals track navigation and screen changes. ##### Web @@ -217,9 +217,9 @@ Track navigation and screen changes. } ``` -#### Network Signals +#### Network signals -Monitor network requests and responses. +Network signals monitor network requests and responses. | Property | Type | Description | |----------|------|-------------| @@ -244,7 +244,7 @@ Monitor network requests and responses. } ``` -#### Local Data Signals +#### Local data signals Track local data storage operations. @@ -263,9 +263,9 @@ Track local data storage operations. } ``` -#### Instrumentation Signals +#### Instrumentation signals -Capture analytics events and instrumentation data. +Instrumentation signals capture analytics events and instrumentation data. | Property | Type | Description | |----------|------|-------------| @@ -288,9 +288,9 @@ Capture analytics events and instrumentation data. } ``` -#### User Defined Signals +#### User-defined signals -Allow for custom signal types with arbitrary data. +User-defined signals allow for custom signal types with arbitrary data. | Property | Type | Description | |----------|------|-------------| @@ -305,4 +305,4 @@ Allow for custom signal types with arbitrary data. "userId": "user-12345", "confidence": 0.85 } -``` \ No newline at end of file +``` From ce251ccc8d45ce5fdb3079ec1abc4f8c77bc299a Mon Sep 17 00:00:00 2001 From: Sharon Adewusi Date: Thu, 14 Aug 2025 14:24:00 +0100 Subject: [PATCH 4/5] [netlify-build] --- src/connections/spec/signals.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/connections/spec/signals.md b/src/connections/spec/signals.md index a5f2ece43a..352a6c81fa 100644 --- a/src/connections/spec/signals.md +++ b/src/connections/spec/signals.md @@ -306,3 +306,4 @@ User-defined signals allow for custom signal types with arbitrary data. "confidence": 0.85 } ``` + From 8ba829f90f9ce1b31781ed3b21baa34c265d806a Mon Sep 17 00:00:00 2001 From: Sharon Adewusi Date: Thu, 14 Aug 2025 14:35:37 +0100 Subject: [PATCH 5/5] casing --- src/connections/spec/signals.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/connections/spec/signals.md b/src/connections/spec/signals.md index 352a6c81fa..7b43d66366 100644 --- a/src/connections/spec/signals.md +++ b/src/connections/spec/signals.md @@ -93,7 +93,7 @@ The `Context` type is defined as follows: } ``` -#### Web-Specific Properties +#### Web-specific properties Web signals include additional page context: