iOS SwiftUI SDK Instrumentation- Automated Screen Tracking

Introduction

The Blue Triangle iOS SDK includes BTTInstrumenter, a companion command-line tool that automatically instruments SwiftUI views in your iOS app. Once integrated into your Xcode project, BTTInstrumenter runs on every build — eliminating the need to manually add instrumentation code to each view.

Setup

1. Install BTTInstrumentor

Install the BlueTriangle SwiftUI instrumentor via Homebrew.

Install BTTInstrumentor using the commands.

brew tap blue-triangle-tech/tools

brew trust blue-triangle-tech/tools

brew install bttinstrumentor

Install BTTInstrumentor to Your Project
1. Quit Xcode and navigate to your project root in Terminal.
2. Use below command in your project dirctory.
```
BTTInstrumentor install
```

3.Verify Setup

Check installetion with below command
```
BTTInstrumentor check
```

How It Works

.btt/ folder in your project root contains instrumenter along with supported files.

.btt/ contains

BTTInstrumentor - BTT instrumenter binary. This is a mac binary which dos actual injection
btt_instrument.sh - The shell script that Xcode's pre-action runs before each build
btt_config.json - Stores instrumented config information

scheme pre-action contains

BTTInstrumentation - path to execute .btt/btt_instrument.sh that exicute BTTInstrumentor

Setup command “BTTInstrumentor install” creates all above elements in your project. These are installed in project so that everytime on any change in swift file it will reisntrument. To make is available on any mac this project cloned recommended is to commit this folder.

Ignore Views

A swift file can be mark to ignore by BTTInstrumenter, it will not instrument all views inside this file

Ignore an Single View

Add // btt:ignore on the line immediately before the struct declaration:

// btt:ignore 
struct DebugOverlayView: View { 
   var body: some View { 
         Text("Debug") 
      } 
  }

BTTInstrumentor will skip this view on all future builds.

Ignore an Entire File

Add // btt:ignore-file anywhere in the file (conventionally at the top):

// btt:ignore
import SwiftUI

struct DebugOverlayView: View { 
   var body: some View { 
         Text("Debug") 
      } 
  }

All views in that file are permanently excluded.

Update BTTInstrumentor

As Bluetriange publish new versions of BTTInstrumenter you can update it with below commands.

Run brew upgrade bttinstrumentor to install the SwiftUI instrumentor.
```
brew upgrade bttinstrumentor
```
Quit Xcode and navigate to your project root in Terminal.
Run BTTInstrumentor install installer detects newer binary and prompts you to update
```
BTTInstrumentor install
```

Uninstall

Remove Instrumentation from a Project

Quit Xcode and navigate to your project root in Terminal.
Run BTTInstrumentor uninstall that will be prompted to choose specific target or Remove all
```
BTTInstrumentor uninstall
```

Troubleshooting

If something is not working as expected, run the check command:
```
BTTInstrumentor check
```

This prints a detailed ✓ / ✗ status for each check. If all items show ✓, your project is correctly instrumented and ready to go.

Detailed diagnostic output during install or uninstall, add --verbose to the command:
```
BTTInstrumentor install --verbose
BTTInstrumentor uninstall --verbose
```

View body has long nesting

When View body views are deeply nested like an example bellow “BTTInstrumentor logs a warning” like:

HomeView has a view body too complex for auto-instrumentation

import SwiftUI

struct HomeView: View {
    @State private var condition = true
    var body: some View {
        if condition {
            if condition {
                if condition {
                    if condition {
                        VStack {
                            Text("Deep")
                        }
                    }
                }
            }
        }
    }
}

To work with BTTInstrumentor, wrap the body in a Group so the modifier can be applied at the top level.

Known Issues

Private Swift Package Manager Packages

BTTInstrumentor does not instrument SwiftUI views inside local or remote Swift packages added to your project. Only source files that belong directly to an Xcode target are scanned and instrumented.

This is a current limitation. If your app's SwiftUI views live inside a local package (added via File → Add Local Package) or a remote SPM dependency, those views will not receive .bttTrackScreen() automatically.

Articles in this section