Home

Convert iOS SDK

The Convert iOS SDK brings A/B testing, feature flags, and personalization to native iOS, iPadOS, tvOS, and macOS applications. It resolves experiment and feature decisions on-device from a cached bucketing config, then batches, persists, and flushes tracking events — including after the app is suspended or terminated — over a background URLSession so nothing is lost when the network is unavailable.

Source Repository: ios-sdk

flowchart TD
    A0["ConvertSwiftSDK (init)"]
    A1["ConvertContext"]
    A2["ConfigStore / DataManager"]
    A3["RuleManager"]
    A4["BucketingManager"]
    A5["ConfigFetchService / EventQueue"]
    A6["FeatureManager"]
    A7["EventBus"]
    A8["iOS adapters (URLSession / Keychain / UserDefaults)"]
    A9["BackgroundSessionManager / LifecycleObserver"]
    A0 -- "Creates" --> A1
    A0 -- "Fetches config via" --> A5
    A0 -- "Wires" --> A8
    A0 -- "Fires events via" --> A7
    A1 -- "Runs experiences via" --> A4
    A1 -- "Runs features via" --> A6
    A1 -- "Reads config via" --> A2
    A1 -- "Gates with" --> A3
    A1 -- "Enqueues tracking via" --> A5
    A5 -- "Persists offline via" --> A8
    A5 -- "Schedules retry via" --> A9
    A6 -- "Buckets via" --> A4
    A2 -- "Fires events via" --> A7

Loading

Key Differences from the JavaScript SDK

The iOS SDK shares the same bucketing algorithm as the JavaScript SDK, so variation assignment is deterministic and identical across SDKs. It is adapted for the Swift/Apple runtime:

• Initializer, not builder — ConvertSwiftSDK(configuration: ConvertConfiguration(sdkKey: "...")) replaces the Android builder(context).build() pattern. ready() async throws gates your first decision call instead of an onReady { } callback (a callback overload exists for UIKit-style call sites).
• Swift concurrency — Config fetch, event flush, and all SDK state are actor-isolated. Every public API is async; completion-handler twins are provided for non-async call sites.
• Apple platform adapters — URLSession for HTTP, Keychain for visitor-ID persistence, UserDefaults as a mirror, a coordinated file store for the offline event queue, and a background URLSession for post-suspension delivery.
• Offline-safe by design — Events queue durably to disk and flush via a background URLSession with background task support; a lifecycle observer triggers persist-on-background and flush-on-foreground.
• Privacy-aware — The default visitor ID is a UUID persisted in the Keychain under ThisDeviceOnly (no IDFA, no IDFV, no iCloud Keychain sync). An uninstall may surface a fresh visitor ID; continuity across reinstalls is best-effort only.
• Typed Swift models — Decisions return Swift types (Variation, Feature) and enums (FeatureStatus, LogLevel); feature variables use ConvertValue with typed accessor methods.
• No Objective-C interop surface — The public API is Swift-only; there is no @objc bridge.

Getting Started

• How Convert Works
• Architecture Overview
• Data Model Reference
• Quickstart Overview
• Requirements & Constraints

iOS SDK

• Quickstart
• Installation
• Initialization
• Configuration Options
• Return Types & Models
• Code Examples
• Offline Behavior
• Tracking Control
• Apple Privacy Manifest

Core Concepts

• Experiences & Variations
• Feature Flags
• Bucketing Algorithm
• Rule Evaluation & Targeting
• Segments
• Data Management
• Event System
• API Communication & Tracking

How-To Guides

• Running Experiences
• Running Features
• Tracking Conversions
• Visitor Context & Properties
• Persistent DataStore
• Troubleshooting

Contributing

• Testing