diff --git a/src/connections/auto-instrumentation/kotlin-setup.md b/src/connections/auto-instrumentation/kotlin-setup.md index b7fa63241a..3c8ca07d9f 100644 --- a/src/connections/auto-instrumentation/kotlin-setup.md +++ b/src/connections/auto-instrumentation/kotlin-setup.md @@ -17,167 +17,180 @@ 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). -## Step 1: Install dependencies +## Prerequisites -To install Signals, add the following dependencies to your app-level Gradle build file. +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 -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 = "")) - -// 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()) +To get started: +1. Add Signals Core: + ```groovy + // signal core + implementation ("com.segment.analytics.kotlin.signals:core:1.0.0") + ``` +2. Initialize Signals. For a complete list, see [configuration options](#configuration-options). + ```kotlin + //... .... + 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 `` 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 the 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 the 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. **This is 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 the 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 the 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 the 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, 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 +199,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,40 +214,50 @@ 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") ) ``` +## 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](#step-1-getting-started). +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. 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 `debugMode` 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. > 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 +265,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` | 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 | 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 diff --git a/src/connections/auto-instrumentation/swift-setup.md b/src/connections/auto-instrumentation/swift-setup.md index 7133f052d8..953efab2f6 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,69 +21,270 @@ 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 +Segment recommends testing in a development environment before deploying Signals in production. For more information, see [Debug mode](#step-3-enable-debug-mode). -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 (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. - ```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") +] +``` + +## 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. Add the initialization code and configuration options: +2. Import and initialize with your Analytics instance. For a complete list, see [configuration options](#configuration-options). + ```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 -> success "" -> See [configuration options](#configuration-options) for a complete list. +### 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 - {... ....} + Signals.shared.useConfiguration(SignalsConfiguration( + writeKey: "YOUR_WRITE_KEY", + useSwiftUIAutoSignal: true + // ... other options + )) + ``` - // Set up the Signals SDK configuration - let config = Signals.Configuration( - writeKey: "", // Replace 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 in your SwiftUI code: + ```swift + struct ContentView: View { + var body: some View { + NavigationStack { + VStack { + Button("Click Me") { + // Button tap automatically generates a signal + } + + TextField("Enter text", text: $text) + // Text changes automatically generates signals + } + } + } + } + ``` - // 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) +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. + +1. Enable UIKit auto-signals in your configuration: + ```swift + Signals.shared.useConfiguration(SignalsConfiguration( + writeKey: "YOUR_WRITE_KEY", + useUIKitAutoSignal: true + // ... other options + )) + ``` + +2. 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. + +No additional setup is required beyond enabling the appropriate auto-signal flags. + +### 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 + )) ``` -Verify that you replaced `` with the actual write key you copied in [Step 1](#step-1-get-your-source-write-key). +2. Network requests made via URLSession are automatically captured, including: + - Request URL, method, headers, and body. + - Response status, headers, and body. + - Request or response correlation via request ID. + +Third-party networking libraries that use URLSession underneath (like Alamofire) should work automatically. Segment API endpoints are automatically blocked to prevent recursive tracking. -#### SwiftUI projects +#### Configuring network hosts -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: +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, 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 (for example, Debug or Release). + + 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 or 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: 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. -## 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,26 +292,30 @@ 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**. ## 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. - -| `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. +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 | 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