iOS & macOS SDKBeta

Native Swift SDK for Apple platforms with SwiftUI integration.

Requirements

iOS 15+macOS 12+tvOS 15+watchOS 8+Swift 5.9+

Installation

Add the SDK using Swift Package Manager.

Package.swift

// In Package.swift
dependencies: [
    .package(
        url: "https://github.com/himetrica/himetrica-swift",
        from: "1.0.0"
    )
]

Install with AI

Copy this prompt and paste it into ChatGPT, Claude, or any AI assistant to install the Swift SDK for you.

Install Himetrica analytics in my iOS/macOS Swift app using SwiftUI. Himetrica is a native Swift analytics SDK.

1. Add the Swift package dependency:
- URL: https://github.com/himetrica/himetrica-swift
- Version: from "1.0.0"

2. In your @main App struct, configure the SDK:
import Himetrica

@main
struct MyApp: App {
    init() {
        Himetrica.configure(apiKey: "YOUR_API_KEY")
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
                .himetricaLifecycle()
                .himetricaDeepLink()
        }
    }
}

3. Track screen views with the .trackScreen() modifier on any view:
.trackScreen("Home")

4. Track custom events:
Himetrica.shared.track("purchase_completed", properties: [
    "product_id": "pro_plan",
    "price": 9.99
])

5. Identify users after login:
Himetrica.shared.identify(
    userId: user.externalId,
    name: user.name,
    email: user.email,
    metadata: ["plan": user.subscriptionPlan]
)

The userId parameter is optional but enables cross-device visitor merging — when two visitors identify with the same userId, they are automatically merged into one.

The SDK supports iOS 15+, macOS 12+, tvOS 15+, watchOS 8+, and Swift 5.9+. It handles offline queuing, session management, and ATT compliance automatically.

Initialization

Configure the SDK in your app's entry point.

MyApp.swift

import SwiftUI
import Himetrica

@main
struct MyApp: App {
    init() {
        Himetrica.configure(apiKey: "YOUR_API_KEY")
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
                .himetricaLifecycle()  // Handle app lifecycle
                .himetricaDeepLink()   // Track deep links
        }
    }
}

View Modifiers

.himetricaLifecycle() \u2014 Handles app background/foreground events
.himetricaDeepLink() \u2014 Tracks deep link attribution

Screen Tracking

Track screen views with the .trackScreen() modifier.

swift

struct HomeView: View {
    var body: some View {
        NavigationStack {
            List {
                // Your content
            }
        }
        .trackScreen("Home")
    }
}

// With properties
struct ProductView: View {
    let product: Product

    var body: some View {
        ScrollView {
            // Your content
        }
        .trackScreen("Product Detail", properties: [
            "product_id": product.id,
            "category": product.category
        ])
    }
}

Screen duration is automatically tracked when users navigate away or the app goes to background.

Event Tracking

Track custom events and user interactions.

swift

// Track a custom event
Himetrica.shared.track("purchase_completed", properties: [
    "product_id": "pro_plan",
    "price": 9.99,
    "currency": "USD"
])

// Use TrackedButton for automatic tracking
TrackedButton("signup_clicked", title: "Sign Up") {
    performSignup()
}

// Or use trackOnTap modifier
Text("Learn More")
    .trackOnTap("learn_more_tapped")

TrackedButton

A convenience component that tracks events automatically.

swift

// Simple text button
TrackedButton("login_clicked", title: "Log In") {
    performLogin()
}

// With custom label
TrackedButton("signup_button_clicked") {
    performSignup()
} label: {
    HStack {
        Image(systemName: "person.badge.plus")
        Text("Sign Up")
    }
}

// With properties
TrackedButton("add_to_cart", properties: ["product_id": product.id]) {
    addToCart(product)
} label: {
    Text("Add to Cart")
}

User Identification

Associate analytics with a user after authentication.

swift

func onUserLogin(user: User) {
    Himetrica.shared.identify(
        userId: user.externalId,       // optional — stable external user ID
        name: user.name,
        email: user.email,
        metadata: [
            "plan": user.subscriptionPlan,
            "signup_date": user.createdAt.ISO8601Format(),
            "is_verified": user.isEmailVerified
        ]
    )
}

The userId parameter is optional but enables cross-device visitor merging. When two visitors identify with the same userId, they are automatically merged into one.

Deep Link Attribution

Track where users came from via deep links.

swift

ContentView()
    .himetricaDeepLink { url in
        // Handle the URL in your app
        router.navigate(to: url)
    }

Configuration

Full configuration options for the SDK.

swift

let config = HimetricaConfig(
    apiKey: "YOUR_API_KEY",
    apiUrl: "https://app.himetrica.com",  // Custom URL
    sessionTimeout: 30 * 60,               // 30 minutes
    autoTrackScreenViews: true,            // Auto-track navigation
    respectAdTracking: true,               // Respect ATT
    enableLogging: false,                  // Debug logging
    maxQueueSize: 1000,                    // Max offline queue
    flushInterval: 30                      // Flush interval (s)
)

Himetrica.configure(with: config)

Property	Default	Description
apiKey	required	Your Himetrica API key
sessionTimeout	1800	Session expiry in seconds (30 min)
respectAdTracking	true	Respect ATT settings
enableLogging	false	Enable debug logging
maxQueueSize	1000	Max queued events for offline
flushInterval	30	Queue flush interval in seconds

Debug Mode

Enable logging during development.

swift

#if DEBUG
let config = HimetricaConfig(
    apiKey: "YOUR_API_KEY",
    enableLogging: true
)
#else
let config = HimetricaConfig(apiKey: "YOUR_API_KEY")
#endif

Himetrica.configure(with: config)

Features

Offline Support

Events are persisted to disk and sent when connectivity is restored.

Session Management

Automatic session handling with configurable timeout.

Duration Tracking

Automatic time-on-screen measurement for each view.

ATT Compliance

Respects App Tracking Transparency settings by default.

API Reference

Method	Description
configure(apiKey:)	Initialize with API key
configure(with:)	Initialize with full config
trackScreen(name:properties:)	Track a screen view
track(_:properties:)	Track a custom event
identify(userId:name:email:metadata:)	Identify the current user. Pass userId for cross-device merging.
flush()	Force flush event queue
reset()	Clear all stored data

Also see

Web Tracker

Also see

Issue Tracking