instrumentation-facades

Instrumentation Facades

Feature code often becomes verbose when sending many pixels, or mixing pixel calls and wide event lifecycle management.

Consider a subscription purchase flow that needs to:

• Fire a daily pixel when purchase starts
• Start a wide event flow
• Update the wide event with timing data
• Fire unique pixels on success
• Complete the wide event with success/failure/cancelled status
• Handle multiple error cases with different failing steps

This leads to instrumentation code scattered throughout the feature, making it hard to:

• Understand the feature's core logic
• Test the feature in isolation
• Modify instrumentation without touching feature code
• Ensure all instrumentation points are covered

We can improve this using the facade pattern, abstracting our instrumentation behind a protocol. This is done by defining a protocol with domain-specific hooks that the feature calls, then implementing the protocol in a dedicated object that handles all instrumentation.

Benefits

1. Feature code emits domain events only - Cleaner, more readable feature logic
2. Instrumentation logic is centralized - Easy to audit and modify
3. Easy to inject mocks for unit testing - Test feature behavior without pixel dependencies

File Organization

Instrumentation facades should be placed in the same module as the feature they instrument:

Component	Location
Protocol	Feature module (e.g., Subscription/SubscriptionPurchaseInstrumentation.swift)
Default Implementation	Same module as protocol
Mock for Testing	Test target or same module

For features that span iOS and macOS, place the protocol and implementation in a shared package (e.g., BrowserServicesKit).

Pattern Structure

Step 1: Define the Protocol

Create a protocol with methods for each instrumentation hook your feature needs. Name methods after domain events, not pixels:

public protocol SubscriptionPurchaseInstrumentation: AnyObject {
    func purchaseAttemptStarted(selectionID: String, freeTrialEligible: Bool, ...)
    func purchaseCancelled()
    func purchaseFailed(step: FailingStep, error: Error)
    func activationSucceeded()
    // ... other domain events
}