Connect your iOS app
RelevaSDK connects a native iOS app to Releva: screen and product tracking, product blocks, banners, stories, NPS surveys, app push through Firebase Cloud Messaging and the App Inbox. The code is cut down from Releva’s SwiftUI example app and the SDK’s README at version 5.2.1. The latest release is 5.2.1 (21 October 2026); see the integrations changelog for what changed. Every method is listed in the Swift SDK reference.
Before you start
Section titled “Before you start”- iOS 15 or later, Swift 5.7 language mode or later. Xcode as required by the Firebase version Swift Package Manager resolves (the SDK accepts
firebase-ios-sdk11.15.0 up to, not including, 13.0.0; pin"11.15.0"..<"12.0.0"to stay on an older Xcode). - Your shop’s Access Token from Settings › Shop & Integration › General: Find your Access Token and Secret Key. Never put the Secret Key in the app.
- One page token per screen you want to track or personalise, from the Token: bar on Personalization › Product Blocks: Pages and tokens.
- For push: a Firebase project with
GoogleService-Info.plist, and its service account uploaded in Releva: Add your Firebase credentials for app push. The Swift SDK registers FCM tokens, so iOS APNs environment does not apply to it.
Install
Section titled “Install”Swift Package Manager is the only distribution channel. The package has two products: RelevaSDK for the app target and RelevaNotificationExtension for a Notification Service Extension (images and buttons on pushes).
In Xcode: File › Add Package Dependencies…, enter https://github.com/Releva-ai/sdk-swift.git with Up to Next Major Version from 5.2.1, and add RelevaSDK to your app target. Then add https://github.com/firebase/firebase-ios-sdk.git as a second package and add its FirebaseMessaging and FirebaseCore products to the app target: Firebase is a dependency of the SDK, but Swift Package Manager only lets your code use products from packages your own project declares, and the push setup below calls Messaging.messaging().
In a Package.swift:
dependencies: [ .package(url: "https://github.com/Releva-ai/sdk-swift.git", from: "5.2.1"), .package(url: "https://github.com/firebase/firebase-ios-sdk.git", "11.15.0"..<"13.0.0")],targets: [ .target(name: "YourApp", dependencies: [ .product(name: "RelevaSDK", package: "sdk-swift"), .product(name: "FirebaseMessaging", package: "firebase-ios-sdk"), .product(name: "FirebaseCore", package: "firebase-ios-sdk") ])]Add GoogleService-Info.plist to the app target and call FirebaseApp.configure() at launch, as in the standard Firebase setup. For push, add the Push Notifications capability and Background Modes › Remote notifications under Signing & Capabilities.
Configure
Section titled “Configure”1. App delegate: client, delegate order, token provider, permission
Section titled “1. App delegate: client, delegate order, token provider, permission”import SwiftUIimport FirebaseCoreimport FirebaseMessagingimport RelevaSDK
class AppDelegate: NSObject, UIApplicationDelegate, MessagingDelegate { static var relevaClient: RelevaClient?
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool { FirebaseApp.configure()
// realm: "" unless Releva gives you one. accessToken: Settings › Shop & Integration › General. let client = RelevaClient(realm: "", accessToken: "<yourAccessToken>") client.setDeviceId(deviceId) // a UUID you store on first launch client.setProfileId("DEMO-1001") // after login; before that, your own anonymous id
// If your app has its own UNUserNotificationCenterDelegate, set it BEFORE this call: // the SDK takes the delegate slot and forwards what it does not own. client.enablePushEngagementTracking()
// Lets the SDK re-upload the current FCM token on every foreground and profile change. client.pushTokenProvider = { completion in Messaging.messaging().token { token, _ in completion(token) } } client.initializeInbox() AppDelegate.relevaClient = client
Messaging.messaging().delegate = self UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .badge, .sound]) { granted, _ in if granted { DispatchQueue.main.async { application.registerForRemoteNotifications() } } } return true }
func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) { // Only needed when Firebase method swizzling is off (FirebaseAppDelegateProxyEnabled = NO). Messaging.messaging().apnsToken = deviceToken registerPushToken() }
func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String?) { registerPushToken() }
private func registerPushToken() { Task { do { let fcmToken = try await Messaging.messaging().token() try await AppDelegate.relevaClient?.registerPushToken(fcmToken, deviceType: .ios) } catch { print("Push token registration failed: \(error.localizedDescription)") } } }}RelevaClient is @MainActor; the first instance you create becomes RelevaClient.shared. Methods that return a result or an error are async throws; the rest are fire-and-forget. With pushTokenProvider set, the SDK fetches and re-registers the token on every foreground and whenever the profile id changes, skipping the upload when the token, profile and a registration younger than 24 hours are unchanged. Without it the stored token drifts stale and pushes fail with “device token expired”.
Do not add a userNotificationCenter(_:didReceive:) that calls trackEngagement(..., type: .opened) for Releva pushes: since 5.2.1 the SDK tracks and forwards every tap itself, and such a handler counts each tap twice. If your delegate routes every tap generically, skip Releva’s with client.isRelevaMessage(userInfo:).
If your app keeps its own UNUserNotificationCenterDelegate, or calls enablePushEngagementTracking() after application(_:didFinishLaunchingWithOptions:) returns, use SDK 5.3.0 or later and pass each tap to client.handleNotificationResponse(response) in userNotificationCenter(_:didReceive:withCompletionHandler:). The SDK tracks and routes the tap once and returns false for a push that is not Releva’s, so you can route your own. Without it, the SDK does not see those taps (for a late start, the tap that launches a closed app), so they are not tracked and do not navigate.
2. Silent inbox-sync pushes
Section titled “2. Silent inbox-sync pushes”The SDK handles inbox_sync pushes only on the tap path. Forward the silent ones yourself:
func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable: Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) { Messaging.messaging().appDidReceiveMessage(userInfo) // only when swizzling is off
let isInboxSync = (userInfo["inbox_sync"] as? String) == "true" || (userInfo["click_action"] as? String) == "RELEVA_INBOX_SYNC" if isInboxSync { InboxService.shared.handleSyncSignal() } completionHandler(.newData)}The example app waits for the refresh to finish before calling the completion handler, so iOS does not suspend the app mid-request.
3. Rich notifications (images, buttons)
Section titled “3. Rich notifications (images, buttons)”Add a Notification Service Extension target (File › New › Target › Notification Service Extension), add the RelevaNotificationExtension product to it and replace the generated class:
import UserNotificationsimport RelevaNotificationExtension
class NotificationService: RelevaNotificationServiceExtension { // No code needed. The SDK handles the rich notification.}4. Navigate from a tap
Section titled “4. Navigate from a tap”The SDK posts a NotificationCenter notification; your app navigates:
NotificationCenter.default.addObserver(forName: Notification.Name("RelevaNavigateToScreen"), object: nil, queue: .main) { note in guard let screen = note.userInfo?["screen"] as? String else { return } let parameters = note.userInfo?["parsedParameters"] as? [String: Any] // KV Pairs from the push form // route to `screen`}NotificationCenter.default.addObserver(forName: Notification.Name("RelevaNavigateToURL"), object: nil, queue: .main) { note in guard let url = note.userInfo?["url"] as? URL else { return } // your own schemes only // handle the deep link}NotificationCenter.default.addObserver(forName: Notification.Name("RelevaNavigateToInbox"), object: nil, queue: .main) { note in let parameters = note.userInfo?["parsedParameters"] as? [String: Any] let inboxMessageId = parameters?["inboxMessageId"] // open the inbox, optionally that message}
// After the observers exist: replay a tap the SDK handled during a cold launch.if let pending = AppDelegate.relevaClient?.consumePendingNavigation() { NotificationCenter.default.post(name: pending.name, object: nil, userInfo: pending.userInfo)}screen is the Screen name and parsedParameters the KV Pairs set under Mobile Targeting on the push’s Behavior tab. https:// links are opened in Safari by the SDK; only your own schemes post RelevaNavigateToURL.
5. Track screens with page tokens
Section titled “5. Track screens with page tokens”// Screen view with the page token from Personalization › Product Blockslet response = try await client.trackScreenView(screenToken: "<homePageToken>")
// Cart and wishlist are stateful: set them and the SDK syncs the changeslet product = CartProduct(id: "DEMO-1001", price: 29.99, quantity: 1, custom: CustomFields().withStringField(key: "size", values: ["M"]))client.setCart(Cart(products: [product]))client.setWishlist([WishlistProduct(id: "DEMO-1002")])
// Order placed in the apptry await client.trackCheckoutSuccess(orderedCart: Cart(products: [product], orderId: "DEMO-ORDER-1001"))A screen sent without a page token, or with a token Releva does not know, is accepted but records no page view and returns no banners or stories. The SDK sends no page URL, so URL-based targeting of banners and stories does not apply on iOS; target by page token or segment.
Banners, stories and NPS attach to SwiftUI views with .bannerDisplay(client:targetSelector:onLinkTap:), .storyDisplay(client:onLinkTap:) and .npsDisplay(onSubmit:). Scroll triggers need .relevaScrollTracking(client) on the content of the ScrollView (or client.reportScrollPercentage(_:) from UIKit). See the SDK reference.
6. Logout
Section titled “6. Logout”client.setProfileId(UUID().uuidString, true) // fresh anonymous id, no merge// With pushTokenProvider set, the SDK re-registers the token under the new profile by itself.// If you build a new client instead, call oldClient.shutdown() first, or the old one keeps// re-registering the token under the previous profile on every foreground.Verify
Section titled “Verify”Run the app, accept the notification permission and open a screen with a page token. Then follow Check that your mobile app is connected. With RelevaConfig.debug() the SDK logs RelevaSDK: ✓ Successfully registered push token for ios after a successful registration.
Troubleshooting
Section titled “Troubleshooting”Taps are counted twice. Your app also calls trackEngagement(userInfo:type: .opened) in didReceive. Remove it; the SDK tracks taps since 5.2.1.
Your own notifications stopped showing or their taps no longer reach your delegate. Your UNUserNotificationCenterDelegate was set after enablePushEngagementTracking(). Set it first; the SDK forwards willPresent for non-Releva notifications, didReceive for every tap and openSettingsFor always.
Pushes stop after some days with “device token expired”. pushTokenProvider is not set, so the rotated FCM token was never re-registered.
A tap on a cold launch navigates nowhere. The observers were registered after the SDK posted the navigation. Call consumePendingNavigation() once the observers exist.
The inbox does not update until the app is reopened. Silent inbox_sync pushes are not forwarded to InboxService.shared.handleSyncSignal(), or Background Modes › Remote notifications is off.
No banners, stories or product blocks, and no Viewed Page event. The screenToken is not a page token. Copy it from Personalization › Product Blocks.
registerPushToken throws missingRequiredField. setDeviceId has not run.
Messaging.messaging().token() fails or the token never arrives. Firebase is not configured, the APNs key is not uploaded to the Firebase project, or swizzling is off and Messaging.messaging().apnsToken is not set in didRegisterForRemoteNotificationsWithDeviceToken.
What syncs
Section titled “What syncs”| Data | Endpoint | When the SDK calls it |
|---|---|---|
| Screen, product, search views; custom events; cart, wishlist; checkout | POST /api/v0/push |
trackScreenView, trackProductView, trackSearchView, trackCustomEvent, trackCheckoutSuccess, push(_:); setCart/setWishlist on a change after the first call. Sends deviceId, profile.id, sessionId, mergeProfileIds, the page token, the cart and wishlist; no page URL. |
| App push token | POST /api/v0/appPush/tokens |
registerPushToken(_:deviceType:), and automatically on every foreground and profile change when pushTokenProvider is set. FCM tokens only. Writes a Push Notification Subscribe event each time. |
| Push engagement | GET <callbackUrl> from the push data |
opened and clicked immediately on a tap; delivered batched (10 events or 30 s) when a push is presented in the foreground. |
| Banner impressions and actions, story actions | POST /api/v0/impressions, POST /api/v0/push/events |
When banners and stories are shown and used. |
| NPS answer | POST /api/v0/nps/{token}/submissions |
submitNpsResponse. |
| App Inbox | GET /api/v0/inbox/messages, GET /api/v0/inbox/unread-count, read, read-all, delete, action |
initializeInbox(), handleSyncSignal(), resume with a cache older than 5 minutes, and the client.inbox methods. |
| Products, orders paid outside the app, refunds, profile attributes, consent | not sent by the SDK | Your backend: see What your backend still sends. |
The SDK sends no e-mail, phone number, name or consent. Its privacy manifest declares no tracking and the collected data type User ID.