Guides

End-to-end iOS integration

Walk through a complete Zeta iOS SDK integration, from an empty Xcode project to receiving and tracking your first push notification.

Suggest Edits

On this page

  • Prerequisites
  • Step 1: Register your app in ZMP
  • Step 2: Add the SDK
  • Step 3: Initialize the SDK
  • Step 4: Identify a user
  • Step 5: Send a custom event
  • Step 6: Set up push notifications
  • Step 7: Add the Notification Service Extension
  • Step 8: Verify in ZMP

Prerequisites

  • Xcode 16.0 or later
  • An iOS device (push notifications do not work on the simulator)
  • A ZMP account with mobile app registration access
  • An Apple Developer account with push notification entitlements

Step 1: Register your app in ZMP

Follow the Mobile App Registration guide to register your app and obtain your clientSiteId and clientSecret.

Upload your APNS .p8 certificate and note the Team ID and Key ID.

Step 2: Add the SDK

Add the Zeta SDK via Swift Package Manager. In Xcode, go to File > Add Package Dependencies and enter:

https://gitlab.com/zeta-crm/zetakit-swift

Select the ZetaCore product and add it to your app target.

For other installation methods, see Installation.

Step 3: Initialize the SDK

In your AppDelegate, import ZetaCore and initialize the SDK:

import ZetaCore

func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
    let config = ZTConfig(
        clientSiteId: "your-site-id",
        clientSecret: "your-secret", // load from secure storage
        region: .US,
        appGroupId: "group.com.yourcompany.yourapp",
        optIn: true,
        appEnvironment: .PRODUCTION
    )
    ZetaClient.shared.initialize(config: config)
    return true
}

For full configuration options, see Getting Started.

Step 4: Identify a user

After the user logs in, set their identity:

ZetaClient.shared.user?.builder()
    .setUid("user-123")
    .setEmail(ZTUserEmail(email: "[email protected]"))
    .submit()

For the full identity API, see Contact Management.

Step 5: Send a custom event

Track a meaningful action in your app:

ZetaClient.shared.event?.send(name: "product_viewed", properties: [
    "product_id": "SKU-456",
    "category": "shoes"
])

Step 6: Set up push notifications

Request notification permission and forward the device token:

UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .badge, .sound]) { granted, _ in
    guard granted else { return }
    DispatchQueue.main.async {
        UIApplication.shared.registerForRemoteNotifications()
    }
}

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    ZetaClient.shared.user?.updateDeviceToken(token: deviceToken)
}

Set up click tracking in your UNUserNotificationCenterDelegate:

func userNotificationCenter(_ center: UNUserNotificationCenter,
                            didReceive response: UNNotificationResponse,
                            withCompletionHandler completionHandler: @escaping () -> Void) {
    if ZetaClient.shared.push?.userNotificationCenter(center, didReceive: response, withCompletionHandler: completionHandler) == true {
        return
    }
    completionHandler()
}

For the full push setup, see Push Notifications.

Step 7: Add the Notification Service Extension

Create a Notification Service Extension target in Xcode and add the ZetaNotificationService product from the same SPM package. This enables delivery tracking and rich notifications.

For detailed instructions, see Push Notifications / Notification Service Extension.

Step 8: Verify in ZMP

  1. Open ZMP and navigate to your app's integration settings.
  2. Use the Test Integration feature with your device's BSIN.
  3. Send a test push notification.
  4. Confirm the notification appears on your device.
  5. Tap the notification and verify the message_clicked event in ZMP reporting.

Next steps