KestrelKit
v0.1 · early release

How your app is used.
Not who uses it.

KestrelKit is a small Swift package that sends privacy-friendly usage signals, such as Paywall.shown, from your iOS or macOS app to your own Keen Kestrel.

No dependencies. No IDFA, no IDFV, no fingerprinting.

MIT licensedSwift 6Part of Keen Kestrel

Install

One package, nothing else.

In Xcode, choose File › Add Package Dependencies… and enter the repository URL, or add it to your Package.swift.

  • iOS 15
  • macOS 12
  • tvOS 15
  • watchOS 9
  • visionOS 1

Swift 6 with strict concurrency, and a privacy manifest included. Needs Keen Kestrel v0.2 or later, the first version with app analytics.

Xcode › Add Package Dependencies…
https://github.com/Ferdinand99/KestrelKit
Package.swift 0.1.0
dependencies: [
    .package(url: "https://github.com/Ferdinand99/KestrelKit", from: "0.1.0"),
],
targets: [
    .target(
        name: "MyApp",
        dependencies: [.product(name: "KestrelKit", package: "KestrelKit")]
    ),
]

Usage

Configure once. Send signals.

Give KestrelKit your Kestrel’s address and the project’s key: the 32 hex characters at the start of the project’s DSN, on its settings page in Kestrel.

Every call returns at once and is safe from any thread. Signals are sent every 30 seconds and when the app moves to the background; await Kestrel.flush() sends them right away. App.launched and Session.started are sent for you.

Kestrel.Configuration sets test mode, the flush interval, a default payload, the automatic signals and the size of the offline queue. The defaults suit most apps.

Quick start
import KestrelKit

Kestrel.configure(
    url: URL(string: "https://kestrel.example.com")!,
    key: "0123456789abcdef0123456789abcdef"
)

Kestrel.signal("Paywall.shown", payload: ["plan": "pro"])
Kestrel.signal("Export.finished", payload: ["pages": 12, "pdf": true])
SwiftUI
import SwiftUI
import KestrelKit

@main
struct MyApp: App {
    init() {
        Kestrel.configure(
            url: URL(string: "https://kestrel.example.com")!,
            key: "0123456789abcdef0123456789abcdef",
            configuration: .init(defaultPayload: ["theme": "dark"])
        )
    }

    var body: some Scene {
        WindowGroup { ContentView() }
    }
}

Privacy

Counts and trends, not profiles.

KestrelKit sends what a dashboard needs to count users, sessions, versions and devices, and nothing that says who someone is.

Never collected

  • The IDFA or the IDFV
  • The device name, the user’s name or email
  • Location or contacts
  • Cookies, or anything to fingerprint a device
  • IP addresses: Kestrel doesn’t store them

What a signal holds

  • Its type, your payload and the time it happened
  • A random install id: a UUID created once and kept in your app’s own defaults. Kestrel stores only a keyed hash of it.
  • A random session id, new at launch and after 5 minutes or more in the background
  • The app’s bundle id, version and build
  • Platform, OS version, hardware model (such as iPhone16,2) and locale
  • Three flags: debug build, TestFlight, simulator
  • Filtered on the device

    Values that look like an email, a phone or card number, an IP address, a Bearer credential or a token=… secret become [Filtered]. Keys such as ip or user_agent are dropped. Kestrel applies the same rules again.

  • Small payloads

    At most 20 keys of up to 40 characters, with values of up to 200. Signal types use A–Z a–z 0–9 . _ -; other characters become _.

  • An opt-out switch

    When Kestrel.isEnabled is false, nothing is stored or sent. Turning it off deletes the queued signals and the install id, and the choice is remembered. Nothing is sent before configure either.

  • Works offline

    Signals wait in a small queue file in Application Support, excluded from backups, and go out when the network is back. By default up to 5,000 are kept; the oldest go first.

  • Sent in batches

    Up to 100 signals or 256 KB a batch, gzipped when that makes it smaller. A busy or unreachable server gets a backoff from 30 seconds up to an hour, or its Retry-After.

  • A privacy manifest

    PrivacyInfo.xcprivacy declares no tracking, and product interaction and a device id (the install id) used for analytics and not linked to the user.

How it fits

Usage from KestrelKit. Crashes from Sentry’s SDK.

KestrelKit sends app signals to the App tab of Keen Kestrel, the self-hosted error tracker and analytics tool. It doesn’t report crashes: for those, keep the official Sentry SDK and point its DSN at the same Kestrel project.

The key is the same in both, so one project gets errors and analytics. The wire format is in the signals protocol.

One Kestrel project, two SDKs
// Crashes: the official Sentry SDK, with the project’s DSN
SentrySDK.start { options in
    options.dsn = "https://0123456789abcdef0123456789abcdef@kestrel.example.com/1"
}

// Usage: KestrelKit, with the key from the same DSN
Kestrel.configure(
    url: URL(string: "https://kestrel.example.com")!,
    key: "0123456789abcdef0123456789abcdef"
)

Test signals stay out of the way Signals from debug builds are sent with a debug flag, and Kestrel leaves them out of its dashboards unless you include test signals.