add signal spec

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:

src/connections/spec/signals.md

@@ -0,0 +1,309 @@
+---
+title: 'Spec: 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 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
+
+The key features of signals include:
+
+- **Comprehensive Activity Tracking**
+  - User interface interactions
+  - Network activity monitoring (inbound and 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](/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
+
+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 follows:
+
+| 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
+
+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
+
+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
+
+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
+
+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
+
+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
+}
+```
+