Fastest and only macOS Dictation app with on-device STT and custom trained AI enhancement model. Windows, iOS testflight! Android, Linux waitlist open! A local Wispr Flow alternative. Follow https://x.com/fluidvoiceapp for more
import Foundation
/// Typed API for low-volume analytics.
final class AnalyticsService {
static let shared = AnalyticsService()
private let detailedConsentGate: DetailedAnalyticsConsentGate
private let core: AnalyticsCore
private init() {
let detailedConsentGate = DetailedAnalyticsConsentGate()
self.detailedConsentGate = detailedConsentGate
self.core = AnalyticsCore(detailedConsentGate: detailedConsentGate)
}
func bootstrap() {
self.submit { core, context in
await core.bootstrap(context: context)
}
}
func setDetailedAnalyticsEnabled(_ enabled: Bool) {
let consentGeneration = self.detailedConsentGate.advance()
let context = Self.context(
detailedAnalyticsEnabled: enabled,
detailedConsentGeneration: consentGeneration
)
Task.detached(priority: .background) { [core] in
await core.setDetailedAnalyticsEnabled(context: context)
}
}
/// Records one active-user event per local day.
func recordAppActivity() {
self.submit { core, context in
await core.recordActivity(.app, context: context)
}
}
/// Counts accepted usage and attempted AI requests.
func recordUsage(
mode: AnalyticsUsageMode,
transcriptionModel: AnalyticsModelDescriptor? = nil,
aiModel: AnalyticsModelDescriptor? = nil
) {
self.submit { core, context in
await core.recordUsage(
mode: mode,
transcriptionModel: transcriptionModel,
aiModel: aiModel,
context: context
)
}
}
func recordModelUsage(
role: AnalyticsModelRole,
mode: AnalyticsUsageMode,
descriptor: AnalyticsModelDescriptor
) {
self.submit { core, context in
await core.recordModelUsage(role: role, mode: mode, descriptor: descriptor, context: context)
}
}
/// Beta builds aggregate Fluid Intelligence throughput locally and emit one summary per day.
func recordBetaDictationPerformance(
fluidModel: AnalyticsFluidIntelligenceModel?,
tokensPerSecond: Double?
) {
self.submit { core, context in
await core.recordBetaDictationPerformance(
fluidModel: fluidModel,
tokensPerSecond: tokensPerSecond,
context: context
)
}
}
func recordInsertionLatency(
path: AnalyticsInsertionPath,
outcome: AnalyticsInsertionOutcome,
requestMilliseconds: Int,
readyMilliseconds: Int?,
toggleStopMilliseconds: Int?
) {
self.submit { core, context in
await core.recordInsertionLatency(
path: path,
outcome: outcome,
requestMilliseconds: requestMilliseconds,
readyMilliseconds: readyMilliseconds,
toggleStopMilliseconds: toggleStopMilliseconds,
context: context
)
}
}
func recordOnboardingStarted(origin: AnalyticsOnboardingOrigin) {
self.submit { core, context in
await core.recordOnboardingStarted(origin: origin, context: context)
}
}
func recordOnboardingStepViewed(_ step: AnalyticsOnboardingStep, origin: AnalyticsOnboardingOrigin) {
self.submit { core, context in
await core.recordOnboardingStepViewed(step, origin: origin, context: context)
}
}
func recordOnboardingStepCompleted(
_ step: AnalyticsOnboardingStep,
outcome: AnalyticsOnboardingOutcome,
origin: AnalyticsOnboardingOrigin,
completesFlow: Bool = false
) {
self.submit { core, context in
await core.recordOnboardingStepCompleted(
step,
outcome: outcome,
origin: origin,
completesFlow: completesFlow,
context: context
)
}
}
func recordOnboardingTryoutAttemptStarted(startMethod: AnalyticsOnboardingTryoutStartMethod) {
let origin = SettingsStore.shared.analyticsOnboardingOrigin
self.submit { core, context in
await core.recordOnboardingTryoutAttemptStarted(
startMethod: startMethod,
origin: origin,
context: context
)
}
}
func recordOnboardingTryoutAttemptResult(
outcome: AnalyticsOnboardingTryoutOutcome,
failureStage: AnalyticsOnboardingTryoutFailureStage? = nil
) {
let origin = SettingsStore.shared.analyticsOnboardingOrigin
self.submit { core, context in
await core.recordOnboardingTryoutAttemptResult(
outcome: outcome,
failureStage: failureStage,
origin: origin,
context: context
)
}
}
func finishOnboardingTryout(
outcome: AnalyticsOnboardingTryoutOutcome,
failureStage: AnalyticsOnboardingTryoutFailureStage? = nil
) {
let origin = SettingsStore.shared.analyticsOnboardingOrigin
self.submit { core, context in
await core.finishOnboardingTryout(
outcome: outcome,
failureStage: failureStage,
origin: origin,
context: context
)
}
}
func skipOnboardingTryout(origin: AnalyticsOnboardingOrigin) {
self.submit { core, context in
await core.skipOnboardingTryout(origin: origin, context: context)
}
}
func recordModelDownloadStarted(
id: UUID,
descriptor: AnalyticsModelDescriptor,
source: AnalyticsModelDownloadSource
) {
self.submit { core, context in
await core.recordModelDownloadStarted(
id: id.uuidString.lowercased(),
descriptor: descriptor,
source: source,
context: context
)
}
}
func recordModelDownloadFinished(
id: UUID,
descriptor: AnalyticsModelDescriptor,
source: AnalyticsModelDownloadSource,
outcome: AnalyticsModelDownloadOutcome,
duration: TimeInterval?
) {
self.submit { core, context in
await core.recordModelDownloadFinished(
id: id.uuidString.lowercased(),
descriptor: descriptor,
source: source,
outcome: outcome,
duration: duration,
context: context
)
}
}
private func submit(
_ operation: @escaping @Sendable (AnalyticsCore, AnalyticsContext) async -> Void
) {
let context = Self.context(
detailedAnalyticsEnabled: SettingsStore.shared.shareDetailedAnalytics,
detailedConsentGeneration: self.detailedConsentGate.currentGeneration
)
Task.detached(priority: .background) { [core] in
await operation(core, context)
}
}
private static func context(
detailedAnalyticsEnabled: Bool,
detailedConsentGeneration: UInt64
) -> AnalyticsContext {
let version = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String ?? "unknown"
return AnalyticsContext(
detailedAnalyticsEnabled: detailedAnalyticsEnabled,
detailedConsentGeneration: detailedConsentGeneration,
config: AnalyticsConfig.fromBundle(),
distinctID: AnalyticsIdentityStore.shared.anonymousInstallID,
appVersion: version,
collectsBetaPerformance: AnalyticsBuildPolicy
.automaticallyCollectsDictationPerformance(appVersion: version)
)
}
}
private struct AnalyticsContext {
let detailedAnalyticsEnabled: Bool
let detailedConsentGeneration: UInt64
let config: AnalyticsConfig
let distinctID: String
let appVersion: String
let collectsBetaPerformance: Bool
}
final nonisolated class DetailedAnalyticsConsentGate: @unchecked Sendable {
private let lock = NSLock()
private var generation: UInt64 = 0
var currentGeneration: UInt64 {
self.lock.withLock { self.generation }
}
func advance() -> UInt64 {
self.lock.withLock {
self.generation &+= 1
return self.generation
}
}
func accepts(_ generation: UInt64) -> Bool {
self.lock.withLock { generation == self.generation }
}
}
private actor AnalyticsCore {
private var context: AnalyticsContext?
private let detailedConsentGate: DetailedAnalyticsConsentGate
private var database: AnalyticsDatabase?
private var flushTask: Task<Void, Never>?
private var activeUploadTask: Task<Int, Error>?
private var isFlushing = false
private let batchSize = 50
init(detailedConsentGate: DetailedAnalyticsConsentGate) {
self.detailedConsentGate = detailedConsentGate
}
func bootstrap(context: AnalyticsContext) async {
guard self.apply(context) else { return }
do {
if !context.detailedAnalyticsEnabled {
try self.purgeStoredDetailedAnalyticsIfPresent(context: context)
}
guard context.config.isConfigured else { return }
let database = try self.database(for: context)
try database.finalizeDays(before: Date())
if context.detailedAnalyticsEnabled {
try database.recoverInterruptedModelDownloads(at: Date())
}
self.startFlushLoopIfNeeded()
await self.flushIfNeeded()
} catch {
self.stopFlushLoop()
}
}
func setDetailedAnalyticsEnabled(context: AnalyticsContext) async {
guard self.apply(context) else { return }
self.activeUploadTask?.cancel()
self.stopFlushLoop()
await self.bootstrap(context: context)
}
func recordActivity(_ kind: AnalyticsActivityKind, context: AnalyticsContext) async {
await self.writeActivity(context: context) { database, date in
try database.recordActivity(kind, at: date)
}
}
func recordUsage(
mode: AnalyticsUsageMode,
transcriptionModel: AnalyticsModelDescriptor?,
aiModel: AnalyticsModelDescriptor?,
context: AnalyticsContext
) async {
await self.writeDetailed(context: context, fallbackActivity: .coreAction) { database, date in
try database.recordUsage(
mode: mode,
transcriptionModel: transcriptionModel,
aiModel: aiModel,
at: date
)
}
}
func recordModelUsage(
role: AnalyticsModelRole,
mode: AnalyticsUsageMode,
descriptor: AnalyticsModelDescriptor,
context: AnalyticsContext
) async {
await self.writeDetailed(context: context, fallbackActivity: .coreAction) { database, date in
try database.recordModelUsage(role: role, mode: mode, descriptor: descriptor, at: date)
}
}
func recordBetaDictationPerformance(
fluidModel: AnalyticsFluidIntelligenceModel?,
tokensPerSecond: Double?,
context: AnalyticsContext
) async {
guard context.collectsBetaPerformance,
context.config.isConfigured
else { return }
do {
let database = try self.database(for: context)
try database.recordDictationPerformance(
fluidModel: fluidModel,
tokensPerSecond: tokensPerSecond,
measuredAppVersion: context.appVersion,
at: Date()
)
self.startFlushLoopIfNeeded()
} catch {
return
}
}
func recordInsertionLatency(
path: AnalyticsInsertionPath,
outcome: AnalyticsInsertionOutcome,
requestMilliseconds: Int,
readyMilliseconds: Int?,
toggleStopMilliseconds: Int?,
context: AnalyticsContext
) async {
await self.writeDetailed(context: context) { database, date in
try database.recordInsertionLatency(
path: path,
outcome: outcome,
requestMilliseconds: requestMilliseconds,
readyMilliseconds: readyMilliseconds,
toggleStopMilliseconds: toggleStopMilliseconds,
at: date
)
}
}
func recordOnboardingStarted(origin: AnalyticsOnboardingOrigin, context: AnalyticsContext) async {
await self.writeDetailed(context: context, fallbackActivity: .app) { database, date in
try database.recordOnboardingStarted(origin: origin, at: date)
}
}
func recordOnboardingStepViewed(
_ step: AnalyticsOnboardingStep,
origin: AnalyticsOnboardingOrigin,
context: AnalyticsContext
) async {
await self.writeDetailed(context: context) { database, date in
try database.recordOnboardingStepViewed(step, origin: origin, at: date)
}
}
func recordOnboardingStepCompleted(
_ step: AnalyticsOnboardingStep,
outcome: AnalyticsOnboardingOutcome,
origin: AnalyticsOnboardingOrigin,
completesFlow: Bool,
context: AnalyticsContext
) async {
await self.writeDetailed(context: context) { database, date in
try database.recordOnboardingStepCompleted(
step,
outcome: outcome,
origin: origin,
completesFlow: completesFlow,
at: date
)
}
}
func recordOnboardingTryoutAttemptStarted(
startMethod: AnalyticsOnboardingTryoutStartMethod,
origin: AnalyticsOnboardingOrigin,
context: AnalyticsContext
) async {
await self.writeDetailed(context: context) { database, date in
try database.recordOnboardingTryoutAttemptStarted(
startMethod: startMethod,
origin: origin,
at: date
)
}
}
func recordOnboardingTryoutAttemptResult(
outcome: AnalyticsOnboardingTryoutOutcome,
failureStage: AnalyticsOnboardingTryoutFailureStage?,
origin: AnalyticsOnboardingOrigin,
context: AnalyticsContext
) async {
await self.writeDetailed(context: context) { database, date in
try database.recordOnboardingTryoutAttemptResult(
outcome: outcome,
failureStage: failureStage,
origin: origin,
at: date
)
}
}
func finishOnboardingTryout(
outcome: AnalyticsOnboardingTryoutOutcome,
failureStage: AnalyticsOnboardingTryoutFailureStage?,
origin: AnalyticsOnboardingOrigin,
context: AnalyticsContext
) async {
await self.writeDetailed(context: context) { database, date in
try database.finishOnboardingTryout(
outcome: outcome,
failureStage: failureStage,
origin: origin,
at: date
)
}
}
func skipOnboardingTryout(origin: AnalyticsOnboardingOrigin, context: AnalyticsContext) async {
await self.writeDetailed(context: context) { database, date in
try database.skipOnboardingTryout(origin: origin, at: date)
}
}
func recordModelDownloadStarted(
id: String,
descriptor: AnalyticsModelDescriptor,
source: AnalyticsModelDownloadSource,
context: AnalyticsContext
) async {
await self.writeDetailed(context: context, fallbackActivity: .coreAction) { database, date in
try database.recordModelDownloadStarted(id: id, descriptor: descriptor, source: source, at: date)
}
}
func recordModelDownloadFinished(
id: String,
descriptor: AnalyticsModelDescriptor,
source: AnalyticsModelDownloadSource,
outcome: AnalyticsModelDownloadOutcome,
duration: TimeInterval?,
context: AnalyticsContext
) async {
await self.writeDetailed(context: context) { database, date in
try database.recordModelDownloadFinished(
id: id,
descriptor: descriptor,
source: source,
outcome: outcome,
duration: duration,
at: date
)
}
}
private func writeActivity(
context: AnalyticsContext,
operation: (AnalyticsDatabase, Date) throws -> Void
) async {
guard context.config.isConfigured else { return }
do {
let database = try self.database(for: context)
try operation(database, Date())
self.startFlushLoopIfNeeded()
} catch {
return
}
}
private func writeDetailed(
context: AnalyticsContext,
fallbackActivity: AnalyticsActivityKind? = nil,
operation: (AnalyticsDatabase, Date) throws -> Void
) async {
let mayRecordDetails = self.apply(context) && context.detailedAnalyticsEnabled
guard context.config.isConfigured else { return }
guard mayRecordDetails || fallbackActivity != nil else { return }
do {
let database = try self.database(for: context)
let date = Date()
if mayRecordDetails {
try operation(database, date)
} else if let fallbackActivity {
try database.recordActivity(fallbackActivity, at: date)
}
self.startFlushLoopIfNeeded()
} catch {
return
}
}
private func apply(_ context: AnalyticsContext) -> Bool {
guard self.detailedConsentGate.accepts(context.detailedConsentGeneration) else { return false }
self.context = context
return true
}
private func database(for context: AnalyticsContext) throws -> AnalyticsDatabase {
if let database { return database }
let url = try self.databaseURL()
let database = try AnalyticsDatabase(
url: url,
distinctID: context.distinctID,
appVersion: context.appVersion
)
self.database = database
return database
}
private func databaseURL() throws -> URL {
let applicationSupport = try FileManager.default.url(
for: .applicationSupportDirectory,
in: .userDomainMask,
appropriateFor: nil,
create: true
)
let directoryName = Bundle.main.bundleIdentifier ?? "FluidVoice"
return applicationSupport
.appendingPathComponent(directoryName, isDirectory: true)
.appendingPathComponent("Analytics", isDirectory: true)
.appendingPathComponent("analytics-v2.sqlite3")
}
private func purgeStoredDetailedAnalyticsIfPresent(context: AnalyticsContext) throws {
if let database {
try database.purgeDetailedAnalytics()
return
}
let url = try self.databaseURL()
guard FileManager.default.fileExists(atPath: url.path) else { return }
let existingDatabase = try AnalyticsDatabase(
url: url,
distinctID: context.distinctID,
appVersion: context.appVersion
)
try existingDatabase.purgeDetailedAnalytics()
}
private func startFlushLoopIfNeeded() {
guard self.flushTask == nil,
let context,
self.detailedConsentGate.accepts(context.detailedConsentGeneration),
context.config.isConfigured
else { return }
self.flushTask = Task { [weak self] in
while !Task.isCancelled {
try? await Task.sleep(for: .seconds(30))
guard !Task.isCancelled else { return }
await self?.flushIfNeeded()
}
}
}
private func stopFlushLoop() {
self.flushTask?.cancel()
self.flushTask = nil
}
private func flushIfNeeded() async {
guard !self.isFlushing,
let context,
self.detailedConsentGate.accepts(context.detailedConsentGeneration),
context.config.isConfigured,
let database
else { return }
self.isFlushing = true
defer {
self.activeUploadTask = nil
self.isFlushing = false
}
let items: [AnalyticsOutboxItem]
do {
try database.finalizeDays(before: Date())
items = try database.readyOutbox(limit: self.batchSize, at: Date())
} catch {
return
}
guard !items.isEmpty else { return }
guard self.detailedConsentGate.accepts(context.detailedConsentGeneration) else { return }
let ids = items.map(\.id)
let uploadTask = Task {
guard self.detailedConsentGate.accepts(context.detailedConsentGeneration) else {
throw CancellationError()
}
return try await self.send(items: items, config: context.config)
}
self.activeUploadTask = uploadTask
let status: Int
do {
status = try await uploadTask.value
} catch {
guard self.detailedConsentGate.accepts(context.detailedConsentGeneration) else { return }
try? database.retry(ids: ids, at: Date())
return
}
guard self.detailedConsentGate.accepts(context.detailedConsentGeneration) else { return }
switch status {
case 200..<300:
try? database.acknowledgeUploaded(ids: ids, at: Date())
case 408, 429, 500...599:
try? database.retry(ids: ids, at: Date())
default:
try? database.discardPermanently(ids: ids)
}
}
private func send(items: [AnalyticsOutboxItem], config: AnalyticsConfig) async throws -> Int {
guard let url = URL(string: config.postHogHost)?.appendingPathComponent("batch") else {
throw URLError(.badURL)
}
let batch = try items.map { item -> Any in
try JSONSerialization.jsonObject(with: item.payload)
}
let body: [String: Any] = ["api_key": config.postHogApiKey, "batch": batch]
let data = try JSONSerialization.data(withJSONObject: body)
var request = URLRequest(url: url)
request.httpMethod = "POST"
request.httpBody = data
request.timeoutInterval = 10
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
let (_, response) = try await URLSession.shared.data(for: request)
guard let httpResponse = response as? HTTPURLResponse else {
throw URLError(.badServerResponse)
}
return httpResponse.statusCode
}
}