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.
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.
https://github.com/Ferdinand99/KestrelKit
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.
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])
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
Bearercredential or atoken=…secret become[Filtered]. Keys such asiporuser_agentare 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.isEnabledisfalse, nothing is stored or sent. Turning it off deletes the queued signals and the install id, and the choice is remembered. Nothing is sent beforeconfigureeither. -
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.xcprivacydeclares 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.
// 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.