From feb4c313add84b5fea1a110c112a04e9899a9bec Mon Sep 17 00:00:00 2001
From: Wenxi Zeng <wzeng@twilio.com>
Date: Thu, 6 Nov 2025 15:09:07 -0600
Subject: [PATCH 01/15] update kotlin setup guide

---
 .../auto-instrumentation/kotlin-setup.md      | 264 ++++++++++--------
 1 file changed, 142 insertions(+), 122 deletions(-)

diff --git a/src/connections/auto-instrumentation/kotlin-setup.md b/src/connections/auto-instrumentation/kotlin-setup.md
index b7fa63241a..90e0fb81c7 100644
--- a/src/connections/auto-instrumentation/kotlin-setup.md
+++ b/src/connections/auto-instrumentation/kotlin-setup.md
@@ -25,159 +25,173 @@ Signals supports [Jetpack Compose](https://developer.android.com/compose){:targe
 
 Segment recommends testing in a development environment before deploying Signals in production. For more information, see [Debug mode](#step-4-enable-debug-mode).
 
-## Step 1: Install dependencies
+## Prerequisites
 
-To install Signals, add the following dependencies to your app-level Gradle build file.
+Auto-Instrumentation (aka Signals) works on top of Analytics and Live Plugins. Make sure to add the following dependencies to your module's Gradle file if you don't have them already.
 
 ```groovy
-dependencies {
-  // Core Analytics Kotlin library
-  implementation("com.segment.analytics.kotlin:android:1.19.1")
-
-  // Live plugin for real-time analytics
-  implementation("com.segment.analytics.kotlin:analytics-kotlin-live:1.1.0")
-
-  // Signals core library
-  implementation("com.segment.analytics.kotlin.signals:core:0.5.0")
-
-  // Optional: Jetpack Compose UI tracking
-  implementation("com.segment.analytics.kotlin.signals:compose:0.5.0")
-
-  // Optional: OkHttp3 network request tracking
-  implementation("com.segment.analytics.kotlin.signals:okhttp3:0.5.0")
-
-  // Optional: Screen and route tracking for Navigation components
-  implementation("com.segment.analytics.kotlin.signals:navigation:0.5.0")
-
-  // Optional: HttpURLConnection tracking
-  implementation("com.segment.analytics.kotlin.signals:java-net:0.5.0")
-}
+// analytics kotlin 
+implementation ("com.segment.analytics.kotlin:android:1.22.0")
+// live plugin 
+implementation("com.segment.analytics.kotlin:analytics-kotlin-live:1.3.0")
 ```
 
-The core libraries are required to enable Signals and real-time analytics. Use the following optional plugins to track additional activity based on your app's architecture:
-
-- **Compose**: Tracks user interface events in Jetpack Compose.
-- **OkHttp3**: Captures requests sent through OkHttp3 or Retrofit.
-- **Navigation**: Tracks route changes when using Jetpack Navigation.
-- **JavaNet**: Tracks network activity sent through `HttpURLConnection`.
-
-Only add the plugins you plan to use. You can add or remove them later without reinitializing your source.
-
-## Step 2: Initialize the SDK
-
-After you add dependencies, you need to initialize the Analytics client and configure the Signals plugin. 
-
-Start by creating the `Analytics` instance using your source's write key. Then add the Signals plugin and configure its settings separately.
-
-```kotlin
-// Create the Analytics instance with your configuration
-val analytics = Analytics(Configuration(writeKey = "<WRITE_KEY>"))
-
-// Add the live plugin for real-time event handling
-analytics.add(LivePlugins())
+## Step 1: Getting started
 
-// Add the Signals plugin
-analytics.add(Signals)
-
-// Configure Signals settings
-Signals.configuration = Configuration(
-  maximumBufferSize = 1000, // Number of signals to keep in memory
-  broadcastInterval = 60, // Send signals every 60 seconds
-  broadcasters = listOf(WebhookBroadcaster("YOUR_WEBHOOK")), // Optional
-  debugMode = true // For development use only
-)
-
-// Optional: Add the Compose plugin to track UI events and interactions
-analytics.add(SignalsComposeTrackingPlugin())
+Instrumentation becomes as simple as adding dependencies to your module's Gradle file:
+1. Add Signals Core
+    ```groovy
+    // signal core   
+    implementation ("com.segment.analytics.kotlin.signals:core:1.0.0")
+    ```
+2. Initialize Signals
+    ```kotlin
+    //... <analytics config>....
+    analytics.add(LivePlugins()) // Make sure LivePlugins is added
+    analytics.add(Signals)  // Add the signals plugin
+  
+    Signals.configuration = Configuration(
+      // sendDebugSignalsToSegment will relay events to Segment server. Should only be true for development purposes.
+      sendDebugSignalsToSegment = true
+      // obfuscateDebugSignals will obfuscate sensitive data
+      obfuscateDebugSignals = true
+      // .. other options
+    )
+    ```
+3. Add proper dependency and plugin as needed to: 
+     * [Capture Interactions](#capture-interactions)
+     * [Capture Navigation](#capture-navigation)
+     * [Capture Network](#capture-network)
 
-// Optional: Track screen transitions using Navigation
-analytics.add(SignalsActivityTrackingPlugin())
-navController.turnOnScreenTracking()
-```
+## Step 2: Additional setup
 
-When you run this code, keep the following in mind:
+### Capture Interactions
 
-- You need to replace `<WRITE_KEY>` with the key from your Android Source in Segment.
-- `debugMode` sends signals to Segment for use in the Event Builder. Only enable it in development environments.
-- If your app doesn't use Jetpack Compose or Navigation, you can skip those plugin lines.
+#### Kotlin Compose
 
-For more options, see [Configuration options reference](#configuration-options).
+1. Add the dependency to your module’s Gradle build file.
+    ```groovy
+    implementation ("com.segment.analytics.kotlin.signals:compose:1.0.0")
+    ```
 
-## Step 3: Track network requests
+2. Add `SignalsComposeTrackingPlugin` to analytics
+    ```kotlin
+    analytics.add(SignalsComposeTrackingPlugin())
+    ```
 
-Signals supports automatic tracking of network activity for apps that use OkHttp3, Retrofit, or `HttpURLConnection`.
+#### Legacy XML UI
 
-Add the relevant plugin based on your network stack.
+1. Add uitoolkit Gradle Plugin dependency to project level `build.gradle`
+    ```groovy
+    buildscript {
+        dependencies {
+            classpath 'com.segment.analytics.kotlin.signals:uitoolkit-gradle-plugin:1.0.0'
+        }
+    }
+    ```
+2. Apply the plugin in your app level `build.gradle` and add the dependency
+    ```groovy
+    plugins {
+        // ...other plugins
+        id 'com.segment.analytics.kotlin.signals.uitoolkit-tracking'
+    }
+    
+    dependencies {
+      // ..other dependencies
+      implementation ("com.segment.analytics.kotlin.signals:uitoolkit:1.0.0")
+    }
+    ```
 
-### OkHttp3
 
-1. Add the dependency to your Gradle file:
+### Capture Navigation
 
+1. Add navigation Gradle Plugin dependency to project level `build.gradle`
     ```groovy
-    implementation("com.segment.analytics.kotlin.signals:okhttp3:0.5.0")
+    buildscript {
+        dependencies {
+            classpath 'com.segment.analytics.kotlin.signals:navigation-gradle-plugin:1.0.0'
+        }
+    }
     ```
-
-2. Add the tracking plugin to your `OkHttpClient`:
-
+2. Apply the plugin in your app level `build.gradle` and add the dependency
+    ```groovy
+    plugins {
+        // ...other plugins
+        id 'com.segment.analytics.kotlin.signals.navigation-tracking'
+    }
+    
+    dependencies {
+      // ..other dependencies
+      implementation ("com.segment.analytics.kotlin.signals:navigation:1.0.0")
+    }
+    ```
+3. (Optional) Add `SignalsActivityTrackingPlugin` to analytics to track Activity/Fragment navigation. **Not required for Compose Navigation**  
     ```kotlin
-    val okHttpClient = OkHttpClient.Builder()
-        .addInterceptor(SignalsOkHttp3TrackingPlugin())
-        .build()
+    analytics.add(SignalsActivityTrackingPlugin())
     ```
 
-### Retrofit
-
-Retrofit is built on top of OkHttp, so the setup is similar.
-
-1. Add the same OkHttp3 plugin shown in the previous sectiion:
+### Capture Network
 
+#### OkHttp
+  
+1. add dependency:
     ```groovy
-    implementation("com.segment.analytics.kotlin.signals:okhttp3:0.5.0")
+    implementation ("com.segment.analytics.kotlin.signals:okhttp3:1.0.0")
     ```
 
-2. Attach the plugin through your Retrofit client configuration:
-
+2. add `SignalsOkHttp3TrackingPlugin` as an interceptor to your OkHttpClient:
     ```kotlin
-    val okHttpClient = OkHttpClient.Builder()
-        .addInterceptor(SignalsOkHttp3TrackingPlugin())
-        .build()
-
-    val retrofit = Retrofit.Builder()
-        .client(okHttpClient)
-        .baseUrl("https://your.api.endpoint")
-        .build()
+       private val okHttpClient = OkHttpClient.Builder()
+           .addInterceptor(SignalsOkHttp3TrackingPlugin())
+           .build()
     ```
 
-### HttpURLConnection
-
-1. Add the JavaNet plugin dependency:
+#### Retrofit
 
+1. add dependency:
     ```groovy
-    implementation("com.segment.analytics.kotlin.signals:java-net:0.5.0")
+    implementation ("com.segment.analytics.kotlin.signals:okhttp3:1.0.0")
     ```
 
-2. Install the plugin at runtime:
-
+2. add `SignalsOkHttp3TrackingPlugin` as an interceptor to your Retrofit client:
     ```kotlin
-    JavaNetTrackingPlugin.install()
+       private val okHttpClient = OkHttpClient.Builder()
+           .addInterceptor(SignalsOkHttp3TrackingPlugin())
+           .build()
+       
+       val retrofit = Retrofit.Builder()
+           .client(okHttpClient)
+           .build()
     ```
 
-Depending on your app’s network stack, you may only need one plugin. If your app uses multiple clients, you can install more than one plugin.
+#### java.net.HttpURLConnection
+ 1. add dependency:
+     ```groovy
+     implementation ("com.segment.analytics.kotlin.signals:java-net:1.0.0")
+     ```
+ 
+ 2. install the `JavaNetTrackingPlugin` on where you initialize analytics:
+     ```kotlin
+         JavaNetTrackingPlugin.install()
+     ```
 
-## Step 4: Enable debug mode
+
+## Step 3: Enable debug mode
 
 By default, Signals stores captured data on the device and doesn't forward it to Segment. This process prevents unnecessary bandwidth use and helps support privacy compliance requirements.
 
-To view captured signals in the Event Builder and create event generation rules, you need to enable `debugMode`. This setting temporarily lets the SDK send signal data to Segment while you're testing.
+To view captured signals in the Event Builder and create event generation rules, you need to enable `sendDebugSignalsToSegment`. This setting temporarily lets the SDK send signal data to Segment while you're testing.
+
+In addition, the SDK obfuscates signals sent to Segment by default. To view the completed data, you need to turn off `obfuscateDebugSignals`.
 
 > warning ""
-> Only enable `debugMode` in development environments. Avoid using `debugMode` in production apps.
+> Only enable `sendDebugSignalsToSegment` in development environments. Avoid using `sendDebugSignalsToSegment` in production apps.
 
-You can enable `debugMode` in one of two ways.
+You can enable `sendDebugSignalsToSegment` and turn off `obfuscateDebugSignals` in one of two ways.
 
 ### Option 1: Use build flavors
 
-Configure `debugMode` at build time using [Android product flavors](https://developer.android.com/build/build-variants#product-flavors){:target="_blank"}.
+Configure `sendDebugSignalsToSegment` and `obfuscateDebugSignals` at build time using [Android product flavors](https://developer.android.com/build/build-variants#product-flavors){:target="_blank"}.
 
 1. In your `build.gradle` file, define two flavors:
 
@@ -186,10 +200,12 @@ Configure `debugMode` at build time using [Android product flavors](https://deve
       ...
       productFlavors {
         prod {
-          buildConfigField "boolean", "DEBUG_MODE", "false"
+          buildConfigField "boolean", "SEND_DEBUG_SIGNALS_TO_SEGMENT", "false"
+          buildConfigField "boolean", "OBFUSCATE_DEBUG_SIGNALS", "true"
         }
         dev {
-          buildConfigField "boolean", "DEBUG_MODE", "true"
+          buildConfigField "boolean", "SEND_DEBUG_SIGNALS_TO_SEGMENT", "true"
+          buildConfigField "boolean", "OBFUSCATE_DEBUG_SIGNALS", "false"
         }
       }
     }
@@ -199,19 +215,21 @@ Configure `debugMode` at build time using [Android product flavors](https://deve
 
     ```kotlin
     Signals.configuration = Configuration(
-      ...
-      debugMode = BuildConfig.DEBUG_MODE
+      // ... other config options
+      sendDebugSignalsToSegment = BuildConfig.SEND_DEBUG_SIGNALS_TO_SEGMENT
+      obfuscateDebugSignals = BuildConfig.OBFUSCATE_DEBUG_SIGNALS
     )
     ```
 
 ### Option 2: Use a feature flag
 
-If your app uses [Firebase Remote Config](https://firebase.google.com/docs/remote-config){:target="_blank"} or a similar system, you can control `debugMode` remotely.
+If your app uses [Firebase Remote Config](https://firebase.google.com/docs/remote-config){:target="_blank"} or a similar system, you can control `sendDebugSignalsToSegment` and `obfuscateDebugSignals` remotely.
 
 ```kotlin
 Signals.configuration = Configuration(
   ...
-  debugMode = remoteConfig.getBoolean("debug_mode")
+  sendDebugSignalsToSegment = remoteConfig.getBoolean("sendDebugSignalsToSegment")
+  obfuscateDebugSignals = remoteConfig.getBoolean("obfuscateDebugSignals")
 )
 ```
 
@@ -226,13 +244,13 @@ After you build and run your app, use the [Event Builder](/docs/connections/auto
    - Tap buttons and UI elements.
    - Trigger network requests.
 
-If `debugMode` is enabled, Signals appear in real time as you interact with the app.
+If `sendDebugSignalsToSegment` is enabled, Signals appear in real time as you interact with the app.
 
 4. In the Event Builder, select a signal and click **Configure event** to define a new event.
 5. After you add any event mappings, click **Publish event rules** to save them.
 
 > info "What if I don't see the Event Builder tab?"
-> If you don't see the Event Builder tab, confirm that the SDK is installed correctly and make sure `debugMode` is enabled. Verify that Auto-Instrumentation is enabled in **Settings > Advanced**. If you still don't see it, reach out to your CSM.
+> If you don't see the Event Builder tab, confirm that the SDK is installed correctly and make sure `sendDebugSignalsToSegment` is enabled. Verify that Auto-Instrumentation is enabled in **Settings > Advanced**. If you still don't see it, reach out to your CSM.
 
 ## Configuration options
 
@@ -240,12 +258,14 @@ Use the `Signals.configuration` object to control how captured signals are store
 
 The following table lists the available options:
 
-| Option              | Required | Type                      | Default | Description                                                                                                                                                                                         |
-| ------------------- | -------- | ------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `maximumBufferSize` | No       | `Int`                     | `1000`  | The number of captured signals to keep in memory before relaying them. Signals get stored in a first-in, first-out buffer.                                                                          |
-| `broadcastInterval` | No       | `Int` (seconds)           | `60`    | The interval, in seconds, at which buffered signals are sent to broadcasters.                                                                                                                       |
-| `broadcasters`      | No       | `List<SignalBroadcaster>` | N/A     | A list of broadcasters that forward signal data to external destinations. `SegmentBroadcaster` is included by default, and you can add others like `WebhookBroadcaster` or a custom implementation. |
-| `debugMode`         | No       | `Boolean`                 | `false` | When `true`, relays signals to Segment so they appear in the Event Builder. Only enable this in development environments.                                                                           |
+| OPTION            | REQUIRED | VALUE                     | DESCRIPTION |
+|------------------|----------|---------------------------|-------------|
+| **maximumBufferSize** | No  | Integer                   | The number of signals to be kept for JavaScript inspection. This buffer is first-in, first-out. Default is **1000**. |
+| **relayCount** | No  | Integer                   | Relays every X signals to Segment. Default is **20**. |
+| **relayInterval** | No  | Integer                   | Relays signals to Segment every X seconds. Default is **60**. |
+| **broadcasters**  | No      | List<SignalBroadcaster>    | An array of broadcasters. These objects forward signal data to their destinations, like **WebhookBroadcaster**, or you could write your own **DebugBroadcaster** that writes logs to the developer console. **SegmentBroadcaster** is always added by the SDK. |
+| **sendDebugSignalsToSegment**      | No      | Boolean                    | Turns on debug mode and allows the SDK to relay Signals to Segment server. Default is **false**. It should only be set to true for development purposes. |
+| **obfuscateDebugSignals**      | No      | Boolean                    | Obfuscates signals being relayed to Segment. Default is **true**. |
 
 ## Next steps
 

From 252f27b008dbaec8fad50dd9296828365a51930c Mon Sep 17 00:00:00 2001
From: Wenxi Zeng <wzeng@twilio.com>
Date: Thu, 6 Nov 2025 15:28:45 -0600
Subject: [PATCH 02/15] update swift setup guide

---
 .../auto-instrumentation/swift-setup.md       | 307 +++++++++++++++---
 1 file changed, 258 insertions(+), 49 deletions(-)

diff --git a/src/connections/auto-instrumentation/swift-setup.md b/src/connections/auto-instrumentation/swift-setup.md
index 7133f052d8..cbc4691e8f 100644
--- a/src/connections/auto-instrumentation/swift-setup.md
+++ b/src/connections/auto-instrumentation/swift-setup.md
@@ -12,7 +12,7 @@ Learn how to connect an existing source, integrate dependencies, turn on Auto-In
 > info "Regional availability"
 > Auto-Instrumentation isn't supported in EU workspaces.
 
-## Step 1: Get your source write key
+## Before you start
 
 You need the `writeKey` from an existing Segment source. To find it:
 
@@ -21,60 +21,265 @@ You need the `writeKey` from an existing Segment source. To find it:
 3. From the source's overview tab, go to **Settings > API Keys**.
 4. Copy the `writeKey` shown in the code block.
 
-## Step 2: Add dependencies and initialization code
 
-Next, add the Signals SDKs to your Swift applicatiion.
+## Prerequisites
 
-1. Use Swift Package Manager to add the Signals SDK from the following repository:
+Auto-Instrumentation (aka Signals) works on top of Analytics. Make sure to add the following dependency to your project if you don't have analytics-swift already.
 
-    ```zsh
-    https://github.com/segment-integrations/analytics-swift-live.git
-    ```
+```swift
+dependencies: [
+    .package(url: "https://github.com/segmentio/analytics-swift.git", from: "1.9.1")
+]
+```
 
-2. Add the initialization code and configuration options:
+## Step 1: Getting started
+
+1. Add AnalyticsLive to your Swift Package dependencies:
+    ```swift
+    dependencies: [
+        .package(url: "https://github.com/segmentio/analytics-live-swift.git", from: "3.2.1")
+    ]
+    ```
 
+2. Import and initialize with your Analytics instance:
+   
 > success ""
 > See [configuration options](#configuration-options) for a complete list.
+> 
+    ```swift
+    import Segment
+    import AnalyticsLive
+    
+    let analytics = Analytics(configuration: Configuration(writeKey: "YOUR_WRITE_KEY"))
+    
+    // Add LivePlugins first
+    analytics.add(plugin: LivePlugins())
+    
+    // Add Signals
+    analytics.add(plugin: Signals.shared)
+    
+    // Configure Signals
+    Signals.shared.useConfiguration(SignalsConfiguration(
+        writeKey: "YOUR_WRITE_KEY", // Same writeKey as Analytics
+        useUIKitAutoSignal: true,
+        useSwiftUIAutoSignal: true,
+        useNetworkAutoSignal: true,
+        #if DEBUG
+        // NOTE: See section below on using these flags appropriately.
+        sendDebugSignalsToSegment: true, // Only true for development
+        obfuscateDebugSignals: false // Only false for development
+        #endif
+        // ... other options
+    ))
+    ```
+
+3. Set up capture for the UI framework(s) you're using:
+     * [Capture SwiftUI Interactions](#swiftui)
+     * [Capture UIKit Interactions](#uikit)
+     * [Capture Network Activity](#capture-network)
 
+
+## Step 2: Additional setup
+
+### Capture Interactions
+
+#### SwiftUI
+
+SwiftUI automatic signal capture requires adding typealiases to your code. This is necessary because SwiftUI doesn't provide hooks for automatic instrumentation.
+
+1. Enable SwiftUI auto-signals in your configuration:
     ```swift
-    // Configure Analytics with your settings
-    {... <analytics config>....} 
+    Signals.shared.useConfiguration(SignalsConfiguration(
+        writeKey: "YOUR_WRITE_KEY",
+        useSwiftUIAutoSignal: true
+        // ... other options
+    ))
+    ```
 
-    // Set up the Signals SDK configuration
-    let config = Signals.Configuration(
-        writeKey: "<WRITE_KEY>",          // Replace <WRITE_KEY> with the write key you previously copied
-        maximumBufferSize: 100,
-        useSwiftUIAutoSignal: true,
-        useNetworkAutoSignal: true
-    )
+2. Add the following typealiases to your SwiftUI views or in a shared file:
+    ```swift
+    import SwiftUI
+    import AnalyticsLive
+    
+    // Navigation
+    typealias NavigationLink = SignalNavigationLink
+    typealias NavigationStack = SignalNavigationStack // iOS 16+
+    
+    // Selection & Input Controls
+    typealias Button = SignalButton
+    typealias TextField = SignalTextField
+    typealias SecureField = SignalSecureField
+    typealias Picker = SignalPicker
+    typealias Toggle = SignalToggle
+    typealias Slider = SignalSlider // Not available on tvOS
+    typealias Stepper = SignalStepper // Not available on tvOS
+    
+    // List & Collection Views
+    typealias List = SignalList
+    ```
 
-    // Locate and set the fallback JavaScript file for edge functions
-    let fallbackURL = Bundle.main.url(forResource: "MyEdgeFunctions", withExtension: "js")
+3. Use the controls normally in your SwiftUI code:
+    ```swift
+    struct ContentView: View {
+        var body: some View {
+            NavigationStack {
+                VStack {
+                    Button("Click Me") {
+                        // Button tap will automatically generate a signal
+                    }
+                    
+                    TextField("Enter text", text: $text)
+                    // Text changes will automatically generate signals
+                }
+            }
+        }
+    }
+    ```
+
+> **Note:** The typealiases replace SwiftUI's native controls with signal-generating versions. Your code remains unchanged, but interactions are now automatically captured.
+
+#### UIKit
+
+UIKit automatic signal capture uses method swizzling and requires no code changes.
 
-    // Apply the configuration and add the Signals plugin
-    Signals.shared.useConfiguration(config)
-    Analytics.main.add(plugin: LivePlugins(fallbackFileURL: fallbackURL))
-    Analytics.main.add(plugin: Signals.shared)
+1. Enable UIKit auto-signals in your configuration:
+    ```swift
+    Signals.shared.useConfiguration(SignalsConfiguration(
+        writeKey: "YOUR_WRITE_KEY",
+        useUIKitAutoSignal: true
+        // ... other options
+    ))
     ```
 
-Verify that you replaced `<WRITE_KEY>` with the actual write key you copied in [Step 1](#step-1-get-your-source-write-key).
+2. That's it! The following UIKit interactions and navigation events are automatically captured via method swizzling:
+
+    **Interactions:**
+    - `UIButton` taps
+    - `UISlider` value changes
+    - `UIStepper` value changes
+    - `UISwitch` toggle events
+    - `UITextField` text changes
+    - `UITableViewCell` selections
+    
+    **Navigation:**
+    - `UINavigationController` push/pop operations
+    - `UIViewController` modal presentations and dismissals
+    - `UITabBarController` tab switches
+
+### Capture Navigation
+
+Navigation capture is handled automatically when you enable SwiftUI or UIKit auto-signals:
+
+- **SwiftUI**: Captured through `SignalNavigationLink` and `SignalNavigationStack` when you add the typealiases
+- **UIKit**: Captured automatically via `UINavigationController`, `UIViewController`, and `UITabBarController` swizzling
 
-#### SwiftUI projects
+No additional setup required beyond enabling the appropriate auto-signal flags.
 
-If your app is written in SwiftUI, you need to add a `TypeAlias.swift` file to your project that captures interaction and navigation Signals, like in this example:
+### Capture Network
+
+Network capture automatically tracks URLSession requests and responses.
+
+1. Enable network auto-signals in your configuration:
+    ```swift
+    Signals.shared.useConfiguration(SignalsConfiguration(
+        writeKey: "YOUR_WRITE_KEY",
+        useNetworkAutoSignal: true,
+        allowedNetworkHosts: ["*"], // Allow all hosts (default)
+        blockedNetworkHosts: [] // Block specific hosts (optional)
+        // ... other options
+    ))
+    ```
+
+2. Network requests made via URLSession are automatically captured, including:
+   - Request URL, method, headers, and body
+   - Response status, headers, and body
+   - Request/response correlation via request ID
+
+> **Note:** Third-party networking libraries that use URLSession underneath (like Alamofire) should work automatically. Segment API endpoints are automatically blocked to prevent recursive tracking.
+
+#### Configuring Network Hosts
+
+You can control which network requests are tracked:
 
 ```swift
-import Foundation
-import Signals
-
-typealias Button = SignalButton
-typealias NavigationStack = SignalNavigationStack
-typealias NavigationLink = SignalNavigationLink
-typealias TextField = SignalTextField
-typealias SecureField = SignalSecureField
+SignalsConfiguration(
+    writeKey: "YOUR_WRITE_KEY",
+    useNetworkAutoSignal: true,
+    allowedNetworkHosts: ["api.myapp.com", "*.example.com"], // Only track these hosts
+    blockedNetworkHosts: ["analytics.google.com"] // Exclude these hosts
+)
 ```
 
-## Step 3: Turn on Auto-Instrumentation in your source
+- `allowedNetworkHosts`: Array of host patterns to track. Use `"*"` to allow all hosts (default).
+- `blockedNetworkHosts`: Array of host patterns to exclude from tracking.
+
+The following hosts are automatically blocked to prevent recursive tracking:
+- `api.segment.com`
+- `cdn-settings.segment.com`
+- `signals.segment.com`
+- `api.segment.build`
+- `cdn.segment.build`
+- `signals.segment.build`
+
+## Step 3: Enable debug mode
+
+By default, Signals stores captured data on the device and doesn't forward it to Segment. This process prevents unnecessary bandwidth use and helps support privacy compliance requirements.
+
+To view captured signals in the Event Builder and create event generation rules, you need to enable `sendDebugSignalsToSegment`. This setting temporarily lets the SDK send signal data to Segment while you're testing.
+
+In addition, the SDK obfuscates signals sent to Segment by default. To view the completed data, you need to turn off `obfuscateDebugSignals`.
+
+> warning ""
+> Only enable `sendDebugSignalsToSegment` in development environments. Avoid using `sendDebugSignalsToSegment` in production apps.
+
+You can enable `sendDebugSignalsToSegment` and turn off `obfuscateDebugSignals` in one of three ways.
+
+### Option 1: Use Build Configurations to Toggle Debug Mode
+  
+  1. Define different configurations in your project settings (Debug, Release, etc.)
+  
+  2. Use compiler flags to control the setting:
+      ```swift
+      Signals.shared.useConfiguration(SignalsConfiguration(
+          writeKey: "YOUR_WRITE_KEY",
+          // ... other config options
+          #if DEBUG
+          sendDebugSignalsToSegment: true,
+          obfuscateDebugSignals: false
+          #else
+          sendDebugSignalsToSegment: false,
+          obfuscateDebugSignals: true
+          #endif
+      ))
+      ```
+
+### Option 2: Use a Feature Flag System
+ If you're using Firebase Remote Config or a similar feature flag system, you can dynamically control `sendDebugSignalsToSegment` and `obfuscateDebugSignals` without requiring a new app build:
+  ```swift
+  let remoteConfig = RemoteConfig.remoteConfig()
+  
+  Signals.shared.useConfiguration(SignalsConfiguration(
+      writeKey: "YOUR_WRITE_KEY",
+      // ... other config options
+      sendDebugSignalsToSegment: remoteConfig["sendDebugSignalsToSegment"].boolValue,
+      obfuscateDebugSignals: remoteConfig["obfuscateDebugSignals"].boolValue
+  ))
+  ```
+
+### Option 3: Use Environment Variables (for debugging/testing)
+ You can check for environment variables or launch arguments during development:
+  ```swift
+  let isDebugEnabled = ProcessInfo.processInfo.environment["SIGNALS_DEBUG"] != nil
+  
+  Signals.shared.useConfiguration(SignalsConfiguration(
+      writeKey: "YOUR_WRITE_KEY",
+      // ... other config options
+      sendDebugSignalsToSegment: isDebugEnabled,
+      obfuscateDebugSignals: !isDebugEnabled
+  ))
+  ```
+
+## Step 4: Turn on Auto-Instrumentation in your source
 
 Next, return to the source settings to turn on Auto-Instrumentation:
 
@@ -83,7 +288,7 @@ Next, return to the source settings to turn on Auto-Instrumentation:
 3. From the source's overview tab, go to **Settings > Advanced**.
 4. Toggle Auto-Instrumention on.
 
-## Step 4: Verify and deploy events
+## Step 5: Verify and deploy events
 
 After integrating the SDK and running your app, verify that Segment is collecting signals:
 
@@ -91,7 +296,7 @@ After integrating the SDK and running your app, verify that Segment is collectin
 2. In the source overview, look for the **Event Builder** tab. If the tab doesn’t appear:
   - Make sure you've installed the SDK correctly.
   - Reach out to your Segment CSM to confirm that your workspace has the necessary feature flags enabled.
-3. Launch your app [in debug mode](https://github.com/segmentio/analytics-next/tree/master/packages/signals/signals#sending-and-viewing-signals-on-segmentcom-debug-mode){:target="_blank"}. This enables signal collection so you can see activity in the Event Builder.
+3. If `sendDebugSignalsToSegment` is enabled, Signals appear in real time in the Event Builder as you interact with the app.
 4. Use the app as a user would: navigate between screens, tap buttons, trigger network requests. Signals appear in real time as you interact with the app.
 5. In the Event Builder, find a signal and click **Configure event** to define a new event. After configuring the event, click **Publish event rules**.
 
@@ -99,18 +304,22 @@ After integrating the SDK and running your app, verify that Segment is collectin
 
 Using the Signals Configuration object, you can control the destination, frequency, and types of signals that Segment automatically tracks within your application. The following table details the configuration options for Signals-Swift.
 
-| `Option`               | Required | Value                      | Description                                                                                                                                                                                            |
-| ---------------------- | -------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `writeKey`             | Yes      | String                     | Source write key                                                                                                                                                                                       |
-| `maximumBufferSize`    | No       | Integer                    | The number of signals to be kept for JavaScript inspection. This buffer is first-in, first-out. Default is `1000`.                                                                                     |
-| `relayCount`           | No       | Integer                    | Relays signals to Segment every Xth event. Default is `20`.                                                                                                                                            |
-| `relayInterval`        | No       | TimeInterval  | Relays signals to segment every X seconds. Default is `60`.                                                                                                                                            |
-| `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`. |
-| `useUIKitAutoSignal`   | No       | Bool                       | Tracks UIKit component interactions automatically. Default is `false`.                                                                                                                                 |
-| `useSwiftUIAutoSignal` | No       | Bool                       | Tracks SwiftUI component interactions automatically. Default is `false`.                                                                                                                               |
-| `useNetworkAutoSignal` | No       | Bool                       | Tracks network events automatically. Default is `false`.                                                                                                                                               |
-| `allowedNetworkHosts`  | No       | Array                      | An array of allowed network hosts.                                                                                                                                                                     |
-| `blockedNetworkHosts`  | No       | Array                      | An array of blocked network hosts.                                                                                                                                                
+
+| OPTION            | REQUIRED | VALUE                     | DESCRIPTION |
+|------------------|----------|---------------------------|-------------|
+| **writeKey** | Yes | String | Your Segment write key. Should match your Analytics instance writeKey. |
+| **maximumBufferSize** | No  | Int                   | The number of signals to be kept for JavaScript inspection. This buffer is first-in, first-out. Default is **1000**. |
+| **relayCount** | No  | Int                   | Relays every X signals to Segment. Default is **20**. |
+| **relayInterval** | No  | TimeInterval                   | Relays signals to Segment every X seconds. Default is **60**. |
+| **broadcasters**  | No      | [SignalBroadcaster]    | An array of broadcasters. These objects forward signal data to their destinations, like **WebhookBroadcaster**, or you could write your own **DebugBroadcaster** that writes logs to the developer console. **SegmentBroadcaster** is always added by the SDK when `sendDebugSignalsToSegment` is true. |
+| **sendDebugSignalsToSegment**      | No      | Bool                    | Turns on debug mode and allows the SDK to relay Signals to Segment server. Default is **false**. It should only be set to true for development purposes. |
+| **obfuscateDebugSignals**      | No      | Bool                    | Obfuscates signals being relayed to Segment. Default is **true**. |
+| **apiHost** | No | String | API host for signal relay. Default is **"signals.segment.io/v1"**. |
+| **useUIKitAutoSignal** | No | Bool | Enables automatic UIKit signal capture via method swizzling. Default is **false**. |
+| **useSwiftUIAutoSignal** | No | Bool | Enables automatic SwiftUI signal capture (requires typealiases). Default is **false**. |
+| **useNetworkAutoSignal** | No | Bool | Enables automatic network signal capture for URLSession. Default is **false**. |
+| **allowedNetworkHosts** | No | [String] | Array of host patterns to track. Use `["*"]` for all hosts. Default is **["*"]**. |
+| **blockedNetworkHosts** | No | [String] | Array of host patterns to exclude from tracking. Default is **[]**. |
 
 ## Next steps
 

From 1f3da0ed9cd117ad886680500491567c1ddfc4c0 Mon Sep 17 00:00:00 2001
From: Wenxi Zeng <wzeng@twilio.com>
Date: Thu, 6 Nov 2025 15:28:58 -0600
Subject: [PATCH 03/15] minor fix

---
 .../auto-instrumentation/kotlin-setup.md            | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/src/connections/auto-instrumentation/kotlin-setup.md b/src/connections/auto-instrumentation/kotlin-setup.md
index 90e0fb81c7..baff94dca4 100644
--- a/src/connections/auto-instrumentation/kotlin-setup.md
+++ b/src/connections/auto-instrumentation/kotlin-setup.md
@@ -45,6 +45,10 @@ Instrumentation becomes as simple as adding dependencies to your module's Gradle
     implementation ("com.segment.analytics.kotlin.signals:core:1.0.0")
     ```
 2. Initialize Signals
+ 
+> success ""
+> See [configuration options](#configuration-options) for a complete list.
+> 
     ```kotlin
     //... <analytics config>....
     analytics.add(LivePlugins()) // Make sure LivePlugins is added
@@ -233,6 +237,15 @@ Signals.configuration = Configuration(
 )
 ```
 
+## Step 4: Turn on Auto-Instrumentation in your source
+
+Next, return to the source settings to turn on Auto-Instrumentation:
+
+1. Go to **Connections > Sources**.
+2. Select the source you used in Step 1.
+3. From the source's overview tab, go to **Settings > Advanced**.
+4. Toggle Auto-Instrumention on.
+
 ## Step 5: Verify event collection
 
 After you build and run your app, use the [Event Builder](/docs/connections/auto-instrumentation/event-builder/) to confirm that Signals are being collected correctly.

From 5108f0c7edcd1b35b5c6bc5c741c0bff856f8f79 Mon Sep 17 00:00:00 2001
From: Wenxi Zeng <wzeng@twilio.com>
Date: Thu, 6 Nov 2025 16:06:55 -0600
Subject: [PATCH 04/15] link fix

---
 src/connections/auto-instrumentation/kotlin-setup.md | 3 +--
 src/connections/auto-instrumentation/swift-setup.md  | 1 +
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/connections/auto-instrumentation/kotlin-setup.md b/src/connections/auto-instrumentation/kotlin-setup.md
index baff94dca4..95025d4cd1 100644
--- a/src/connections/auto-instrumentation/kotlin-setup.md
+++ b/src/connections/auto-instrumentation/kotlin-setup.md
@@ -17,13 +17,12 @@ This guide shows how to install and configure the library, as well as how to ena
 To use Signals with Android, you need:
 
 - An active Segment workspace with Auto-Instrumentation enabled.
-- A Kotlin-based Android project.
 - Android Gradle Plugin version 7.0 or later.
 - A minimum compile SDK version of 21.
 
 Signals supports [Jetpack Compose](https://developer.android.com/compose){:target="_blank"} and traditional Android UI frameworks. It also includes optional plugins for network tracking using [OkHttp3](https://square.github.io/okhttp/){:target="_blank"}, [Retrofit](https://square.github.io/retrofit/){:target="_blank"}, or [HttpURLConnection](https://developer.android.com/reference/java/net/HttpURLConnection){:target="_blank"}.
 
-Segment recommends testing in a development environment before deploying Signals in production. For more information, see [Debug mode](#step-4-enable-debug-mode).
+Segment recommends testing in a development environment before deploying Signals in production. For more information, see [Debug mode](#step-3-enable-debug-mode).
 
 ## Prerequisites
 
diff --git a/src/connections/auto-instrumentation/swift-setup.md b/src/connections/auto-instrumentation/swift-setup.md
index cbc4691e8f..785e002a06 100644
--- a/src/connections/auto-instrumentation/swift-setup.md
+++ b/src/connections/auto-instrumentation/swift-setup.md
@@ -21,6 +21,7 @@ You need the `writeKey` from an existing Segment source. To find it:
 3. From the source's overview tab, go to **Settings > API Keys**.
 4. Copy the `writeKey` shown in the code block.
 
+Segment recommends testing in a development environment before deploying Signals in production. For more information, see [Debug mode](#step-3-enable-debug-mode).
 
 ## Prerequisites
 

From 43d6e37fed7966bcea771a9039b64147b2b76732 Mon Sep 17 00:00:00 2001
From: Sharon Adewusi <sadewusi@twilio.com>
Date: Fri, 7 Nov 2025 11:48:45 +0000
Subject: [PATCH 05/15] edits [netlify-build]

---
 .../auto-instrumentation/kotlin-setup.md      | 54 +++++++++----------
 1 file changed, 26 insertions(+), 28 deletions(-)

diff --git a/src/connections/auto-instrumentation/kotlin-setup.md b/src/connections/auto-instrumentation/kotlin-setup.md
index 95025d4cd1..ad8672c1ba 100644
--- a/src/connections/auto-instrumentation/kotlin-setup.md
+++ b/src/connections/auto-instrumentation/kotlin-setup.md
@@ -26,7 +26,7 @@ Segment recommends testing in a development environment before deploying Signals
 
 ## Prerequisites
 
-Auto-Instrumentation (aka Signals) works on top of Analytics and Live Plugins. Make sure to add the following dependencies to your module's Gradle file if you don't have them already.
+Auto-Instrumentation (also known as Signals) works on top of Analytics and Live Plugins. Make sure to add the following dependencies to your module's Gradle file if you don't have them already.
 
 ```groovy
 // analytics kotlin 
@@ -37,7 +37,7 @@ implementation("com.segment.analytics.kotlin:analytics-kotlin-live:1.3.0")
 
 ## Step 1: Getting started
 
-Instrumentation becomes as simple as adding dependencies to your module's Gradle file:
+To get started:
 1. Add Signals Core
     ```groovy
     // signal core   
@@ -62,13 +62,13 @@ Instrumentation becomes as simple as adding dependencies to your module's Gradle
     )
     ```
 3. Add proper dependency and plugin as needed to: 
-     * [Capture Interactions](#capture-interactions)
-     * [Capture Navigation](#capture-navigation)
-     * [Capture Network](#capture-network)
+     * [Capture interactions](#capture-interactions).
+     * [Capture navigation](#capture-navigation).
+     * [Capture network](#capture-network).
 
 ## Step 2: Additional setup
 
-### Capture Interactions
+### Capture interactions
 
 #### Kotlin Compose
 
@@ -84,7 +84,7 @@ Instrumentation becomes as simple as adding dependencies to your module's Gradle
 
 #### Legacy XML UI
 
-1. Add uitoolkit Gradle Plugin dependency to project level `build.gradle`
+1. Add the uitoolkit Gradle Plugin dependency to project-level `build.gradle`:
     ```groovy
     buildscript {
         dependencies {
@@ -92,7 +92,7 @@ Instrumentation becomes as simple as adding dependencies to your module's Gradle
         }
     }
     ```
-2. Apply the plugin in your app level `build.gradle` and add the dependency
+2. Apply the plugin in your app-level `build.gradle` and add the dependency:
     ```groovy
     plugins {
         // ...other plugins
@@ -106,9 +106,9 @@ Instrumentation becomes as simple as adding dependencies to your module's Gradle
     ```
 
 
-### Capture Navigation
+### Capture navigation
 
-1. Add navigation Gradle Plugin dependency to project level `build.gradle`
+1. Add the navigation Gradle Plugin dependency to project-level `build.gradle`:
     ```groovy
     buildscript {
         dependencies {
@@ -116,7 +116,7 @@ Instrumentation becomes as simple as adding dependencies to your module's Gradle
         }
     }
     ```
-2. Apply the plugin in your app level `build.gradle` and add the dependency
+2. Apply the plugin in your app-level `build.gradle` and add the dependency:
     ```groovy
     plugins {
         // ...other plugins
@@ -128,21 +128,21 @@ Instrumentation becomes as simple as adding dependencies to your module's Gradle
       implementation ("com.segment.analytics.kotlin.signals:navigation:1.0.0")
     }
     ```
-3. (Optional) Add `SignalsActivityTrackingPlugin` to analytics to track Activity/Fragment navigation. **Not required for Compose Navigation**  
+3. (Optional) Add `SignalsActivityTrackingPlugin` to analytics to track Activity/Fragment navigation. **This is not required for Compose Navigation**.  
     ```kotlin
     analytics.add(SignalsActivityTrackingPlugin())
     ```
 
-### Capture Network
+### Capture network
 
 #### OkHttp
   
-1. add dependency:
+1. Add the dependency:
     ```groovy
     implementation ("com.segment.analytics.kotlin.signals:okhttp3:1.0.0")
     ```
 
-2. add `SignalsOkHttp3TrackingPlugin` as an interceptor to your OkHttpClient:
+2. Add `SignalsOkHttp3TrackingPlugin` as an interceptor to your OkHttpClient:
     ```kotlin
        private val okHttpClient = OkHttpClient.Builder()
            .addInterceptor(SignalsOkHttp3TrackingPlugin())
@@ -151,12 +151,12 @@ Instrumentation becomes as simple as adding dependencies to your module's Gradle
 
 #### Retrofit
 
-1. add dependency:
+1. Add the dependency:
     ```groovy
     implementation ("com.segment.analytics.kotlin.signals:okhttp3:1.0.0")
     ```
 
-2. add `SignalsOkHttp3TrackingPlugin` as an interceptor to your Retrofit client:
+2. Add `SignalsOkHttp3TrackingPlugin` as an interceptor to your Retrofit client:
     ```kotlin
        private val okHttpClient = OkHttpClient.Builder()
            .addInterceptor(SignalsOkHttp3TrackingPlugin())
@@ -168,12 +168,12 @@ Instrumentation becomes as simple as adding dependencies to your module's Gradle
     ```
 
 #### java.net.HttpURLConnection
- 1. add dependency:
+ 1. Add the dependency:
      ```groovy
      implementation ("com.segment.analytics.kotlin.signals:java-net:1.0.0")
      ```
  
- 2. install the `JavaNetTrackingPlugin` on where you initialize analytics:
+ 2. Install the `JavaNetTrackingPlugin` on where you initialize analytics:
      ```kotlin
          JavaNetTrackingPlugin.install()
      ```
@@ -183,7 +183,7 @@ Instrumentation becomes as simple as adding dependencies to your module's Gradle
 
 By default, Signals stores captured data on the device and doesn't forward it to Segment. This process prevents unnecessary bandwidth use and helps support privacy compliance requirements.
 
-To view captured signals in the Event Builder and create event generation rules, you need to enable `sendDebugSignalsToSegment`. This setting temporarily lets the SDK send signal data to Segment while you're testing.
+To view captured signals in the Event Builder and create event generation rules, enable `sendDebugSignalsToSegment`. This setting temporarily lets the SDK send signal data to Segment while you're testing.
 
 In addition, the SDK obfuscates signals sent to Segment by default. To view the completed data, you need to turn off `obfuscateDebugSignals`.
 
@@ -241,7 +241,7 @@ Signals.configuration = Configuration(
 Next, return to the source settings to turn on Auto-Instrumentation:
 
 1. Go to **Connections > Sources**.
-2. Select the source you used in Step 1.
+2. Select the source you used in [Step 1](#Step-1-Getting-started).
 3. From the source's overview tab, go to **Settings > Advanced**.
 4. Toggle Auto-Instrumention on.
 
@@ -251,13 +251,11 @@ After you build and run your app, use the [Event Builder](/docs/connections/auto
 
 1. In your Segment workspace, go to **Connections > Sources** and select the Android Source you configured.
 2. Open the **Event Builder** tab.
-3. Interact with your app on a simulator or test device:
-   - Navigate between screens.
-   - Tap buttons and UI elements.
-   - Trigger network requests.
-
-If `sendDebugSignalsToSegment` is enabled, Signals appear in real time as you interact with the app.
-
+3. Interact with your app on a simulator or test device: 
+    > - Navigate between screens. 
+    > - Tap buttons and UI elements. 
+    > - Trigger network requests. 
+    > If `sendDebugSignalsToSegment` is enabled, Signals appear in real time as you interact with the app.
 4. In the Event Builder, select a signal and click **Configure event** to define a new event.
 5. After you add any event mappings, click **Publish event rules** to save them.
 

From a4d51b3ee1194e5eae401b7df83755c9d663009a Mon Sep 17 00:00:00 2001
From: Sharon Adewusi <sadewusi@twilio.com>
Date: Fri, 7 Nov 2025 12:02:34 +0000
Subject: [PATCH 06/15] fixes + edits

---
 .../auto-instrumentation/swift-setup.md       | 69 +++++++++----------
 1 file changed, 34 insertions(+), 35 deletions(-)

diff --git a/src/connections/auto-instrumentation/swift-setup.md b/src/connections/auto-instrumentation/swift-setup.md
index 785e002a06..8bc6f71684 100644
--- a/src/connections/auto-instrumentation/swift-setup.md
+++ b/src/connections/auto-instrumentation/swift-setup.md
@@ -25,7 +25,7 @@ Segment recommends testing in a development environment before deploying Signals
 
 ## Prerequisites
 
-Auto-Instrumentation (aka Signals) works on top of Analytics. Make sure to add the following dependency to your project if you don't have analytics-swift already.
+Auto-Instrumentation (also known as Signals) works on top of Analytics. Make sure to add the following dependency to your project if you don't have analytics-swift already.
 
 ```swift
 dependencies: [
@@ -42,11 +42,10 @@ dependencies: [
     ]
     ```
 
-2. Import and initialize with your Analytics instance:
-   
-> success ""
-> See [configuration options](#configuration-options) for a complete list.
-> 
+2. Import and initialize with your Analytics instance: 
+    > success ""
+    > See [configuration options](#configuration-options) for a complete list.
+    > 
     ```swift
     import Segment
     import AnalyticsLive
@@ -75,14 +74,14 @@ dependencies: [
     ```
 
 3. Set up capture for the UI framework(s) you're using:
-     * [Capture SwiftUI Interactions](#swiftui)
-     * [Capture UIKit Interactions](#uikit)
-     * [Capture Network Activity](#capture-network)
+     * [Capture SwiftUI interactions](#swiftui).
+     * [Capture UIKit interactions](#uikit).
+     * [Capture network activity](#capture-network). 
 
 
 ## Step 2: Additional setup
 
-### Capture Interactions
+### Capture interactions
 
 #### SwiftUI
 
@@ -119,25 +118,25 @@ SwiftUI automatic signal capture requires adding typealiases to your code. This
     typealias List = SignalList
     ```
 
-3. Use the controls normally in your SwiftUI code:
+3. Use the controls in your SwiftUI code:
     ```swift
     struct ContentView: View {
         var body: some View {
             NavigationStack {
                 VStack {
                     Button("Click Me") {
-                        // Button tap will automatically generate a signal
+                        // Button tap automatically generates a signal
                     }
                     
                     TextField("Enter text", text: $text)
-                    // Text changes will automatically generate signals
+                    // Text changes automatically generates signals
                 }
             }
         }
     }
     ```
 
-> **Note:** The typealiases replace SwiftUI's native controls with signal-generating versions. Your code remains unchanged, but interactions are now automatically captured.
+The typealiases replace SwiftUI's native controls with signal-generating versions. Your code remains unchanged, but interactions are now automatically captured.
 
 #### UIKit
 
@@ -152,7 +151,7 @@ UIKit automatic signal capture uses method swizzling and requires no code change
     ))
     ```
 
-2. That's it! The following UIKit interactions and navigation events are automatically captured via method swizzling:
+2. The following UIKit interactions and navigation events are automatically captured via method swizzling:
 
     **Interactions:**
     - `UIButton` taps
@@ -167,16 +166,16 @@ UIKit automatic signal capture uses method swizzling and requires no code change
     - `UIViewController` modal presentations and dismissals
     - `UITabBarController` tab switches
 
-### Capture Navigation
+### Capture navigation
 
 Navigation capture is handled automatically when you enable SwiftUI or UIKit auto-signals:
 
-- **SwiftUI**: Captured through `SignalNavigationLink` and `SignalNavigationStack` when you add the typealiases
-- **UIKit**: Captured automatically via `UINavigationController`, `UIViewController`, and `UITabBarController` swizzling
+- **SwiftUI**: Captured through `SignalNavigationLink` and `SignalNavigationStack` when you add the typealiases.
+- **UIKit**: Captured automatically via `UINavigationController`, `UIViewController`, and `UITabBarController` swizzling.
 
-No additional setup required beyond enabling the appropriate auto-signal flags.
+No additional setup is required beyond enabling the appropriate auto-signal flags.
 
-### Capture Network
+### Capture network
 
 Network capture automatically tracks URLSession requests and responses.
 
@@ -192,13 +191,13 @@ Network capture automatically tracks URLSession requests and responses.
     ```
 
 2. Network requests made via URLSession are automatically captured, including:
-   - Request URL, method, headers, and body
-   - Response status, headers, and body
-   - Request/response correlation via request ID
+   - Request URL, method, headers, and body.
+   - Response status, headers, and body.
+   - Request or response correlation via request ID.
 
-> **Note:** Third-party networking libraries that use URLSession underneath (like Alamofire) should work automatically. Segment API endpoints are automatically blocked to prevent recursive tracking.
+Third-party networking libraries that use URLSession underneath (like Alamofire) should work automatically. Segment API endpoints are automatically blocked to prevent recursive tracking.
 
-#### Configuring Network Hosts
+#### Configuring network hosts
 
 You can control which network requests are tracked:
 
@@ -226,7 +225,7 @@ The following hosts are automatically blocked to prevent recursive tracking:
 
 By default, Signals stores captured data on the device and doesn't forward it to Segment. This process prevents unnecessary bandwidth use and helps support privacy compliance requirements.
 
-To view captured signals in the Event Builder and create event generation rules, you need to enable `sendDebugSignalsToSegment`. This setting temporarily lets the SDK send signal data to Segment while you're testing.
+To view captured signals in the Event Builder and create event generation rules, enable `sendDebugSignalsToSegment`. This setting temporarily lets the SDK send signal data to Segment while you're testing.
 
 In addition, the SDK obfuscates signals sent to Segment by default. To view the completed data, you need to turn off `obfuscateDebugSignals`.
 
@@ -235,9 +234,9 @@ In addition, the SDK obfuscates signals sent to Segment by default. To view the
 
 You can enable `sendDebugSignalsToSegment` and turn off `obfuscateDebugSignals` in one of three ways.
 
-### Option 1: Use Build Configurations to Toggle Debug Mode
+### Option 1: Use build configurations to toggle debug mode
   
-  1. Define different configurations in your project settings (Debug, Release, etc.)
+  1. Define different configurations in your project settings (for example, Debug or Release).
   
   2. Use compiler flags to control the setting:
       ```swift
@@ -254,7 +253,7 @@ You can enable `sendDebugSignalsToSegment` and turn off `obfuscateDebugSignals`
       ))
       ```
 
-### Option 2: Use a Feature Flag System
+### Option 2: Use a Feature Flag system
  If you're using Firebase Remote Config or a similar feature flag system, you can dynamically control `sendDebugSignalsToSegment` and `obfuscateDebugSignals` without requiring a new app build:
   ```swift
   let remoteConfig = RemoteConfig.remoteConfig()
@@ -267,7 +266,7 @@ You can enable `sendDebugSignalsToSegment` and turn off `obfuscateDebugSignals`
   ))
   ```
 
-### Option 3: Use Environment Variables (for debugging/testing)
+### Option 3: Use environment variables (for debugging or testing)
  You can check for environment variables or launch arguments during development:
   ```swift
   let isDebugEnabled = ProcessInfo.processInfo.environment["SIGNALS_DEBUG"] != nil
@@ -285,7 +284,7 @@ You can enable `sendDebugSignalsToSegment` and turn off `obfuscateDebugSignals`
 Next, return to the source settings to turn on Auto-Instrumentation:
 
 1. Go to **Connections > Sources**.
-2. Select the source you used in Step 1.
+2. Select the source you used in [Step 1](#Step-1-Getting-started).
 3. From the source's overview tab, go to **Settings > Advanced**.
 4. Toggle Auto-Instrumention on.
 
@@ -303,7 +302,7 @@ After integrating the SDK and running your app, verify that Segment is collectin
 
 ## Configuration options
 
-Using the Signals Configuration object, you can control the destination, frequency, and types of signals that Segment automatically tracks within your application. The following table details the configuration options for Signals-Swift.
+Using the Signals Configuration object, you can control the destination, frequency, and types of signals that Segment automatically tracks within your application. The following table details the configuration options for Signals-Swift:
 
 
 | OPTION            | REQUIRED | VALUE                     | DESCRIPTION |
@@ -312,15 +311,15 @@ Using the Signals Configuration object, you can control the destination, frequen
 | **maximumBufferSize** | No  | Int                   | The number of signals to be kept for JavaScript inspection. This buffer is first-in, first-out. Default is **1000**. |
 | **relayCount** | No  | Int                   | Relays every X signals to Segment. Default is **20**. |
 | **relayInterval** | No  | TimeInterval                   | Relays signals to Segment every X seconds. Default is **60**. |
-| **broadcasters**  | No      | [SignalBroadcaster]    | An array of broadcasters. These objects forward signal data to their destinations, like **WebhookBroadcaster**, or you could write your own **DebugBroadcaster** that writes logs to the developer console. **SegmentBroadcaster** is always added by the SDK when `sendDebugSignalsToSegment` is true. |
+| **broadcasters**  | No      | SignalBroadcaster    | An array of broadcasters. These objects forward signal data to their destinations, like **WebhookBroadcaster**, or you could write your own **DebugBroadcaster** that writes logs to the developer console. **SegmentBroadcaster** is always added by the SDK when `sendDebugSignalsToSegment` is true. |
 | **sendDebugSignalsToSegment**      | No      | Bool                    | Turns on debug mode and allows the SDK to relay Signals to Segment server. Default is **false**. It should only be set to true for development purposes. |
 | **obfuscateDebugSignals**      | No      | Bool                    | Obfuscates signals being relayed to Segment. Default is **true**. |
 | **apiHost** | No | String | API host for signal relay. Default is **"signals.segment.io/v1"**. |
 | **useUIKitAutoSignal** | No | Bool | Enables automatic UIKit signal capture via method swizzling. Default is **false**. |
 | **useSwiftUIAutoSignal** | No | Bool | Enables automatic SwiftUI signal capture (requires typealiases). Default is **false**. |
 | **useNetworkAutoSignal** | No | Bool | Enables automatic network signal capture for URLSession. Default is **false**. |
-| **allowedNetworkHosts** | No | [String] | Array of host patterns to track. Use `["*"]` for all hosts. Default is **["*"]**. |
-| **blockedNetworkHosts** | No | [String] | Array of host patterns to exclude from tracking. Default is **[]**. |
+| **allowedNetworkHosts** | No | String | Array of host patterns to track. Use `["*"]` for all hosts. Default is **["*"]**. |
+| **blockedNetworkHosts** | No | String | Array of host patterns to exclude from tracking. Default is **[]**. |
 
 ## Next steps
 

From ac84b7e56cce80b677b23036b776c752563551c7 Mon Sep 17 00:00:00 2001
From: Sharon Adewusi <sadewusi@twilio.com>
Date: Fri, 7 Nov 2025 12:05:33 +0000
Subject: [PATCH 07/15] fixes [netlify-build]

---
 .../auto-instrumentation/kotlin-setup.md          | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/src/connections/auto-instrumentation/kotlin-setup.md b/src/connections/auto-instrumentation/kotlin-setup.md
index ad8672c1ba..1625c32c9a 100644
--- a/src/connections/auto-instrumentation/kotlin-setup.md
+++ b/src/connections/auto-instrumentation/kotlin-setup.md
@@ -38,12 +38,12 @@ implementation("com.segment.analytics.kotlin:analytics-kotlin-live:1.3.0")
 ## Step 1: Getting started
 
 To get started:
-1. Add Signals Core
+1. Add Signals Core:
     ```groovy
     // signal core   
     implementation ("com.segment.analytics.kotlin.signals:core:1.0.0")
     ```
-2. Initialize Signals
+2. Initialize Signals:
  
 > success ""
 > See [configuration options](#configuration-options) for a complete list.
@@ -72,12 +72,12 @@ To get started:
 
 #### Kotlin Compose
 
-1. Add the dependency to your module’s Gradle build file.
+1. Add the dependency to your module’s Gradle build file:
     ```groovy
     implementation ("com.segment.analytics.kotlin.signals:compose:1.0.0")
     ```
 
-2. Add `SignalsComposeTrackingPlugin` to analytics
+2. Add `SignalsComposeTrackingPlugin` to analytics:
     ```kotlin
     analytics.add(SignalsComposeTrackingPlugin())
     ```
@@ -128,7 +128,7 @@ To get started:
       implementation ("com.segment.analytics.kotlin.signals:navigation:1.0.0")
     }
     ```
-3. (Optional) Add `SignalsActivityTrackingPlugin` to analytics to track Activity/Fragment navigation. **This is not required for Compose Navigation**.  
+3. (**Optional**): Add `SignalsActivityTrackingPlugin` to analytics to track Activity/Fragment navigation. **This is not required for Compose Navigation**.  
     ```kotlin
     analytics.add(SignalsActivityTrackingPlugin())
     ```
@@ -254,8 +254,9 @@ After you build and run your app, use the [Event Builder](/docs/connections/auto
 3. Interact with your app on a simulator or test device: 
     > - Navigate between screens. 
     > - Tap buttons and UI elements. 
-    > - Trigger network requests. 
-    > If `sendDebugSignalsToSegment` is enabled, Signals appear in real time as you interact with the app.
+    > - Trigger network requests.
+    >
+  > If `sendDebugSignalsToSegment` is enabled, Signals appear in real time as you interact with the app.
 4. In the Event Builder, select a signal and click **Configure event** to define a new event.
 5. After you add any event mappings, click **Publish event rules** to save them.
 

From 66a18242243f2caabf8ca3d189bbdd1c4c5ad58a Mon Sep 17 00:00:00 2001
From: Sharon Adewusi <sadewusi@twilio.com>
Date: Fri, 7 Nov 2025 12:24:59 +0000
Subject: [PATCH 08/15] fixing numbering [netlify-build]

---
 src/connections/auto-instrumentation/swift-setup.md | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/src/connections/auto-instrumentation/swift-setup.md b/src/connections/auto-instrumentation/swift-setup.md
index 8bc6f71684..1e99cc39e8 100644
--- a/src/connections/auto-instrumentation/swift-setup.md
+++ b/src/connections/auto-instrumentation/swift-setup.md
@@ -43,9 +43,8 @@ dependencies: [
     ```
 
 2. Import and initialize with your Analytics instance: 
-    > success ""
-    > See [configuration options](#configuration-options) for a complete list.
-    > 
+> success ""
+> See [configuration options](#configuration-options) for a complete list.
     ```swift
     import Segment
     import AnalyticsLive
@@ -72,7 +71,6 @@ dependencies: [
         // ... other options
     ))
     ```
-
 3. Set up capture for the UI framework(s) you're using:
      * [Capture SwiftUI interactions](#swiftui).
      * [Capture UIKit interactions](#uikit).

From 30816686c12597e1d79117fec72df2893bbcba77 Mon Sep 17 00:00:00 2001
From: Sharon Adewusi <sadewusi@twilio.com>
Date: Fri, 7 Nov 2025 12:31:12 +0000
Subject: [PATCH 09/15] trying again

---
 src/connections/auto-instrumentation/kotlin-setup.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/connections/auto-instrumentation/kotlin-setup.md b/src/connections/auto-instrumentation/kotlin-setup.md
index 1625c32c9a..92b70c53ef 100644
--- a/src/connections/auto-instrumentation/kotlin-setup.md
+++ b/src/connections/auto-instrumentation/kotlin-setup.md
@@ -43,12 +43,11 @@ To get started:
     // signal core   
     implementation ("com.segment.analytics.kotlin.signals:core:1.0.0")
     ```
-2. Initialize Signals:
- 
+2. Initialize Signals: 
 > success ""
 > See [configuration options](#configuration-options) for a complete list.
-> 
-    ```kotlin
+
+```kotlin
     //... <analytics config>....
     analytics.add(LivePlugins()) // Make sure LivePlugins is added
     analytics.add(Signals)  // Add the signals plugin
@@ -60,7 +59,8 @@ To get started:
       obfuscateDebugSignals = true
       // .. other options
     )
-    ```
+```
+
 3. Add proper dependency and plugin as needed to: 
      * [Capture interactions](#capture-interactions).
      * [Capture navigation](#capture-navigation).

From 4bdeb7eb2a14b6860f262749fe7402d75d32b791 Mon Sep 17 00:00:00 2001
From: Sharon Adewusi <sadewusi@twilio.com>
Date: Fri, 7 Nov 2025 12:31:32 +0000
Subject: [PATCH 10/15] please work [netlify-build]

---
 src/connections/auto-instrumentation/swift-setup.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/src/connections/auto-instrumentation/swift-setup.md b/src/connections/auto-instrumentation/swift-setup.md
index 1e99cc39e8..a98a5841d5 100644
--- a/src/connections/auto-instrumentation/swift-setup.md
+++ b/src/connections/auto-instrumentation/swift-setup.md
@@ -45,7 +45,7 @@ dependencies: [
 2. Import and initialize with your Analytics instance: 
 > success ""
 > See [configuration options](#configuration-options) for a complete list.
-    ```swift
+```swift
     import Segment
     import AnalyticsLive
     
@@ -70,7 +70,8 @@ dependencies: [
         #endif
         // ... other options
     ))
-    ```
+```
+    
 3. Set up capture for the UI framework(s) you're using:
      * [Capture SwiftUI interactions](#swiftui).
      * [Capture UIKit interactions](#uikit).

From 5661ef6725fe1e8021b08ff42d4e0cfa0085c04c Mon Sep 17 00:00:00 2001
From: Sharon Adewusi <sadewusi@twilio.com>
Date: Fri, 7 Nov 2025 12:43:01 +0000
Subject: [PATCH 11/15] pleaseee

Updated the initialization instructions for Signals and improved clarity in the documentation.
---
 src/connections/auto-instrumentation/kotlin-setup.md | 10 +++-------
 1 file changed, 3 insertions(+), 7 deletions(-)

diff --git a/src/connections/auto-instrumentation/kotlin-setup.md b/src/connections/auto-instrumentation/kotlin-setup.md
index 92b70c53ef..9f36b8e51d 100644
--- a/src/connections/auto-instrumentation/kotlin-setup.md
+++ b/src/connections/auto-instrumentation/kotlin-setup.md
@@ -43,11 +43,8 @@ To get started:
     // signal core   
     implementation ("com.segment.analytics.kotlin.signals:core:1.0.0")
     ```
-2. Initialize Signals: 
-> success ""
-> See [configuration options](#configuration-options) for a complete list.
-
-```kotlin
+2. Initialize Signals. For a complete list, see [configuration options](#configuration-options).
+  ```kotlin
     //... <analytics config>....
     analytics.add(LivePlugins()) // Make sure LivePlugins is added
     analytics.add(Signals)  // Add the signals plugin
@@ -59,8 +56,7 @@ To get started:
       obfuscateDebugSignals = true
       // .. other options
     )
-```
-
+  ```
 3. Add proper dependency and plugin as needed to: 
      * [Capture interactions](#capture-interactions).
      * [Capture navigation](#capture-navigation).

From b81f9fdd79933f52bd147eaf1f92274a54867105 Mon Sep 17 00:00:00 2001
From: Sharon Adewusi <sadewusi@twilio.com>
Date: Fri, 7 Nov 2025 12:43:59 +0000
Subject: [PATCH 12/15] praying this works [netlify-build]

Reword instructions for importing and initializing Analytics instance for clarity.
---
 src/connections/auto-instrumentation/swift-setup.md | 9 +++------
 1 file changed, 3 insertions(+), 6 deletions(-)

diff --git a/src/connections/auto-instrumentation/swift-setup.md b/src/connections/auto-instrumentation/swift-setup.md
index a98a5841d5..723a857147 100644
--- a/src/connections/auto-instrumentation/swift-setup.md
+++ b/src/connections/auto-instrumentation/swift-setup.md
@@ -42,10 +42,8 @@ dependencies: [
     ]
     ```
 
-2. Import and initialize with your Analytics instance: 
-> success ""
-> See [configuration options](#configuration-options) for a complete list.
-```swift
+2. Import and initialize with your Analytics instance. For a complete list, see [configuration options](#configuration-options).
+    ```swift
     import Segment
     import AnalyticsLive
     
@@ -70,8 +68,7 @@ dependencies: [
         #endif
         // ... other options
     ))
-```
-    
+    ``` 
 3. Set up capture for the UI framework(s) you're using:
      * [Capture SwiftUI interactions](#swiftui).
      * [Capture UIKit interactions](#uikit).

From 7c6f97181c36f9d6f103031d5c647e9ca27fcd00 Mon Sep 17 00:00:00 2001
From: Sharon Adewusi <sadewusi@twilio.com>
Date: Fri, 7 Nov 2025 13:14:47 +0000
Subject: [PATCH 13/15] last fixes

---
 src/connections/auto-instrumentation/swift-setup.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/connections/auto-instrumentation/swift-setup.md b/src/connections/auto-instrumentation/swift-setup.md
index 723a857147..5dc9db5af9 100644
--- a/src/connections/auto-instrumentation/swift-setup.md
+++ b/src/connections/auto-instrumentation/swift-setup.md
@@ -33,7 +33,7 @@ dependencies: [
 ]
 ```
 
-## Step 1: Getting started
+## Step 1: ing started
 
 1. Add AnalyticsLive to your Swift Package dependencies:
     ```swift
@@ -280,7 +280,7 @@ You can enable `sendDebugSignalsToSegment` and turn off `obfuscateDebugSignals`
 Next, return to the source settings to turn on Auto-Instrumentation:
 
 1. Go to **Connections > Sources**.
-2. Select the source you used in [Step 1](#Step-1-Getting-started).
+2. Select the source you used in [Step 1](#step-1-getting-started).
 3. From the source's overview tab, go to **Settings > Advanced**.
 4. Toggle Auto-Instrumention on.
 

From 33c50a6385bf7ffc6447ad6fe2032c000c6f378b Mon Sep 17 00:00:00 2001
From: Sharon Adewusi <sadewusi@twilio.com>
Date: Fri, 7 Nov 2025 13:15:20 +0000
Subject: [PATCH 14/15] all done [netlify-build]

---
 src/connections/auto-instrumentation/kotlin-setup.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/connections/auto-instrumentation/kotlin-setup.md b/src/connections/auto-instrumentation/kotlin-setup.md
index 9f36b8e51d..3c8ca07d9f 100644
--- a/src/connections/auto-instrumentation/kotlin-setup.md
+++ b/src/connections/auto-instrumentation/kotlin-setup.md
@@ -237,7 +237,7 @@ Signals.configuration = Configuration(
 Next, return to the source settings to turn on Auto-Instrumentation:
 
 1. Go to **Connections > Sources**.
-2. Select the source you used in [Step 1](#Step-1-Getting-started).
+2. Select the source you used in [Step 1](#step-1-getting-started).
 3. From the source's overview tab, go to **Settings > Advanced**.
 4. Toggle Auto-Instrumention on.
 

From 48efb817ca8ff49d67e0388da0442ee6d6086355 Mon Sep 17 00:00:00 2001
From: Sharon Adewusi <sadewusi@twilio.com>
Date: Fri, 7 Nov 2025 13:32:49 +0000
Subject: [PATCH 15/15] done done done

---
 src/connections/auto-instrumentation/swift-setup.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/connections/auto-instrumentation/swift-setup.md b/src/connections/auto-instrumentation/swift-setup.md
index 5dc9db5af9..953efab2f6 100644
--- a/src/connections/auto-instrumentation/swift-setup.md
+++ b/src/connections/auto-instrumentation/swift-setup.md
@@ -33,7 +33,7 @@ dependencies: [
 ]
 ```
 
-## Step 1: ing started
+## Step 1: Getting started
 
 1. Add AnalyticsLive to your Swift Package dependencies:
     ```swift