iOS SDK
Last updated
Use the Swift SDK to add Metrickle to an iPhone or iPad app built with UIKit or SwiftUI. It follows the same rules as the other SDKs, so a funnel, task or survey means the same thing on iOS as on the web. For what each event means and how to name your own, see Events, people and properties.
Native Swift SDK for Metrickle: UX research and conversion analytics, accessibility first. It records screens, journeys and friction (rage taps, U-turns, form errors), segments everything by the assistive tech and accessibility settings people use, and runs in-app surveys in an accessible native sheet.
It follows the same event model as the web, React Native, Android and Flutter SDKs, so a funnel, task or survey means the same thing on every platform.
- iOS 15+ (builds on macOS 12+ for tests), Swift 6 language mode, no dependencies
- UIKit and SwiftUI
- Thread safe: every method can be called from any thread and never blocks the main thread on I/O
Install
Swift Package Manager: in Xcode choose File › Add Package Dependencies… and enter
https://github.com/metrickle/metrickle-swift
or in Package.swift:
.package(url: "https://github.com/metrickle/metrickle-swift", from: "0.2.0"),
// ...
.target(name: "MyApp", dependencies: [.product(name: "Metrickle", package: "metrickle-swift")]),
Quick start
UIKit
import Metrickle
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
Metrickle.configure(writeKey: "mk_pub_YOUR_WRITE_KEY")
return true
}
Screens are tracked automatically from viewDidAppear. The name is the controller’s title, or its class name without the ViewController suffix (CheckoutViewController → Checkout). Navigation, tab, page and split view controllers, system controllers and generic ones such as UIHostingController<Content> are skipped. To choose the name, or skip a controller:
final class CheckoutViewController: UIViewController, MetrickleScreenNaming {
var metrickleScreenName: String? { "Checkout" } // nil to skip
}
Titles can contain user data (for example a person’s name on a profile screen). Adopt MetrickleScreenNaming on those controllers.
SwiftUI
import Metrickle
import SwiftUI
@main
struct MyApp: App {
init() { Metrickle.configure(writeKey: "mk_pub_YOUR_WRITE_KEY") }
var body: some Scene {
WindowGroup { HomeView().metrickleScreen("Home") }
}
}
struct CheckoutView: View {
var body: some View {
Form { /* ... */ }
.metrickleScreen("Checkout", properties: ["step": 2])
}
}
Events
let mk = Metrickle.shared!
mk.track("plan_selected", properties: ["plan": "pro", "seats": 5, "annual": true])
mk.screen("Onboarding step 2") // manual screen, e.g. for custom containers
mk.identify("user_123", traits: ["plan": "pro"])
mk.register(["experiment": "b"]) // added to every later event
mk.formError(form: "signup", field: "email", reason: "format") // field ids only, never what was typed
mk.reset() // on logout: new anonymous id (none while opted out) and session
mk.flush()
Property values are strings (up to 1024 characters), numbers, booleans or nil, at most 64 per event. Names starting with $ are reserved.
Revenue from Stripe or RevenueCat
Connect your RevenueCat project (or Stripe account) in the Metrickle dashboard under Integrations → Revenue. Purchases, renewals, refunds and cancels then arrive server-side on the person you identified, so a refund takes back the task they completed. Log in to RevenueCat with the same id:
mk.identify(user.id)
_ = try await Purchases.shared.logIn(user.id)
// Or keep RevenueCat's id and name the Metrickle user:
// Purchases.shared.attribution.setAttributes(["metrickle_user_id": user.id])
Options
Metrickle.configure(writeKey: "mk_pub_YOUR_WRITE_KEY", options: .init(
host: "https://in.metrickle.com",
flushInterval: 5,
debug: true,
beforeSend: { event in
var event = event
event.properties?["email"] = nil
return event // or nil to drop it
}
))
| Option | Default | |
|---|---|---|
host | https://in.metrickle.com | Ingest origin (trailing slash is removed). |
cookieless | false | Persist no ids. The server derives a daily-rotating visitor hash; surveys stay off. |
flushInterval | 5 | Seconds between sends. Events are also sent at 20 queued and when the app goes to the background. |
sessionTimeout | 1800 | Seconds of inactivity before a new session starts. |
automaticScreenTracking | true | $screen from UIViewController.viewDidAppear. |
rageTaps | true | $rage_click for 3 taps within 1 second inside 30pt. |
deadTaps | true | $dead_click / $slow_click for taps on controls that nothing answered within 4 seconds, or only after 1 second. See Dead and slow taps. |
debug | false | Log every queued event and each send result. |
beforeSend | nil | Edit or drop (return nil) each event before it is queued. Runs on the SDK queue. |
appVersion / appBuild | bundle values | Override CFBundleShortVersionString / CFBundleVersion. |
What is collected automatically
| Event | When |
|---|---|
$screen | A screen appears (UIKit automatically, SwiftUI with .metrickleScreen). referrer is the previous screen. |
$app_open | Launch and each return to the foreground. |
$app_background | The app goes to the background; the queue is then sent inside a background task. |
$u_turn | Screen A → B → back to A within 7 seconds (back_to, dwell_ms). |
$rage_click | 3 taps within 1 second in a 30pt radius (selector: accessibility identifier or class name, text: accessibility label or button title, up to 80 characters, never text field contents). |
$form_error | You call formError(form:field:reason:). Duplicates within 1.5 seconds are collapsed. |
$dead_click | A tap on a control that nothing answered within 4 seconds (selector, text as for rage taps, input: "touch", affordance: "control"). |
$slow_click | A tap on a control that was answered, but only after 1 to 4 seconds (as $dead_click, plus ms). |
Each batch carries device context (type, model identifier, iOS version, screen size in points, app version, locale, time zone) and accessibility flags, updated when a setting changes: screen_reader (VoiceOver), keyboard (hardware keyboard or Switch Control), reduced_motion, reduced_transparency, high_contrast (Increase Contrast), inverted_colors, grayscale, bold_text, large_text (text size above the default).
Dead and slow taps
The same signals as the web SDK’s dead clicks, so friction, hotspots and cases treat them alike. On by default; turn them off with deadTaps: false (rageTaps is separate).
A tap (down and up within 10pt) is judged when it lands on:
- UIKit: the nearest enabled
UIControl, a view with aUITapGestureRecognizeryour app added, or a cell of a table or collection view that allows selection. Text fields, text views, search bars, sliders and disabled controls are never judged. - SwiftUI: views you mark with
.metrickleTag("id"). SwiftUI has no public way to tell a button from text under a finger, so nothing else is judged. The tag also becomes the view’s accessibility identifier and theselectorof its dead, slow and rage taps.
Button("Pay now") { pay() }
.metrickleTag("pay-button")
A tap is answered by anything the person could notice: an event captured after it (a screen change, your own track(), the app going to the background; not other friction signals) or a change on screen (a cheap fingerprint of the window’s layer tree, taken when the finger goes down, differs). An answer within 1 second sends nothing. An answer within 4 seconds sends $slow_click with ms; none sends $dead_click. Both carry the screen the tap happened on. Something that animates on its own can hide a dead tap; nothing makes a working tap look dead.
Surveys
Campaigns are created in the Metrickle dashboard. The SDK fetches them at launch, on foreground (at most every 5 minutes) and on refreshConfig(), then decides on the device whether to show one: trigger (load, a screen name with an optional trailing *, or an event), delay, targeting, sampling, frequency caps and a 24-hour cooldown between any two surveys.
Built-in sheet
On by default. The sheet is presented on the top-most view controller and is designed to meet WCAG 2.2 AA:
- Announced once when it opens, with VoiceOver focus on its “Survey” heading. It never appears over an alert or during a transition.
- Scale questions (NPS 0–10, CSAT and rating 1–5, CES 1–7) are single-select groups of buttons of at least 44×44pt. Each button’s label includes the end label (“0, Not at all likely”) and selected state, and the group is labelled with the question.
- Choice questions use toggles (multiple answers) or a list of selectable rows (single answer). Text questions have a visible label and a multiline field.
- Dynamic Type with no truncation (it scrolls, opens at full height for accessibility sizes, and stacks buttons), dark mode, Increase Contrast (outlines in the full text colour at twice the width, and semantic colours), and Reduce Motion (presented without animation).
- A visible Close button; swipe down, Escape and the VoiceOver escape gesture also dismiss it. It ends with your thank-you message or “Thanks for your feedback”.
- When the campaign has a follow-up and the response qualifies, the submit button says “One moment…” (focus stays on it) while the sheet asks for the person’s study link, for up to 5 seconds. With a link it shows the invite (below); otherwise the thank-you.
- Your brand accent (
branding.accent) is used for fills only when it reaches 4.5:1 against the sheet background (7:1 with Increase Contrast); otherwise the app’s tint colour is used. Text on fills is white when it reaches 4.5:1, otherwise black (textOn, as on the web).
Metrickle.shared?.surveys.useBuiltInSheet = false // turn it off
Metrickle.shared?.surveys.show("cmp_123") // QA: show an active campaign now, ignoring targeting
Headless
Render surveys with your own UI. Your renderer replaces the built-in sheet and is called on the main thread:
let stop = Metrickle.shared?.surveys.onShow { survey in
present(MySurveyView(campaign: survey.campaign,
onAppear: { survey.shown() },
onAnswer: { question, answer in survey.answer(question, answer) }, // Answer(score:), Answer(values:), Answer(text:)
onFinish: { survey.complete() },
onClose: { index in survey.dismiss(atIndex: index) }))
}
// later: stop?()
Answers become $survey_shown, $survey_answered and $survey_dismissed events, so responses join journeys and funnels.
Follow-ups (study invites)
A campaign can invite the people who answered into a study: a booked video call (moderated) or a self-guided test on the web (unmoderated). The campaign then carries survey.followUp (studyId, kind, prompt, optional when, incentive, durationMin), only while the study is recruiting. when limits it to certain answers, for example NPS 0–6 or a particular choice.
The built-in sheet handles all of this. After the last answer it shows the invite: your prompt as a heading (VoiceOver focus moves to it), what taking part involves (“A 30-minute video call at a time that suits you.” or “A short self-guided test of the site. Takes about 10–15 minutes.”), any incentive (“As a thank-you: …”), and two buttons: “No thanks” and “Choose a time” (moderated) or “Take part” (unmoderated). The second opens the person’s link in the browser and says so to VoiceOver. The invite never closes on its own.
With your own renderer:
Metrickle.shared?.surveys.onShow { survey in
// ... ask the questions, calling survey.answer(_:_:) for each, then:
survey.complete()
guard survey.followUp != nil, survey.qualifies() else { return showThanks() }
Task { @MainActor in
guard let url = await survey.invite() else { return showThanks() } // nil: full, closed, or offline
showInvite(survey.followUp!, onAccept: {
survey.followUpAccepted()
UIApplication.shared.open(url)
})
survey.followUpOffered() // once the invite is on screen
}
}
qualifies(): whether this response’s answers meetfollowUp.when(always true without one; false with no follow-up).invite(): the person’s personal study link. It asks the server once per response (later calls return the same answer) and returns nil when there’s no follow-up, the response doesn’t qualify, the user opted out, the study is full or no longer recruiting, the link isn’t https, or the request fails. Only show an invite you have a link for.followUpOffered()/followUpAccepted(): each records$survey_follow_uponce per response (study,accepted: false/true), so you can see how many people were asked and how many said yes.
Feedback
let screenshot = Metrickle.shared?.feedback.captureScreenshot() // only after the user opts in
let result = await Metrickle.shared?.feedback.submit(
category: .accessibility, // .bug, .confusing, .idea, .accessibility, .other
message: "The pay button has no label",
rating: 2, // optional, 1–5
screenshot: screenshot
)
if result?.ok == true { /* result.id */ }
Feedback can be switched off per platform under Settings → Research in the dashboard. While it’s off, Metrickle.shared?.feedback.isEnabled is false and submit sends nothing, so use it to hide your feedback button.
The session, current screen, app version, device, screen size, locale and accessibility flags are attached. captureScreenshot() renders the key window as JPEG (quality 0.7, at most 1280px on the long edge, at most 2 MB). A screenshot can contain personal data, so only capture one when the user chooses to attach it. Text fields are not masked.
Built-in feedback sheet
A native “Send feedback” sheet you open from your own button or menu item. It never opens by itself, and does nothing while feedback.isEnabled is false or after optOut().
// UIKit: presents on the top-most view controller, or pass `from:`. Returns whether it opened.
Metrickle.shared?.feedback.present()
Metrickle.shared?.feedback.present(from: self, category: .accessibility) // preselect a category
// SwiftUI: set back to false when the sheet closes, or straight away if it can't open.
@State private var reporting = false
Button("Report a problem") { reporting = true }
.metrickleFeedbackSheet(isPresented: $reporting)
The copy matches the web dialog: “What’s it about?” (Something’s broken, Something’s confusing, An idea or request, An accessibility barrier, Something else) and “Tell us what happened” (up to 4000 characters), with “Cancel” and “Send”. It submits through submit(category:message:), so the current screen, device, app version, locale and accessibility flags are attached. It never attaches a screenshot; to include one, build your own form with captureScreenshot() and submit.
It’s designed to meet WCAG 2.2 AA, like the survey sheet:
- Announced once when it opens, with VoiceOver focus on its “Send feedback” heading.
- The categories are a single-select group: each row is at least 44pt tall and has a selected state.
- Errors (“Choose what your feedback is about.”, “Describe what happened.”) appear under their fields, focus moves to the first one, and “Please fix the highlighted fields.” is announced. While sending, Send says “Sending…” and is disabled. If sending fails the message is announced and the sheet stays open with the text kept.
- On success the form is replaced by “Thank you! Your feedback was sent.” (focused) and a Done button. It waits for the person rather than closing by itself.
- Dynamic Type with no truncation (it scrolls and stacks buttons), dark mode, Increase Contrast, and Reduce Motion (presented without animation). A visible Close button; swipe down, Escape and the VoiceOver escape gesture also dismiss it.
- Your brand accent is used as in the survey sheet (4.5:1, else the app’s tint). “Powered by Metrickle” is shown unless you turn it off in the dashboard (
branding.poweredBy). - It isn’t recorded as a screen by automatic screen tracking.
Privacy
- No IDFA, IDFV or device serials.
anonymousIdis a random UUID stored in the app’scom.metrickleUserDefaults suite and removed with the app. The model identifier (for exampleiPhone15,2) identifies a hardware model, not a device. - Text field contents are never captured, only identifiers you pass.
optOut()clears the queue, stops collection, removes the anonymous id and session from the device, and makes no further network calls (including config, feedback and study invites) untiloptIn(). The choice is persisted. While opted out no anonymous id is created, at launch or onreset(). Your own user id fromidentify()and the consent choice are kept.optIn()creates a new anonymous id and fetches surveys and settings again.- Cookieless mode stores no ids at all.
consent(replay:)records consent for session replay (not available on iOS yet; kept for parity with the web SDK).- Unsent events (at most 1000) are kept on disk so they survive the app being killed; events older than 7 days are never sent.
- The package includes a
PrivacyInfo.xcprivacy: no tracking, no tracking domains, collected data types Product Interaction and Other Usage Data (analytics, not linked to the user’s identity, not used for tracking), and the UserDefaults required-reason API with reasonCA92.1. If you callidentify()with your own user ids, update your app’s privacy manifest and App Store privacy answers to declare the data as linked to the user.