BuzzKit iOS SDK

Push notifications for iOS, with no backend code

Read the docs »

Installation · Configure · Identify · Push · Preferences · Contributing

Introduction

This is the native Swift SDK for BuzzKit, the open source notification orchestration layer. It handles identity, events, push registration, notification preferences, deep links, remote actions and workflow-scheduled local notifications, so you can add the full notification stack to an iOS app without building more backend infrastructure.

import BuzzKit

// Once, at launch. The client key is public and safe to ship.
BuzzKit.configure(apiKey: "bk_pk_…")

// At login. Everything tracked before this carries over to the user.
BuzzKit.identify("user_42")

// Permission, device token, environment and registration in one call.
let granted = try await BuzzKit.registerForPush()

// Events drive segments and workflows. Written to disk first, so they survive offline.
BuzzKit.track("workout.completed", data: ["duration": 42])

Once configured, the SDK keeps each user, device and preference in sync while you manage messages, segments, topics and workflows from the dashboard.

Installation

Add the package in Xcode (File → Add Package Dependencies) or in Package.swift:

.package(url: "https://github.com/buzzkit-dev/buzzkit-ios", from: "1.0.0")

The package provides three products:

Product	Add to	What it does
BuzzKit	the app	The SDK: identity, events, push, preferences, deep links
BuzzKitUI	the app	BuzzKitPreferencesView, the drop-in settings screen
BuzzKitNotificationServiceExtension	a notification service extension target	Rich media and delivered receipts

Configure

@main
struct GymApp: App {
    init() {
        BuzzKit.configure(with: BuzzKit.Configuration(
            apiKey: "bk_pk_…",
            appGroup: "group.com.example.gym"
        ))
    }
    …
}

The client key comes from the dashboard's API keys page and is safe to ship in the binary. Self-hosted installations can point apiURL at their own deployment. The app group is shared with the notification service extension so delivered receipts survive its short lifetime.

Identify and track

Every user starts with a stable anonymous id on first launch, and anything tracked before login carries over when they identify.

BuzzKit.identify("user_42", email: "ada@example.com", identityHash: hash)
BuzzKit.setAttributes(["plan": "pro", "streak": 4])
BuzzKit.track("workout.completed", data: ["duration": 42])
BuzzKit.logout()

Events are written to disk before reaching the network, then batched and retried so tracking continues to work offline. The queue flushes on launch, in the background and whenever the app reconnects, and only removes a batch after the server acknowledges it. An identityHash generated by your backend proves that the user may claim the given id. Email is stored on the subscriber and automatically subscribed when the tenant has an email provider; pass subscribe: [.email: false] to keep the address on file without subscribing it. Read more about identity and events.

Push

let granted = try await BuzzKit.registerForPush()

This one call handles the permission prompt, device token, environment detection and subscription registration. Debug builds and simulators use the APNs sandbox, while release builds use production. The SDK handles the app delegate's token callbacks automatically, or you can set Configuration.automaticPushHandling to false and forward them yourself. Foreground notifications appear as banners by default and can be changed per notification through BuzzKitDelegate. Read more about push.

Deep links and remote actions

A message created in the dashboard can carry a deep link or name an action; the SDK routes both when the notification is opened.

BuzzKit.onDeepLink { url in router.open(url) }
BuzzKit.actions.register("show_offer") { action in
    paywall.present(offerId: action.data["offerId"])
}

Unhandled deep links fall through to the system. Read more about deep links and actions.

Preferences

BuzzKitPreferencesView()                            // the whole settings screen
let topics = try await BuzzKit.preferences.all()    // or build your own UI
try await BuzzKit.preferences.set("gym-reminders", enabled: false)

The default screen loads the user's topics with a toggle for each one, while a custom row builder gives you complete control over its appearance. Read more about preferences.

Live Activities

BuzzKit.activities.monitor(activity)                     // keeps tokens registered
BuzzKit.activities.enablePushToStart(for: MatchAttributes.self)

Start, update and end Live Activities from the dashboard or API while the SDK handles their token lifecycle. Read more about Live Activities.

Rich media and receipts

Add a notification service extension target with one line of code:

final class NotificationService: BuzzKitNotificationService {
    override var buzzKitAppGroup: String? { "group.com.example.gym" }
}

The extension attaches images to notifications and reports each delivery as a $notification.delivered event; notification opens are reported as $notification.opened. Read more about the notification service extension.

Local notifications from workflows

A workflow step with deliver: "local" sends a silent push that schedules the notification on the device, allowing it to fire on time even in airplane mode and cancel itself when the user completes the action it was prompting. The SDK handles the implementation. Read more about local notifications.

Requirements

• iOS 15+ (BuzzKitUI: iOS 15+, Mac Catalyst 15+)
• Swift 6 toolchain (the package builds with strict concurrency)

Documentation

Find our full documentation here.

Contributing

BuzzKit is still in beta, so we're being careful about what goes in. While that's the case, pull requests are limited to the core contributors, and the best way to help is through issues. Bug reports and feature ideas are always welcome, and we read every one.

• Report a bug
• Propose a feature

License

The BuzzKit iOS SDK is licensed under the MIT License.