iOS SDK

Track product usage, screen views, and user identity from iOS, macOS, tvOS, and watchOS apps using the official Ripples Swift SDK.

Install

Add the package via Swift Package Manager:

.package(url: "https://github.com/ripplesanalytics/ripples-ios", from: "0.1.6")

Or in Xcode: File → Add Package Dependencies and paste https://github.com/ripplesanalytics/ripples-ios.

Keys

Ripples projects have two identifiers. The iOS SDK takes the project token, never the secret key.

The project token is safe to bundle in a mobile or web app — revenue events submitted with the token are rejected server-side, so a scraped key can't forge MRR or LTV. Rotate it in project settings if you see abuse.

Quick start

Initialize once at app launch:

import Ripples

@main
struct MyApp: App {
    init() {
        Ripples.setup(RipplesConfig(projectToken: "YOUR-PROJECT-TOKEN"))
    }

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

Identify users

Call identify to associate the visitor with your internal user ID and update traits. Traits are cached and forwarded with every subsequent event automatically.

Ripples.shared.identify("user_123", traits: [
    "email": "[email protected]",
    "name":  "Jane Smith",
])

Parameters

Track product usage

Call track only for significant product usage — actions that prove a user got real value (created a budget, sent a message, invited a teammate). This is not a generic event log like PostHog or Mixpanel: do not send screen views, banner impressions, button taps, or "viewed X" events. Every track call feeds the Activation dashboard, so noise here pollutes your funnel. (Use screen(_:) / trackScreen for navigation — see below.)

// Group actions by product area
Ripples.shared.track("created a budget", area: "budgets")

// Mark THIS occurrence as the activation moment
Ripples.shared.track("added transaction", area: "transactions", properties: [
    "activated": true,
])

// area can also be passed inside properties — both forms are equivalent
Ripples.shared.track("exported report", properties: ["area": "reports"])

Keeping user data fresh

Pass userProperties alongside any event to upsert the user record without a separate identify call. This mirrors how PostHog handles $set — one request carries both the event and the trait update:

Ripples.shared.track("created a budget",
                     area: "budgets",
                     userProperties: ["plan": "pro", "company": "Acme"])

Traits from the last identify call are cached and forwarded automatically with every subsequent event, so you generally don't need to pass userProperties explicitly. Pass an empty dictionary [:] to suppress forwarding for a specific call.

Parameters

Track screen views

Screen views are stored as pageview events and appear in the Pages report alongside web pageviews. The first screen in each session is automatically flagged as the session entry.

Use the SwiftUI modifier — one line per screen:

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

// With area and extra properties
struct ListDetailView: View {
    let listId: String
    var body: some View {
        ScrollView { ... }
            .trackScreen("ListDetail", properties: ["area": "lists", "list_id": listId])
    }
}

Or call it imperatively (UIKit, custom navigation):

Ripples.shared.screen("Settings")
Ripples.shared.screen("ListDetail", area: "lists", properties: ["list_id": listId])

Flush manually

Events are batched in memory, persisted to disk, and flushed automatically on a timer, when the queue fills, and when the app enters background or terminates. Call flush explicitly before logout, account deletion, or any moment you want delivery to be attempted immediately:

Ripples.shared.flush { /* delivery attempted */ }

Automatic behaviour

Configuration

let config = RipplesConfig(projectToken: "YOUR-PROJECT-TOKEN")
config.host                 = "https://your-domain.com"  // self-hosted
config.flushIntervalSeconds = 30
config.flushAt              = 20
config.maxBatchSize         = 50
config.maxQueueSize         = 1000
config.requestTimeout       = 10
config.onError              = { error in print("Ripples error:", error) }
Ripples.setup(config)

Configuration options

Requirements

• Swift 5.5+
• iOS 13+, macOS 10.15+, tvOS 13+, watchOS 6+