Track screens

The SDK records a built-in $screen event each time the user lands on a new screen. Each event carries the screen the user came from and how long they stayed there, so one event describes a whole transition. Screen tracking is on by default and needs analytics consent.

UIKit

Nothing to add. When a view controller from your app appears, the SDK records it. Framework containers such as navigation and tab bar controllers are skipped, and so are child controllers embedded inside a screen. The screen name is the class name, and the path is the chain of parent controllers, such as /MainTabBarController/HomeViewController.

A view controller belongs to your app when its class is defined in your app's main bundle. Two setups need more than that rule:

• Feature modules in dynamic frameworks. Controllers defined in an embedded framework are not in the main bundle, so they are not recorded.
• Statically linked libraries. A library linked into your app binary, which is the Swift Package Manager default, places its controllers in the main bundle. A payment sheet or an image picker from such a library is then recorded as one of your screens.

Set isAppScreenClass to decide which classes are your screens:

let featureBundle = Bundle(for: CheckoutViewController.self)

var options = VoidhashOptions()
options.screenTracking.isAppScreenClass = { type in
    Bundle(for: type) == .main || Bundle(for: type) == featureBundle
}

Container and child controllers are still skipped, and mapScreen still applies afterwards.

SwiftUI

SwiftUI navigation does not expose view controllers, so mark each screen with a modifier:

struct CheckoutView: View {
    var body: some View {
        content
            .voidhashScreen("Checkout")
    }
}

Pass title: to record a display title as well: .voidhashScreen("Checkout", title: "Your order"). The screen is recorded when the view appears. Once a SwiftUI screen has been recorded, the hosting controller is no longer reported by the automatic UIKit tracking. This includes your own UIHostingController subclasses, so a SwiftUI screen pushed from UIKit is recorded once per visit.

Custom navigation

Call screen() yourself when your app drives navigation another way, such as onboarding steps or pager pages. Each call records a new screen, even with the same name:

await voidhash.screen("Onboarding step 2", properties: ["step": .number(2)])

Event properties

A screen is recorded once when it becomes visible. Returning from the background does not record it again. Navigating back to an earlier screen does.

Options

Configure tracking when you configure the SDK:

var options = VoidhashOptions()
options.screenTracking.automatic = false
options.screenTracking.mapScreen = { view in
    view.name.hasPrefix("Debug") ? nil : view
}
Voidhash.configure(publishableKey: "vh_pk_...", options: options)

Set automatic to false to stop the SDK from observing view controllers. mapScreen lets you rename a screen or drop it by returning nil. isAppScreenClass decides which view controller classes count as your screens, as described in UIKit.

To stop accepting screen events for a whole project without an app release, turn off $screen in the project's event settings. See Events.

Next steps

• Capture analytics
• Events
• Analytics reports