Auto-Instrumentation Setup

This guide outlines the steps required to set up the Signals SDK in your Apple OS applications using Swift.

Learn how to connect an existing source, integrate dependencies, turn on Auto-Instrumentation, and verify that your setup captures and processes data as intended.

Before you start

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.

Prerequisites

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.

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:

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

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

    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.
   • Capture UIKit interactions.
   • Capture network activity.

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:

    Signals.shared.useConfiguration(SignalsConfiguration(
        writeKey: "YOUR_WRITE_KEY",
        useSwiftUIAutoSignal: true
        // ... other options
    ))
   

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

    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
   

3. Use the controls in your SwiftUI code:

    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
                }
            }
        }
    }
   

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:

    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:

    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 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.

Configuring network hosts

You can control which network requests are tracked:

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

• 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.

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:

    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:

  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:

  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.
3. From the source’s overview tab, go to Settings > Advanced.
4. Toggle Auto-Instrumention on.

Step 5: Verify and deploy events

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.

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:

Next steps

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.