Quick start: iOS

On this page you send your first event and see it in your app's log. You don't need an account with any analytics service yet: you start with Herald's log module, which prints each event instead of sending it. At the end you add Firebase.

Add the core library and the log module. The iOS SDK page lists all the modules.

In Xcode, File → Add Package Dependencies, add https://github.com/MkhytarMkhoian/herald-ios, and choose HeraldCore and HeraldLog. In a Package.swift:

.package(url: "https://github.com/MkhytarMkhoian/herald-ios", from: "1.3.0")

1. Describe what happened

An event is a small class in your app. It has a name, and parameters that describe what happened:

struct CheckoutStarted: Event, Equatable {
    let plan: String
    let seats: Int

    var name: String { "checkout_started" }
    var parameters: [String: AnalyticsValue] { ["plan": .string(plan), "seats": .int(seats)] }
}

Parameters keep their type. seats reaches every service as the number 3, not as the text "3", so you can still sum and filter by it there.

2. Create Herald

Herald is the object your app talks to. You give it the services to send to, and it passes every event on to each of them. Herald calls these services providers.

Here there's one provider, the log module. It has two parts: a tracker that handles events and user properties, and a service that handles everything else, such as start-up and sign-in.

// Where the log lines go: print fits as-is.
let logger: AnalyticsLogger = { message in print(message) }

// Handles events and user properties, using Herald's ready-made factories.
let logTracker = LogAnalyticsTrackerService(
    eventTrackerFactory: CompositeLogEventTrackerFactory([
        ScreenViewLogEventTrackerFactory(logger: logger),  // screen views
        GenericLogEventTrackerFactory(logger: logger),  // every other event
    ]),
    propertySetterFactory: GenericLogPropertySetterFactory(logger: logger)
)
// Handles the rest: start-up, sign-in and sign-out, consent.
let logService = LogAnalyticsService(logger: logger)

let herald = Herald(providers: [
    HeraldProvider(
        name: "log",
        events: logTracker,
        properties: logTracker,
        identity: logService,
        lifecycle: logService,
        consent: logService
    )
])

Create Herald once for the whole app. Set up your app shows how to share it.

Start it in your app delegate's application(_:didFinishLaunchingWithOptions:), where the vendors' own guides set up their SDKs. With SwiftUI, add the delegate with @UIApplicationDelegateAdaptor:

final class AppDelegate: NSObject, UIApplicationDelegate {
    let herald = makeHerald()

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
    ) -> Bool {
        FirebaseApp.configure()  // vendors set themselves up first, as their guides say
        herald.start()
        return true
    }
}

3. Track the event

Your classes don't use Herald directly. They ask for EventTrackerService, a small interface with a single track function, and you pass Herald in its place. That keeps them easy to test: in tests you pass a fake instead.

final class CheckoutViewModel {
    private let analytics: any EventTrackerService

    init(analytics: any EventTrackerService) {
        self.analytics = analytics
    }

    func onCheckout(plan: String, seats: Int) {
        analytics.track(CheckoutStarted(plan: plan, seats: seats))
    }
}

Call onCheckout(plan: "pro", seats: 3), and the log shows the event as a real service would receive it:

Xcode console

[herald] start
[herald] event   checkout_started
    ├─ plan  = pro
    └─ seats = 3

4. Add Firebase

First set up Firebase in your app the usual way, by following Firebase's guide for iOS. Then add Herald's Firebase module:

Add https://github.com/MkhytarMkhoian/herald-ios-firebase the same way, and choose HeraldFirebase:

.package(url: "https://github.com/MkhytarMkhoian/herald-ios-firebase", from: "1.3.0")

The Firebase provider is built the same way as the log one. Its factories send screen views as GA4's own screen_view event, and every other event under its own name:

func firebaseProvider() -> HeraldProvider {
    let tracker = FirebaseAnalyticsTrackerService(
        eventTrackerFactory: CompositeFirebaseEventTrackerFactory([
            ScreenViewFirebaseEventTrackerFactory(),  // GA4's reserved screen_view
            GenericFirebaseEventTrackerFactory(),  // everything else, as-is
        ]),
        propertySetterFactory: GenericFirebasePropertySetterFactory()
    )
    let service = FirebaseAnalyticsService()
    return HeraldProvider(
        name: "firebase",
        events: tracker,
        properties: tracker,
        identity: service,
        lifecycle: service,
        consent: service
    )
}

Add it to Herald next to the log provider:

let herald = Herald(providers: [
    HeraldProvider(
        name: "log",
        events: logTracker,
        properties: logTracker,
        identity: logService,
        lifecycle: logService,
        consent: logService
    ),
    firebaseProvider(),  // the new line
])

The same CheckoutStarted now goes to both the log and Firebase, and CheckoutViewModel didn't change at all.

Next

• Set up your app: several services, error reporting and dependency injection.
• iOS SDK: every module, and what's specific to iOS.
• SwiftUI: screen views and impressions from SwiftUI views.
• Philosophy: why Herald works the way it does.