Skip to Content
iOS SDK

iOS SDK

Add live in-app micro-surveys to your iOS app. The SDK fetches your published survey config, listens to your analytics events, evaluates triggers locally, and presents the right survey at the right time — with no per-survey host code.

Beta. The SDK is in active dogfooding. Build it in Xcode (a recent Xcode is required for the native survey UI). APIs below are stable for MVP; expect small changes as the package is hardened.

Requirements

  • iOS 15+ (self-sizing sheet uses iOS 16+ APIs, with a graceful fallback).
  • Swift Package Manager.
  • Optional but recommended: Amplitude-Swift in your app, so events and identity flow in automatically.

1. Add the package

// In your app's Package.swift, or Xcode → File → Add Package → Add Local…
.package(path: "../MicroSurveysSDK/sdk-ios")

Add MicroSurveysSDK to your target’s dependencies. The package links Amplitude-Swift; the Amplitude integration is conditionally compiled, so apps without Amplitude still build and can drive the SDK manually.

2. Wire it up — the three lines

import MicroSurveysSDK
import AmplitudeSwift
 
let ms = MicroSurveysSDK(apiKey: "ms_live_xxx")   // your project's public API key
amplitude.add(plugin: ms.amplitudePlugin())        // forward events + identity
ms.start()                                          // fetch config + flush outbox
  • amplitudePlugin() returns an enrichment plugin that reads every tracked event and keeps an identity snapshot fresh. It returns each event unmodified — a pure pass-through that never drops or alters your analytics.
  • start() loads the cached config immediately (so surveys work offline and on first frame), flushes any impressions/responses queued from a previous offline session, and refreshes config from the network (ETag-aware). The SDK also auto-refreshes config on app-foreground, throttled to once per 12 hours.

3. Optional configuration

Non-Amplitude hosts / extra context

ms.setUser(id: "user-123", properties: ["plan": "pro"])   // identity + audience props
ms.track("booking_completed", properties: ["amount": 42]) // manual trigger event

track(...) feeds the same trigger engine as the Amplitude plugin, so you can use either or both.

Control where surveys appear

ms.presentationAnchor = { myTopViewController }  // defaults to the active scene's top VC

Theming

Survey appearance is configured in the dashboard and delivered in the config — the SDK applies it automatically, no code required. This is the white-label path: restyle your surveys to match your app without shipping an update. See the Dashboard guide. For an exact brand font, set the SurveyTheme.*Font values in code (fonts are otherwise fetched at runtime and never bundled).

Debug logging

MicroSurveysSDK.loggingEnabled = true  // ON by default in DEBUG

Filter the Xcode console by [MicroSurveys] to see events, per-gate trigger decisions (and skip reasons), presentation, config fetches, and ingestion.

How a published survey reaches the screen

You publish a survey

In the dashboard, with a trigger (e.g. page_view where screen = Wallet) plus eligibility rules and a theme.

The SDK downloads config

GET /api/sdk/config returns all active surveys and the project theme; the SDK caches it to disk.

Each event is matched locally

Every Amplitude event (or ms.track(...)) is checked against every active survey’s trigger. When a trigger is satisfied, the SDK applies the eligibility order: window → trigger → frequency → audience → sampling → cap.

An eligible survey is presented

Scheduled after delaySeconds (the cap is re-checked at fire time) and rendered natively on the top-most view controller using your dashboard theme.

Results are reported

On close the SDK posts an impression (dismissed reflects the outcome) and, if answered, a response. Both carry a UUID clientId and queue in a small disk outbox, so offline submissions flush on the next launch.

Trigger progress, occurrence counters, sticky sampling decisions, and last-shown timestamps persist per user across app restarts.

endUserId resolves as Amplitude userId → deviceId → host setUser(id:) → a generated, persisted anonymous id.

Next

  • API reference — the exact config, impression, and response shapes.
  • Concepts — triggers, targeting, sampling, and caps in depth.
ConceptsAPI reference