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.

Step 1: Get your source write key

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.

Step 2: Add dependencies and initialization code

Next, add the Signals SDKs to your Swift applicatiion.

1. Use Swift Package Manager to add the Signals SDK from the following repository:

    https://github.com/segment-integrations/analytics-swift-live.git
   

2. Add the initialization code and configuration options:

```swift
// Configure Analytics with your settings
{... <analytics config>....} 

// 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
)

// Locate and set the fallback JavaScript file for edge functions
let fallbackURL = Bundle.main.url(forResource: "MyEdgeFunctions", withExtension: "js")

// 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)
```

Verify that you replaced <WRITE_KEY> with the actual write key you copied in Step 1.

SwiftUI projects

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:

import Foundation
import Signals

typealias Button = SignalButton
typealias NavigationStack = SignalNavigationStack
typealias NavigationLink = SignalNavigationLink
typealias TextField = SignalTextField
typealias SecureField = SignalSecureField

Step 3: 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 4: 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. Launch your app in debug mode. This enables signal collection so you can see activity in the Event Builder.
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.