Setup Guide for SwiftUI Automatic Compile-Time Selectors (V4) Preview

Introduction

Fullstory can automatically generate selectors for SwiftUI Views. Version 4 of SwiftUI selectors is compile-time: instead of deriving a selector by inspecting views as they render, the FullStorySwiftUIWrapper tool rewrites your SwiftUI source before it is compiled, substituting Fullstory proxy types for the SwiftUI types they stand in for. Each proxy renders identically to the original and carries the information needed to describe the view, so the selector is determined by the structure of your code rather than reconstructed at runtime.

This produces more accurate and more stable selectors than version 3, and it supports a much larger set of SwiftUI view types and modifiers. The tool also performs cross-file analysis across your whole project and its Swift Package dependencies, so it can tell when a name like List refers to one of your own types rather than SwiftUI's, and leave it alone.

The transformation is applied to your own source files, in place, as an Xcode pre-build action. Every edit is bracketed by /*Fullstory_XFORM_start*/ and /*Fullstory_XFORM_end*/ markers or by a __FsS prefix, and the tool can reverse all of them exactly. Nothing is deleted or reflowed, so your line numbers — and therefore crash reports and debugger breakpoints — stay aligned with your original source.

Before you begin

1. Make sure the Fullstory SDK is configured — follow Getting Started with iOS Data Capture. This includes the FullStoryCommandLine build phase.
2. In your Target's Build Settings, set User Script Sandboxing to NO.
3. If you previously used version 3 selectors, remove any Build Rule or Pre-action that runs FullStorySwiftUITransformer. Running both tools in the same build is not supported.

Installing the package

The selectors library and the FullStorySwiftUIWrapper tool ship together in a public Swift package.

1. In Xcode, choose File > Add Package Dependencies… and add:

   https://github.com/fullstorydev/fullstory-swiftui-selectors-ios

   Pin it to an Exact Version. Each FSSwiftUISelectors release is built against one specific Fullstory build, so its manifest pins the matching Fullstory version exactly.

2. Add the FSSwiftUISelectors library to your app target (under General > Frameworks, Libraries, and Embedded Content), the same way the Fullstory framework is added.

3. Because you will also be calling Fullstory APIs directly (FS.setup(…) and friends), most projects should declare both packages explicitly, at the same version. In a Package.swift that looks like:

   dependencies: [
       .package(url: "https://github.com/fullstorydev/fullstory-swiftui-selectors-ios", exact: "1.74.0"),
       .package(url: "https://github.com/fullstorydev/fullstory-swift-package-ios", exact: "1.74.0"),
   ]

Configuration

Update your Info.plist (or the Info tab of your project properties) to include the following in the FullStory dictionary:

• SwiftUIEnabled type Boolean to YES
• SwiftUISelectorVersion type Number to 4
• SwiftUISelectorPreview type Number to 1

Running the transformer

Run the included FullStorySwiftUIWrapper using either:

• (Recommended) Pre-actions, which modifies the source in your repository, supports the use of debug breakpoints, and enables cross-file analysis.
  OR
• Build Rules, which don't modify the source in your repository, but transform one file at a time with no cross-file analysis.

Command line options

FullStorySwiftUIWrapper takes one or more input paths, followed by any of the options below.

Input paths

Directory and file inputs cannot be mixed in one invocation.

Options

Excluding individual files

Two directives control the tool from inside a source file. Add either string anywhere in the file, with no spaces.

Troubleshooting

"Unable to find module dependency: 'FSSwiftUISelectors'"

Xcode resolves packages and plans the build before it runs pre-build actions, so a dependency the tool injects into a Package.swift during a build is invisible to the targets being built in that same build. The plan is then cached, and re-resolving does not discard it, so later builds repeat the same failure.

The tool prints a warning when this happens, naming the manifests it changed. Choose Product > Clean Build Folder and build again. Your transformed sources are preserved. This affects only the first build after a manifest changes.

A file fails to transform

Add --warn-on-error to your pre-action so the file is skipped with a warning and the build continues; that file is simply left uninstrumented. Please report the file to support so the rule can be fixed.

Reverting the transformation

Run the tool again with --untransform and the same input paths. Every edit is reversible, and round-tripping restores your source byte for byte. Removing the pre-action alone does not revert the source, since the original files are modified.

Package sources appear uninstrumented

Use File > Packages > Reset Package Caches and build again; the build may have used cached copies rather than the transformed package sources.

Additional notes

Where the tool cannot be certain that a name refers to a SwiftUI type — because you declared a type of the same name, or because a protocol may have a conformer outside the code being analyzed — it leaves that code alone. Missing instrumentation is preferable to a rewrite that would not compile, so some views may be uninstrumented by design.

Re-running the tool is safe and idempotent. It reverts any previous transformation before applying the current one, so incremental builds produce identical bytes and an upgrade to a newer version of the tool never layers on top of an older result.

If you have any questions, run into any issues, or have requests to add support for a view, please contact support! We will be very happy to help.