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: diff --git a/src/connections/spec/signals.md b/src/connections/spec/signals.md new file mode 100644 index 0000000000..7b43d66366 --- /dev/null +++ b/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 +} +``` +