iOS integration

This guide covers the complete iOS integration of Amply SDK.

Basic Setup

1

Add Dependency

Swift Package Manager

In Xcode: File → Add Package Dependencies and enter the repository URL.

Or in Package.swift:

Package.swift

dependencies: [
    .package(url: "https://github.com/anthropics/amply-sdk-ios", from: "0.1.7")
]

CocoaPods

In your Podfile:

Podfile

pod 'AmplySDK', '~> 0.1.7'

Then run pod install.

2

Initialize SDK

Initialize in your AppDelegate:

AppDelegate.swift

import UIKit
import AmplySDK

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    private static var amplySDK: Amply?

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {

        let config = AmplyConfig(
            appId: "your.app.id",
            apiKeyPublic: "your_public_key",
            apiKeySecret: "your_secret_key",
            defaultConfig: nil
        )

        AppDelegate.amplySDK = Amply(config: config)

        return true
    }

    static func getAmply() -> Amply? {
        return amplySDK
    }
}

3

SwiftUI App Lifecycle

For SwiftUI apps using @main App:

MyApp.swift

import SwiftUI
import AmplySDK

@main
struct MyApp: App {

    @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate

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

Configuration Options

Full Configuration

Configuration

let config = AmplyConfig(
    appId: "your.app.id",
    apiKeyPublic: "your_public_key",
    apiKeySecret: "your_secret_key",
    defaultConfig: nil,  // Optional: default campaign JSON
    configBaseUrl: "https://config.amply.tools",  // Optional: override
    backendBaseUrl: "https://api.amply.tools"     // Optional: override
)

Tracking Events

Basic Events

Tracking basic events

guard let amply = AppDelegate.getAmply() else { return }

// Simple event
amply.track(event: "OnboardingStarted")

// Event with properties
amply.track(event: "ButtonTapped", properties: [
    "name": "purchase_btn",
    "screen": "PaywallCoffee2"
])

From View Controllers

ProductViewController.swift

class ProductViewController: UIViewController {

    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)

        AppDelegate.getAmply()?.track(event: "product_screen_viewed")
    }

    @IBAction func purchaseButtonTapped(_ sender: UIButton) {
        AppDelegate.getAmply()?.track(event: "PurchaseFinished", properties: [
            "product_id": "com.example.app.sub.01y",
            "price": 29.99,
            "currency": "USD"
        ])
    }
}

From SwiftUI Views

PurchaseButton.swift

struct PurchaseButton: View {
    var body: some View {
        Button("Purchase") {
            AppDelegate.getAmply()?.track(event: "OnboardingStarted")
        }
    }
}

Handling Deep Links

Register Listener

DeepLinkAdapter.swift

protocol DeepLinkHandler: AnyObject {
    func handleDeepLink(url: String, info: [String: Any]) -> Bool
}

class DeepLinkAdapter: NSObject, DeepLinkListener {
    private weak var handler: DeepLinkHandler?

    init(handler: DeepLinkHandler) {
        super.init()
        self.handler = handler
    }

    func onDeepLink(url: String, info: [String: Any]) -> Bool {
        return handler?.handleDeepLink(url: url, info: info) ?? false
    }
}

Register in your app:

AppDelegate+DeepLink.swift

class AppDelegate: UIResponder, UIApplicationDelegate, DeepLinkHandler {

    private var deepLinkAdapter: DeepLinkAdapter?

    func application(...) -> Bool {
        // ... SDK init ...

        // Register deep link listener
        deepLinkAdapter = DeepLinkAdapter(handler: self)
        AppDelegate.amplySDK?.registerDeepLinkListener(listener: deepLinkAdapter!)

        return true
    }

    func handleDeepLink(url: String, info: [String: Any]) -> Bool {
        if url.hasPrefix("myapp://promo/") {
            let promoId = String(url.dropFirst("myapp://promo/".count))
            showPromoScreen(promoId: promoId)
            return true
        }
        return false
    }
}

System Events

Listen for SDK system events:

SystemEventsAdapter.swift

class SystemEventsAdapter: NSObject, SystemEventsListener {

    func onEvent(event: EventInterface) {
        print("System event: \(event.name)")

        switch event.name {
        case "SDK_INITIALIZED":
            onSdkReady()
        case "CAMPAIGNS_LOADED":
            onCampaignsReady()
        case "SESSION_START":
            onSessionStart()
        default:
            break
        }
    }
}

// Register
let adapter = SystemEventsAdapter()
amply.setSystemEventsListener(listener: adapter)

Important: Keep a strong reference to your listener adapter to prevent it from being deallocated.

Rate & Review

The SDK supports triggering App Store reviews via campaigns. On iOS:

• Uses SKStoreReviewController.requestReview()

• Follows Apple's guidelines for review prompts

• No additional code needed - handled automatically by campaign actions

Get Dataset Snapshots

Get dataset snapshots

Task {
    guard let amply = AppDelegate.getAmply() else { return }

    // Device data
    if let deviceType = DataSetType.Companion.shared.fromString(value: "@device", params: [:]) {
        let deviceData = try await amply.getDataSetSnapshot(type: deviceType)
        print("Device: \(deviceData)")
    }

    // Session data
    if let sessionType = DataSetType.Companion.shared.fromString(value: "@session", params: [:]) {
        let sessionData = try await amply.getDataSetSnapshot(type: sessionType)
        print("Session: \(sessionData)")
    }

    // Event data
    if let eventType = DataSetType.Companion.shared.fromString(
        value: "@triggeredEvent",
        params: ["eventName": "purchase_completed"]
    ) {
        let eventData = try await amply.getDataSetSnapshot(type: eventType)
        print("Event: \(eventData)")
    }
}

Get Recent Events

Get recent events

Task {
    guard let amply = AppDelegate.getAmply() else { return }

    let events = try await amply.getRecentEvents(limit: 30)
    for event in events {
        print("\(event.name) at \(event.timestamp)")
    }
}

App Lifecycle

The SDK automatically handles app lifecycle for session management. For manual control:

App lifecycle callbacks

func applicationDidBecomeActive(_ application: UIApplication) {
    // Session automatically resumes
}

func applicationDidEnterBackground(_ application: UIApplication) {
    // Session automatically pauses
}

Best Practices

• Initialize in AppDelegate — Ensures SDK is ready before any view loads

• Keep strong references — Listener adapters must be retained

• Request ATT early — But respect user experience (don't prompt immediately)

• Use async/await — SDK methods are async-friendly

• Test on device — Some features require real device (IDFA, reviews)

Troubleshooting

SDK Not Initializing

• Verify API keys are correct

• Check network connectivity

• Review console logs for errors

IDFA Always Empty

• Ensure ATT permission is granted

• Check Info.plist has usage description

• Test on real device (simulator has no IDFA)

Events Not Sending

• Ensure SDK is initialized

• Check network connectivity

• Verify app has network permission

Listener Not Receiving Events

• Keep strong reference to adapter objects

• Verify listener is registered after SDK init

• Check for deinit calls in adapter logs