Fire the call right after the platform billing API confirms the trial transaction. Avoid passing the trial duration, the plan ID, or the payment-method type — your billing vendor (App Store Connect, Google Play, Stripe, RevenueCat) already has all of those with authoritative timestamps.
▸Install the Swift (iOS) SDK
// Package.swift
dependencies: [
.package(url: "https://github.com/respectlytics/respectlytics-swift.git", from: "3.0.0")
]
// Or via Xcode → File → Add Packages → paste the URL above.The SDK ships only via Swift Package Manager. CocoaPods and Carthage are not published — fewer integration paths means fewer surfaces to keep audited.
▸Initialize Respectlytics in Swift (iOS)
import Respectlytics
@main
struct MyApp: App {
init() {
Respectlytics.configure(appKey: "<YOUR_APP_KEY>")
}
var body: some Scene { WindowGroup { ContentView() } }
}Call configure once at app launch — typically in your App struct's init. No Info.plist keys are required: the SDK does not call ATTrackingManager and does not request the IDFA, so NSUserTrackingUsageDescription should NOT be added.
▸Track the event in Swift (iOS)
import Respectlytics
import StoreKit
// In your StoreKit 2 trial purchase handler:
Task {
let result = try await product.purchase()
if case .success(let verification) = result,
case .verified(let transaction) = verification,
transaction.offerType == .introductory {
Respectlytics.track("trial_start")
await transaction.finish()
}
}offerType == .introductory distinguishes trial purchases from regular purchases. Don't pass plan ID, trial duration, or price.
✦Privacy & implementation notes
Your billing system (App Store Connect, Google Play Billing, RevenueCat, Stripe) is the system of record for plan IDs, durations, payment methods, and renewal states. Duplicating that data into your analytics pipeline produces two truths that drift over time. The Respectlytics 5-field schema simply refuses the duplication — by design.
Cohort retention curves ("of the trials started in March, what % were paying in May?") are most accurately computed against your billing data, not your product analytics. Respectlytics tells you product engagement; your billing system tells you revenue truth. Keep them separate.
Apple rejected approximately 3% of apps in 2024 for incorrectly omitting NSUserTrackingUsageDescription when ATT was required by the SDKs they shipped. Respectlytics doesn't trigger ATT. The corollary is also true: do not add the key on Respectlytics's account — its presence implies you track across apps, even if your code never calls requestTrackingAuthorization.
Internally the Swift SDK uses Swift Concurrency: events are queued in an actor-isolated buffer (RAM-only), flushed on a 30-second timer and on UIApplication.willResignActiveNotification. Force-quit before flush drops queued events — by design. There is no UserDefaults or file backing.
⇋How this compares to other analytics SDKs
| Trial start event | Firebase Analytics | Mixpanel | Respectlytics |
|---|---|---|---|
| Per-user identity | app_instance_id + user_id | distinct_id | Never |
| Plan ID / trial duration | Recommended | Recommended | Rejected by API |
| Payment method type | Recommended | Recommended | Rejected by API |
| Trial-to-paid attribution | Per-user | Per-user (Identity Merging) | Session-scoped or via billing system |
| Cohort retention curve | Per-user | Per-user | Out of scope (use billing data) |
❓Frequently asked questions
How do we compute trial-to-paid conversion rate?
Either by session (a session that emits trial_start and later trial_conversion is converting), or — for the authoritative number — by querying your billing system. Most boards want the billing-system number for revenue, and the session-rate number for product diagnosis.
What about distinguishing 7-day vs 14-day trial cohorts?
If you offer multiple trial lengths, emit distinct event names: trial_start_7d, trial_start_14d. The aggregation gives you per-cohort conversion rate. Don't pass the duration as a parameter — the API rejects it.
Should we tag the source (organic / paid / referral)?
Distinct event names per source — trial_start_organic, trial_start_paid. Keep to your top 3–5 sources; bucket the rest as trial_start_other.
When do we fire — at button tap, or at billing confirmation?
At billing confirmation. Tap-fire produces inflated numbers when users abandon the platform billing prompt; confirmation-fire produces the truthful trial-start rate. The few extra seconds of wait are worth a non-noisy metric.