This guide describes how the MotiSig iOS SDK fits into your app at runtime. For install steps, see the iOS overview. For keys and URLs, see Configuration.

Overview

Call MotiSig.initialize(...) once at launch from application(_:didFinishLaunchingWithOptions:) and pass launchOptions (see below).
When you know the signed-in user, call MotiSig.shared.setUser(id:). That registers the user with the MotiSig API and, when an APNs device token is available, upserts the push subscription for that user.
Use MotiSig.shared for profile updates, tags, attributes, events, and notification listeners as needed.

Initialization (SwiftUI)

SwiftUI apps do not receive didFinishLaunching on the @main App struct. Use @UIApplicationDelegateAdaptor so initialization runs before scene setup:

import SwiftUI
import MotiSig

@main
struct YourApp: App {
    @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate

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

class AppDelegate: NSObject, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
    ) -> Bool {
        MotiSig.initialize(
            sdkKey: "YOUR_SDK_KEY",
            projectId: "YOUR_PROJECT_ID",
            logLevel: .info,
            launchOptions: launchOptions
        )
        return true
    }
}

Initialization (UIKit)

import UIKit
import MotiSig

func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
) -> Bool {
    MotiSig.initialize(
        sdkKey: "YOUR_SDK_KEY",
        projectId: "YOUR_PROJECT_ID",
        logLevel: .info,
        launchOptions: launchOptions
    )
    return true
}

Call MotiSig.initialize(...) in application(_:didFinishLaunchingWithOptions:) — not after async auth or other deferred work. The SDK installs the notification delegate proxy and AppDelegate swizzles before iOS can deliver a cold-start notification tap. Deferred initialization is not supported for push click tracking.

The launchOptions parameter is available on the UIKit overload only (#if canImport(UIKit) && !os(watchOS)). When the user opened the app by tapping a push, launchOptions[.remoteNotification] is handled during initialize(). See Push notifications.

Lifecycle

flowchart LR
  init[MotiSig.initialize]
  setUser[MotiSig.shared.setUser]
  api[Server mutations]
  token[APNs token registration]
  init --> setUser
  setUser --> api
  setUser --> token

After initialization, the SDK may request notification permission and register for remote notifications. Push wiring (including method swizzling) is installed as part of initialize; see Push notifications.

Ordered mutations

User-scoped HTTP mutations (setUser, tags, attributes, updateUser, ping, triggerEvent, push subscription upsert/patch/remove) run on an internal FIFO queue. Each queued item captures the user id (and token where applicable) at enqueue time, so work is not dropped if logout() clears storage before a request runs. See User and profile for logout details.

Notification click tracking uses a separate persistent FIFO (ClickDispatcher) on disk. Pending clicks survive app restarts and are retried with exponential backoff until delivery succeeds or the entry is dropped. See Push notifications — Click tracking.

Next steps

Configuration — keys, base URL, logging, launchOptions
User and profile — setUser, updateUser, logout
Events, tags, attributes — events, tags, attributes, ping
Push notifications — listeners, payloads, click reliability

Getting started