GrowthScope iOS SDK

AI-first growth product. Lightweight event tracking that pipes straight into a CLI-driven analytics platform — so a growth Agent (Claude, Cursor, your own scripts) can analyze your product alongside you, every day.

Part of the GrowthScope platform — Cursor 之于代码 = GrowthScope 之于增长.

---

🎯 What is this and who is it for

GrowthScope rethinks product analytics from the ground up for the AI agent era.

Old tools (Mixpanel / Amplitude / PostHog):

• Dashboard-first → humans stare at charts → growth insight is bottlenecked by who has time to open the browser
• SDKs are heavy, configured once, then forgotten

GrowthScope:

• AI-first. All data is consumed via CLI / Skills / scripts — designed for Agents to operate, not humans to navigate
• A growth Agent works alongside you. Ask Claude "MusePod 这周哪里最该优化？" → it queries via growth --json funnel ... → answers with data + suggests experiments
• No dashboard. No "we'll get to it next sprint." You get insights anywhere you have a terminal

This SDK is the first piece: a 2.5KB Swift Package that gets your events into the platform so the Agent has data to analyze.

---

Why this SDK

• 2.5KB compiled — minimal footprint, no transitive dependencies
• Fire-and-forget — never blocks UI, never crashes the host
• Offline-resilient — UserDefaults queue, batches retry when network returns
• Multi-tenant — appId is required, run same SDK across many products
• Privacy-respecting — IDFV-based device ID (resets on uninstall), no IDFA, no SDK-initiated background activity

Install (Swift Package Manager)

In Xcode: File → Add Package Dependencies → enter:

https://github.com/zerolong0/growthscope-ios

Or in Package.swift:

.package(url: "https://github.com/zerolong0/growthscope-ios", from: "0.1.0"),

Usage

1. Configure once at app startup

import GrowthScope

@main
struct MyApp: App {
    init() {
        GrowthScope.configure(
            appId: "myapp",
            endpoint: "https://myapp.com/api/growthscope/v1"
        )
    }
}

2. Track events anywhere

GrowthScope.shared.track("podcast_create_start", [
    "mode": "websearch",
    "language": "zh",
])

GrowthScope.shared.track("podcast_listen_75", [
    "podcastId": podcast.id,
    "duration": player.duration,
])

3. Identify your users

GrowthScope.shared.identify(userId: user.uuid, traits: [
    "plan": "free",
])

// On logout
GrowthScope.shared.reset()

4. Have the Agent analyze your data

After events flow:

# In your terminal, ask the Agent:
$ growth ask "本周我的 podcast_listen_75 转化下降了吗？什么时候开始的？"

Or use a Claude Skill like growth-funnel-debug that auto-correlates the drop with recent git commits in your repo.

---

Architecture

Your iOS app
    │
    ├── GrowthScope.shared.track(...)   ← fire-and-forget
    │     │
    │     ├── enqueue → UserDefaults    ← survives crashes / offline
    │     └── flush (background queue)
    │             │
    │             └── POST {endpoint}/track  ← batch up to 50
    │
GrowthScope server (your own, co-located with app)
    └── Postgres
        │
        ├── CLI:    growth events myapp --tail
        ├── Skill:  growth-funnel-debug → "why drop?" → reads git + correlates
        └── Agent:  Claude/Cursor reads structured JSON output

Configuration knobs

Knob	Default	Notes
Queue max	500 events	Drops oldest when full
Batch size	50 events	Per POST
Network timeout	15s	Drops batch, retries next flush
Device ID	IDFV	Persists across reinstalls until iCloud restore

What gets sent automatically

• app_open — when configure() is called
• That's it. No background polls, no auto screen views, no silent metadata collection.

Everything else is explicit track() calls in your code.

Privacy

• ✅ No IDFA
• ✅ No location
• ✅ No ATT prompt needed (no tracking across apps)
• ✅ Property values are caller-controlled — you decide what to send
• Add to your PrivacyInfo.xcprivacy:
  • NSPrivacyTracking: false (unless you choose to)
  • Required reason API: CA92.1 for UserDefaults (queue persistence)

Sister projects

• 🟢 growthscope — server + Claude Skills (umbrella, the AI Agent runtime)
• 🟢 growthscope-cli — growth CLI for querying data
• 🟢 growthscope-web — Web SDK with same API surface

License

MIT © 2026 zerolong0