Multi-Instance

​

Quick Reference

​

Event Routing

1. Explicit userpilot: argument, when the API exposes one (for example View.userpilotScreen(_:userpilot:)).
2. Anchored owner, when something in the UI hierarchy claims the originating UI (Config.attach(viewControllerClasses:), Config.attach(windows:), Config.attach(bundles:)).
3. Default — the instance that claimed isDefault (defaults to true).

​

Single-Instance Integration

let config = Userpilot.Config(token: "YOUR_TOKEN")
    .logging(enabled: true)
    .enableScreenAutoCapture()
    .enableInteractionAutoCapture()

let userpilot = Userpilot(config: config)   // isDefault defaults to true → claims default
userpilot.identify(userId: "user-123")
userpilot.track(eventName: "Added to Cart")

​

Multi-Instance Integration

​

Vendor SDK

public final class AcmeSDK {
    public static let shared = AcmeSDK()

    private let acmeUserpilot: Userpilot

    private init() {
        let config = Userpilot.Config(token: "ACME")
            .defaultInstance(false)
            .enableScreenAutoCapture()
            .enableInteractionAutoCapture()
            .attach(bundles: [Bundle(for: AcmeSDK.self)])

        acmeUserpilot = Userpilot(config: config)
    }

    public func identifyAcmeUser(_ id: String) {
        acmeUserpilot.identify(userId: id)
    }
}

• isDefault defaults to true. Every Config attempts to claim the default role on registration unless you opt out. Vendor SDKs must call .defaultInstance(false) so they do not compete for that single slot. When every instance opts out, there is no default and un-anchored events are dropped.
• Default resolution is claim-based, not registration-order-based — the instance that successfully holds the isDefault claim becomes the SDK’s default fallback. Init order between host and vendor does not matter when the vendor opts out; only one claimant is allowed at a time, and a second conflicting claim is rejected.
• attach(bundles:) teaches the autocapture router which UI events belong to your tenant.
• Keep a strong reference to your instance (for example a stored property on your facade). The registry holds instances weakly.

​

Host app + embedded vendor

let config = Userpilot.Config(token: "HOST")
    .enableScreenAutoCapture()
    .enableInteractionAutoCapture()
    // no .defaultInstance(true) needed — isDefault defaults to true

let hostUserpilot = Userpilot(config: config)
AcmeSDK.shared.identifyAcmeUser("acme-99")

​

The Default Instance

​

Autocapture Routing

1. attach(viewControllerClasses:) — view controller class match (subclass-aware).
2. attach(windows:) — the view controller’s containing window matches.
3. attach(bundles:) — Bundle(for: VC.class) identifier matches.
4. Default fallback — routes to the instance that claimed isDefault, or is dropped when no default exists.

​

SwiftUI ownership

​

SwiftUI Screen Events

struct AcmeSettings: View {
    let acmeUserpilot: Userpilot

    var body: some View {
        VStack { /* … */ }
            .userpilotScreen("Acme.Settings", userpilot: acmeUserpilot)
    }
}

​

Forwarding Events to the Host

let hostConfig = Userpilot.Config(token: "HOST")
    .enableScreenAutoCapture()
    .enableInteractionAutoCapture()
    .allowReceiveEventsFromExternalSource()

let hostUserpilot = Userpilot(config: hostConfig)

• Autocapture events that resolve to a non-default instance are published to that instance and forwarded to the default instance.
• The flag is read only on the resolved default instance. Setting it on a vendor instance has no effect.
• Forwarded events are delivered unchanged through the host’s publisher — associated with the host’s user/session and reported to the host backend. There is no extra tagging.
• The host’s own events are never duplicated to itself, and forwarding never re-routes, so there is no fan-out loop.

​

Idempotent Initialization

let a = Userpilot(config: .init(token: "HOST"))   // claims default (isDefault defaults true)
let b = Userpilot(config: .init(token: "HOST"))
// a and b share the same dependency container. The supplied config on `b` is discarded.

​

Experience Presentation

• Two instances can present experiences simultaneously on different window levels.
• Touches outside any presented experience pass through so the underlying app stays interactive.
• Window levels are deterministic and stable across launches.

​

Push Notifications

• Token registration fans out to every monitor so each instance can forward the token to its backend.
• Notification responses use the payload app_token to route directly to the matching Userpilot instance. Older payloads without app_token fall back to trying registered monitors until one claims the response.

​

Limitations

• Static autocapture flags. UIKit method swizzles install once per process for the union of all instances’ enabled features. Autocapture uses each instance’s config to filter events at delivery time.
• The default fallback is not thread-locked to a tenant. It always points at the default claimant (isDefault). To act on a specific tenant, keep and pass the explicit Userpilot instance you created. When no instance holds the default role, there is no first-registered fallback.
• stopAutoCapture() / resumeAutoCapture() are per-instance methods.
• Userpilot.enableAutomaticPushConfig() is process-wide — calling it from any instance enables it for all.
• SwiftUI ownership can be ambiguous with no UIKit container in your bundle. Prefer .attach(windows:) or pass userpilot: explicitly.
• Two instances with the same token never happens through the public factory — Userpilot(config:) is idempotent.

​

Complete Example

// AppDelegate.swift (host app)
let hostConfig = Userpilot.Config(token: "HOST")
    .logging(enabled: true)
    .enableScreenAutoCapture()
    .enableInteractionAutoCapture()
let hostUserpilot = Userpilot(config: hostConfig)   // isDefault defaults to true → claims default

// AcmeSDK.swift (vendor SDK)
let vendorConfig = Userpilot.Config(token: "ACME")
    .defaultInstance(false)
    .enableScreenAutoCapture()
    .enableInteractionAutoCapture()
    .attach(bundles: [Bundle(for: AcmeSDK.self)])
let acmeUserpilot = Userpilot(config: vendorConfig)

hostUserpilot.identify(userId: "host-42")
acmeUserpilot.identify(userId: "acme-99")
acmeUserpilot.track(eventName: "vendor_action")