Auto-Instrumentation Setup

You need the writeKey from an existing Segment source. To find it:

1. In your Segment workspace, go to Connections > Sources.
2. Select your source.
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.

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.

1
dependencies: [
2
    .package(url: "https://github.com/segmentio/analytics-swift.git", from: "1.9.1")
3
]

1. Add AnalyticsLive to your Swift Package dependencies:
   Copy code block

   1
   dependencies: [
   2
       .package(url: "https://github.com/segmentio/analytics-live-swift.git", from: "3.2.1")
   3
   ]

2. Import and initialize with your Analytics instance. For a complete list, see configuration options.
   Copy code block

   1
   import Segment
   2
   import AnalyticsLive
   3
   
   4
   let analytics = Analytics(configuration: Configuration(writeKey: "YOUR_WRITE_KEY"))
   5
   
   6
   // Add LivePlugins first
   7
   analytics.add(plugin: LivePlugins())
   8
   
   9
   // Add Signals
   10
   analytics.add(plugin: Signals.shared)
   11
   
   12
   // Configure Signals
   13
   Signals.shared.useConfiguration(SignalsConfiguration(
   14
       writeKey: "YOUR_WRITE_KEY", // Same writeKey as Analytics
   15
       useUIKitAutoSignal: true,
   16
       useSwiftUIAutoSignal: true,
   17
       useNetworkAutoSignal: true,
   18
       #if DEBUG
   19
       // NOTE: See section below on using these flags appropriately.
   20
       sendDebugSignalsToSegment: true, // Only true for development
   21
       obfuscateDebugSignals: false // Only false for development
   22
       #endif
   23
       // ... other options
   24
   ))

3. Set up capture for the UI framework(s) you're using:
   • Capture SwiftUI interactions.
   • Capture UIKit interactions.
   • Capture network activity.

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:
   Copy code block

   1
   Signals.shared.useConfiguration(SignalsConfiguration(
   2
       writeKey: "YOUR_WRITE_KEY",
   3
       useSwiftUIAutoSignal: true
   4
       // ... other options
   5
   ))

2. Add the following typealiases to your SwiftUI views or in a shared file:
   Copy code block

   1
   import SwiftUI
   2
   import AnalyticsLive
   3
   
   4
   // Navigation
   5
   typealias NavigationLink = SignalNavigationLink
   6
   typealias NavigationStack = SignalNavigationStack // iOS 16+
   7
   
   8
   // Selection & Input Controls
   9
   typealias Button = SignalButton
   10
   typealias TextField = SignalTextField
   11
   typealias SecureField = SignalSecureField
   12
   typealias Picker = SignalPicker
   13
   typealias Toggle = SignalToggle
   14
   typealias Slider = SignalSlider // Not available on tvOS
   15
   typealias Stepper = SignalStepper // Not available on tvOS
   16
   
   17
   // List & Collection Views
   18
   typealias List = SignalList

3. Use the controls in your SwiftUI code:
   Copy code block

   1
   struct ContentView: View {
   2
       var body: some View {
   3
           NavigationStack {
   4
               VStack {
   5
                   Button("Click Me") {
   6
                       // Button tap automatically generates a signal
   7
                   }
   8
                   
   9
                   TextField("Enter text", text: $text)
   10
                   // Text changes automatically generates signals
   11
               }
   12
           }
   13
       }
   14
   }

The typealiases replace SwiftUI's native controls with signal-generating versions. Your code remains unchanged, but interactions are now automatically captured.

UIKit automatic signal capture uses method swizzling and requires no code changes.

1. Enable UIKit auto-signals in your configuration:

   Copy code block

   1
   Signals.shared.useConfiguration(SignalsConfiguration(
   2
       writeKey: "YOUR_WRITE_KEY",
   3
       useUIKitAutoSignal: true
   4
       // ... other options
   5
   ))

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

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.

Network capture automatically tracks URLSession requests and responses.

1. Enable network auto-signals in your configuration:
   Copy code block

   1
   Signals.shared.useConfiguration(SignalsConfiguration(
   2
       writeKey: "YOUR_WRITE_KEY",
   3
       useNetworkAutoSignal: true,
   4
       allowedNetworkHosts: ["*"], // Allow all hosts (default)
   5
       blockedNetworkHosts: [] // Block specific hosts (optional)
   6
       // ... other options
   7
   ))

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.

You can control which network requests are tracked:

1
SignalsConfiguration(
2
    writeKey: "YOUR_WRITE_KEY",
3
    useNetworkAutoSignal: true,
4
    allowedNetworkHosts: ["api.myapp.com", "*.example.com"], // Only track these hosts
5
    blockedNetworkHosts: ["analytics.google.com"] // Exclude these hosts
6
)

• 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

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.

You can enable sendDebugSignalsToSegment and turn off obfuscateDebugSignals in one of three ways.

1. Define different configurations in your project settings (for example, Debug or Release).
2. Use compiler flags to control the setting:
   Copy code block

   1
   Signals.shared.useConfiguration(SignalsConfiguration(
   2
       writeKey: "YOUR_WRITE_KEY",
   3
       // ... other config options
   4
       #if DEBUG
   5
       sendDebugSignalsToSegment: true,
   6
       obfuscateDebugSignals: false
   7
       #else
   8
       sendDebugSignalsToSegment: false,
   9
       obfuscateDebugSignals: true
   10
       #endif
   11
   ))

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:

1
let remoteConfig = RemoteConfig.remoteConfig()
2

3
Signals.shared.useConfiguration(SignalsConfiguration(
4
    writeKey: "YOUR_WRITE_KEY",
5
    // ... other config options
6
    sendDebugSignalsToSegment: remoteConfig["sendDebugSignalsToSegment"].boolValue,
7
    obfuscateDebugSignals: remoteConfig["obfuscateDebugSignals"].boolValue
8
))

You can check for environment variables or launch arguments during development:

1
let isDebugEnabled = ProcessInfo.processInfo.environment["SIGNALS_DEBUG"] != nil
2

3
Signals.shared.useConfiguration(SignalsConfiguration(
4
    writeKey: "YOUR_WRITE_KEY",
5
    // ... other config options
6
    sendDebugSignalsToSegment: isDebugEnabled,
7
    obfuscateDebugSignals: !isDebugEnabled
8
))

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.

After integrating the SDK and running your app, verify that Segment is collecting signals:

1. In your Segment workspace, go to Connections > Sources and select the source you used for Auto-Instrumentation.
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. 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.

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:

This guide walked you through initial Signals SDK/Auto-Instrumentation setup. Next, read the Auto-Instrumentation Signals Implementation Guide, which dives deeper into Signals and offers example rules.