iOS integration

In plain English: this page is a collection of how-tos for the Amply iOS SDK beyond "just get it running." It covers session control, deeplink scheme setup, app lifecycle bridging, and the preflight pattern for asking permissions the right way. A PM can skim the section headings to know which knobs exist; an engineer copies the Swift snippets.

Use this when you already have the iOS SDK initialized and you need to wire up a specific flow (deeplinks, lifecycle, permissions). Don't use this when you haven't finished the Quickstart yet — start there.

Before you start

• iOS SDK initialized in AppDelegate (see iOS quickstart).

• A strong reference held to your Amply instance and any listener adapters on your own side, so they stay alive for the lifetime of the app.

Managing the session manually

On iOS the SDK does not auto-track app foreground/background. You call the lifecycle methods yourself. This is different from Android, where lifecycle is automatic.

Signatures (from Amply):

func pauseSession()
func resumeSession()
func stopSession()

Wire them up in your AppDelegate:

// AppDelegate.swift
import AmplySDK

func applicationDidBecomeActive(_ application: UIApplication) {
    AppDelegate.amply?.resumeSession()
}

func applicationDidEnterBackground(_ application: UIApplication) {
    AppDelegate.amply?.pauseSession()
}

func applicationWillTerminate(_ application: UIApplication) {
    AppDelegate.amply?.stopSession()
}

If you use UISceneDelegate, bridge the same calls from sceneDidBecomeActive(_:) and sceneDidEnterBackground(_:) instead.

If you need to distinguish "brief interruption" (incoming call, control center, app switcher preview) from "user left the app," call pauseSession() from applicationWillResignActive(_:) instead of applicationDidEnterBackground(_:). The trade-off: session timing is more sensitive to transient interruptions, but you capture the moment attention leaves the screen.

When to pause vs. stop

• pauseSession() — app went to background. Session can resume when the user returns.

• resumeSession() — app returned to foreground before the session timeout.

• stopSession() — force-end the current session (for example, user logs out).

Registering your deeplink scheme

The SDK will deliver campaign deeplinks to your app, but the scheme still needs to be declared in Info.plist so iOS routes URLs to you.

<!-- Info.plist -->
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLName</key>
        <string>com.example.yourapp</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>yourapp</string>
        </array>
    </dict>
</array>

Use the same scheme when you author deeplink URLs in the Amply dashboard (for example yourapp://promo/summer).

Receiving campaign deeplinks

Register a listener after SDK init. The callback returns a Bool — true if you handled the URL, false to let the system default handler try.

Signature:

func registerDeepLinkListener(listener: DeepLinkListener) -> ListenerToken
// DeepLinkListener.onDeepLink(url: String, info: [String: Any]) -> Bool

// DeepLinkAdapter.swift
import AmplySDK

final class DeepLinkAdapter: NSObject, DeepLinkListener {
    func onDeepLink(url: String, info: [String: Any]) -> Bool {
        guard let parsed = URL(string: url) else { return false }
        if parsed.scheme == "yourapp", parsed.host == "promo" {
            let promoId = parsed.lastPathComponent
            Router.shared.showPromo(id: promoId)
            return true
        }
        return false
    }
}

// AppDelegate.swift
private let deepLinkAdapter = DeepLinkAdapter()
private var deepLinkToken: ListenerToken?
// Keep the adapter retained on the AppDelegate, not as a local — and keep the token with it.
deepLinkToken = amply?.registerDeepLinkListener(listener: deepLinkAdapter)

Store the token. Registering returns a ListenerToken, and that token — not the adapter object — is what detaches the listener later via removeDeepLinkListener(token:).

A listener registered once at launch and kept for the life of the app never needs detaching, so storing the token costs nothing. Anything shorter-lived does need it: a listener left attached after its owner is gone keeps that owner alive and the SDK goes on calling it.

Universal Links

Amply deeplinks are delivered through the SDK's listener regardless of scheme format. If you also want to handle Universal Links (https://yourapp.com/...) tapped from outside a campaign, use the standard iOS entry point:

// AppDelegate.swift
func application(
    _ application: UIApplication,
    continue userActivity: NSUserActivity,
    restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
) -> Bool {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
          let url = userActivity.webpageURL else { return false }
    Router.shared.handle(url: url)
    return true
}

Track the hit through Amply if it matters for targeting:

AppDelegate.amply?.track(
    event: "UniversalLinkOpened",
    properties: ["url": url.absoluteString]
)

Push notification preflight popup

Asking iOS for push permission directly means a single "Allow / Don't Allow" dialog with no second chance. The common pattern is to show a soft-preflight popup via an Amply campaign first, then only call UNUserNotificationCenter for users who tap "Sure."

High-level flow:

1. Track an event at a good moment, for example OnboardingCompleted.

2. In the Amply dashboard, target a popup campaign at that event.

3. The popup's primary button opens a deeplink like yourapp://permissions/push.

4. Your deeplink handler calls requestAuthorization.

// DeepLinkAdapter.swift (extended)
func onDeepLink(url: String, info: [String: Any]) -> Bool {
    guard let parsed = URL(string: url) else { return false }
    if parsed.host == "permissions", parsed.lastPathComponent == "push" {
        UNUserNotificationCenter.current().requestAuthorization(
            options: [.alert, .badge, .sound]
        ) { granted, _ in
            AppDelegate.amply?.track(
                event: granted ? "PushPermissionGranted" : "PushPermissionDenied"
            )
        }
        return true
    }
    return false
}

For the full recipe including copy tips and retry cadence, see Soft push permission.

Listening to SDK system events

Useful during development to see when config loads, when sessions start, and which campaigns evaluate.

Signature:

func setSystemEventsListener(listener: SystemEventsListener) -> ListenerToken
// SystemEventsListener.onEvent(event: EventInterface)

final class SystemEventsAdapter: NSObject, SystemEventsListener {
    func onEvent(event: EventInterface) {
        print("[Amply] \(event.name) \(event.properties)")
    }
}

private let systemEventsAdapter = SystemEventsAdapter()
private var systemEventsToken: ListenerToken?

systemEventsToken = amply?.setSystemEventsListener(listener: systemEventsAdapter)

Hold the adapter on the AppDelegate or another long-lived owner, and hold the token alongside it — clearSystemEventsListener(token:) takes the token, not the adapter.

Log level

amply?.setLogLevel(level: "debug")   // 'none' | 'error' | 'warn' | 'info' | 'debug'

Leave it at warn or lower in production builds.

ATT and IDFA

The SDK reads IDFA when App Tracking Transparency has been granted. Prompting for ATT is your app's responsibility:

import AppTrackingTransparency

ATTrackingManager.requestTrackingAuthorization { _ in
    // SDK will pick up IDFA on the next dataset read.
}

Request ATT on a meaningful screen, not immediately on launch — Apple rejects apps that prompt before context is established.

Related

• iOS quickstart — initial setup, not covered here.

• Tracking events — payload shapes and common patterns.

• Handling deeplinks — cross-platform deeplink routing patterns.

• Soft push permission — full preflight recipe.

• SDK reference: iOS — full method list.