klaviyo-swift-sdk
Contents
Overview
The Klaviyo Swift SDK allows developers to incorporate Klaviyo's analytics and push notification functionality into their iOS applications.
The SDK assists in identifying users and tracking events via Klaviyo Client APIs.
To reduce performance overhead, API requests are queued and sent in batches.
The queue is persisted to local storage so that data is not lost if the device is offline or the app is terminated.
Once integrated, your marketing team will be able to better understand your app users' needs and send them timely messages via APNs.
Installation
-
Enable push notification capabilities in your Xcode project. The section "Enable the push notification capability" in this Apple developer guide provides detailed instructions.
-
If you intend to use rich push notifications, custom badge counts, or custom data, add a Notification Service Extension to your Xcode project. A Notification Service Extension ships as a separate bundle inside your iOS app. To add this extension to your app:
- Select File > New > Target in Xcode.
- Select the Notification Service Extension target from the iOS > Application extension section.
- Click Next.
- Specify a name and other configuration details for your app extension.
- Click Finish.
⚠️ The deployment target of your notification service extension defaults to the latest iOS version.
If this exceeds your app's minimum supported iOS version, push notifications may not display attached media on older devices.
To avoid this, ensure the extension's minimum deployment target matches that of your app. ⚠️
Set up an App Group between your main app target and your Notification Service Extension.
- Select your main app target > Signing & Capabilities
- Select + Capability (make sure it is set to All not Debug or Release) > App Groups
- Create a new App Group based on the recommended naming scheme
group.[MainTargetBundleId].[descriptor]
- In your app's
Info.plist, add a new entry for klaviyo_app_group as a String with the App Group name
- Select your Notification Service Extension target > Signing & Capabilities
- Add an App Group with the same name as the main target's App Group
- In your Notification Service Extension's
Info.plist, add a new entry for klaviyo_app_group as a String with the App Group name
Advanced: If you are using multiple push sending providers, you can determine whether a message originated from Klaviyo by importing KlaviyoSwift and using the isKlaviyoNotification extension property on UNNotifcationResponse.
Initialization
The SDK must be initialized with the short alphanumeric public API key
for your Klaviyo account, also known as your Site ID.
// AppDelegate
import KlaviyoSwift
class AppDelegate: UIResponder, UIApplicationDelegate {
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
KlaviyoSDK().initialize(with: "YOUR_KLAVIYO_PUBLIC_API_KEY")
return true
}
}
The SDK should be initialized before any other Klaviyo SDK methods are called.
Profile Identification
The SDK provides methods to identify your users as Klaviyo profiles via the Create Client Profile API.
A profile can be identified by any combination of the following:
- External ID: A unique identifier used by customers to associate Klaviyo profiles with profiles in an external system, such as a point-of-sale system. Format varies based on the external system.
- Individual's email address
- Individual's phone number in E.164 format
These above identifiers are persisted to local storage so that the SDK can keep track of the current user/profile for you when you make event requests or want to set a push token etc.
Profile identifiers can be set all at once or individually. Either way, the SDK will group and batch API calls to improve performance.
The following code demonstrates how to set profile identifiers:
// organization, title, image, location and additional properties (dictionary) can also be set using the below constructor
let profile = Profile(email: "[email protected]", firstName: "Blob", lastName: "Jr.")
KlaviyoSDK().set(profile: profile)
// or setting individual properties
KlaviyoSDK().set(profileAttribute: .firstName, value: "Blob")
KlaviyoSDK().set(profileAttribute: .lastName, value: "Jr.")
Reset Profile
To start a new profile altogether (e.g. if a user logs out) either call KlaviyoSDK().resetProfile() to clear the currently tracked profile identifiers,
or use KlaviyoSDK().set(profile: profile) to overwrite it with a new profile object.
// start a profile for Blob Jr.
let profile = Profile(email: "[email protected]", firstName: "Blob", lastName: "Jr.")
KlaviyoSDK().set(profile: profile)
// stop tracking Blob Jr.
KlaviyoSDK().resetProfile()
// start a profile for Robin Hood
let profile = Profile(email: "[email protected]", firstName: "Robin", lastName: "Hood")
KlaviyoSDK().set(profile: profile)
Anonymous Tracking Notice
Klaviyo will track unidentified users with an autogenerated ID whenever a push token is set or an event is created.
That way, you can collect push tokens and track events prior to collecting profile identifiers such as email or phone number.
When an identifier is provided, Klaviyo will merge the anonymous user with an identified user.
Automatic push token forwarding: If you enable the klaviyo_automatic_push_token_forwarding
opt-in flag (see the Migration Guide), the SDK forwards
the device push token to Klaviyo automatically once APNs delivers it to your app — which only
happens after your app calls registerForRemoteNotifications(). Because this can occur before you
call setProfile, setEmail, or setPhoneNumber, an anonymous profile will be created in Klaviyo
until you provide identifying information. This is expected behavior.
Avoiding anonymous profiles
If your app should never create a profile in Klaviyo until the user is known (email, phone number, or external ID), initialize the SDK as usual and hold back the calls below until after you call set(email:), set(phoneNumber:), or set(externalId:). This guidance was verified against SDK version 5.4.0.
- Leave automatic push token forwarding off. Do not set
klaviyo_automatic_push_token_forwarding to true in Info.plist; it is off when absent.
- Before identifying the user, do not call:
set(pushToken:)create(event:)set(profileAttribute:value:) or set(profile:) with no email, phone number, or external IDregisterForInAppForms()registerGeofencing()handleUniversalTrackingLink(_:)
- After identifying the user, call
set(pushToken:) and register for forms and geofencing as normal.
handle(notificationResponse:) and klaviyo_automatic_push_open_tracking are safe to use at any time: Klaviyo attributes push opens to the profile the notification was sent to, without creating a new one.
Things to keep in mind:
- Requests are tagged with identity when they are queued. Calling
set(email:) later does not change requests that were already queued, and queued requests persist across app launches.
- Logout and switching users.
resetProfile() keeps the push token and registers it to a new anonymous profile, so don't call it on logout. Instead:
- On logout, stop making the calls listed above, and call
unregisterFromInAppForms() and unregisterGeofencing().
- On the next login, call
set(profile:) with all of the new user's identifiers. When the identifiers differ, the SDK starts a fresh profile and sends the stored push token with the new identifiers in a single request. Calling set(email:) on its own keeps the previous user's other identifiers.
- Until someone logs in again, the previous user's profile keeps this device's push token and can still receive pushes on it.
- Existing installs. If an earlier version of your app already created anonymous profiles, those profiles stay in Klaviyo. A user who later logs in on the same device is merged into their identified profile; users who never log in remain anonymous and must be cleaned up in Klaviyo. Requests queued by the earlier version still send after the update, and users who do not update keep the old behavior.
Event tracking
The SDK provides tools for tracking events that users perform on your app via the Create Client Event API.
Below is an example of how to track an event:
// using a predefined event name
let event = Event(name: .StartedCheckoutMetric,
properties: [
"name": "cool t-shirt",
"color": "blue",
"size": "medium",
],
value: 166 )
KlaviyoSDK().create(event: event)
// using a custom event name
let customEvent = Event(name: .CustomEvent("Checkout Completed"),
properties: [
"name": "cool t-shirt",
"color": "blue",
"size": "medium",
],
value: 166)
KlaviyoSDK().create(event: customEvent)
Arguments
The create method takes an event object as an argument. The event can be constructed with the following arguments:
- [required]
name: The name of the event you want to track, as a EventName enum. A list of common Klaviyo defined event metrics can be found in Event.EventName. You can also create custom events by using the CustomEvent enum case of Event.EventName
properties: A dictionary of properties that are specific to the event. This argument is optional.value: A numeric value (Double) to associate with this event. For example, the dollar amount of a purchase.
List Subscriptions
The SDK can create a subscription and consent record for email, SMS, and Whatsapp channels based on the profile's email and phone number attributes — via the Create Client Subscription API. One of either email or phone number must be provided. WhatsApp BSUID support is coming soon.
Set the profile's email and/or phone number before subscribing. A subscribe call that requests a channel whose identifier has not been set is not sent and is dropped at replay time (a developer warning is logged).
Profiles can be opted into multiple channels — for example email marketing, SMS marketing, and SMS transactional. Specify the channel(s) to subscribe by providing a channels value on Subscription. If you include channels, only those channels will be subscribed. If you use Subscription.allAvailableMarketing (no subscriptions object is sent), subscriptions are defaulted to MARKETING.
Subscriptions to push notifications are not created through this API — use the existing set(pushToken:) registration path instead.
KlaviyoSDK().set(email: "[email protected]")
KlaviyoSDK().set(phoneNumber: "+15005550006")
// Subscribe to a list, defaulting to MARKETING consent for every channel
// available from the identifiers you've set:
KlaviyoSDK().create(subscription: .allAvailableMarketing(listId: "XXXXXX"))
// Or request specific channels and consent types:
let subscription = Subscription(
listId: "XXXXXX",
channels: .init(
email: .marketing,
sms: [.marketing, .transactional],
whatsapp: [.marketing, .transactional]
),
customSource: "iOS in-app form"
)
KlaviyoSDK().create(subscription: subscription)
Arguments
The create(subscription:) method takes a Subscription. Construct one with either:
Subscription.allAvailableMarketing(listId:customSource:) — omits the subscriptions object so the API defaults to MARKETING consent for every channel available from the profile's identifiers.Subscription(listId:channels:customSource:) — sends a subscriptions object for only the channels you name. channels is required on this initializer so a broad grant is never the result of an omitted argument.
Subscription.Channels takes optional email, sms, and whatsapp values. Each channel exposes only the consent sub-types the API supports for it — pass one value (e.g. .marketing) or multiple (e.g. [.marketing, .transactional]):
The consent types per channel include:
email: .marketing, .openTrackingsms / whatsapp: .marketing, .transactional
customSource is an optional free-text label describing where the signup originated (e.g. a form or screen name), stored as the consent record's source.
Push Notifications
Prerequisites
Which option should I use?
Choose Option A for a minimal-boilerplate integration — the SDK intercepts APNs callbacks and tracks push opens automatically. No UNUserNotificationCenterDelegate code required.
Choose Option B if you need direct control over willPresent behavior, are chaining multiple push notification SDKs and want to manage the delegate chain yourself, or have a hybrid flow that requires custom delegate logic.
Option A — Automatic integration
The SDK can intercept APNs device-token callbacks and UNUserNotificationCenter delegate calls automatically, so you don't need to implement didRegisterForRemoteNotificationsWithDeviceToken or any UNUserNotificationCenterDelegate methods in your app delegate.
Step 1 — Enable automatic push behavior in Info.plist
Automatic push tracking and automatic device-token forwarding are two independent opt-in flags.
For the fully automatic, no-boilerplate integration, enable both:
<!-- Injects a notification-delegate proxy that tracks push opens automatically -->
<key>klaviyo_automatic_push_open_tracking</key>
<true/>
<!-- Forwards the APNs device token to Klaviyo automatically (no didRegister... code needed) -->
<key>klaviyo_automatic_push_token_forwarding</key>
<true/>
Each flag can be enabled on its own; enable only the behavior you want. If you enable push tracking without token forwarding, you must still collect the device token yourself and forward it in the .set(pushToken:) method (see Option B), otherwise no token is registered with Klaviyo. Conversely, if you enable token forwarding without push tracking, the device token is forwarded automatically, but you must implement push-open tracking yourself (see Tracking Open Events).
Step 2 — Initialize the SDK and request push authorization
import KlaviyoSwift
import UserNotifications
func application(
_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
KlaviyoSDK().initialize(with: "YOUR_KLAVIYO_PUBLIC_API_KEY")
registerForPushNotifications()
return true
}
func registerForPushNotifications() {
// Register with APNs immediately so a device token is available regardless of
// notification permission status. The SDK intercepts the token callback automatically.
UIApplication.shared.registerForRemoteNotifications()
let center = UNUserNotificationCenter.current()
let options: UNAuthorizationOptions = [.alert, .sound, .badge]
// To use provisional push notifications (no user prompt), use:
// let options: UNAuthorizationOptions = [.alert, .sound, .badge, .provisional]
center.requestAuthorization(options: options) { _, error in
if let error = error {
print("Push authorization error: \(error)")
}
// Irrespective of the authorization status call `registerForRemoteNotifications` here so that
// the `didRegisterForRemoteNotificationsWithDeviceToken` delegate is called. Doing this
// will make sure that Klaviyo always has the latest push authorization status.
DispatchQueue.main.async {
UIApplication.shared.registerForRemoteNotifications()
}
}
}
ℹ️ Silent push (content-available) is not intercepted automatically. If you use silent or background pushes, implement application(_:didReceiveRemoteNotification:fetchCompletionHandler:) in your app delegate — see Silent Push Notifications.
Foreground presentation
With klaviyo_automatic_push_open_tracking enabled and no UNUserNotificationCenterDelegate of your own, the SDK shows a visible foreground banner by default ([.list, .banner, .badge, .sound] on iOS 14+, [.alert, .badge, .sound] on iOS 13) — you don't need to implement willPresent just to get a banner in the foreground.
For a runnable reference, see the SPMExampleAutomatic target.
Once your first push notifications are sent and opened, you should start to see Opened Push metrics in your Klaviyo dashboard.
Option B — Manual integration
Use this path when you need explicit control over the notification delegate chain — for example, to customize willPresent behavior, chain multiple notification SDKs manually, or integrate with a hybrid notification flow.
Collecting Push Tokens
In order to send push notifications to your users, you must collect their push tokens and register them with Klaviyo.
This is done via the KlaviyoSDK().set(pushToken:) method, which registers a push token and current authorization state
via the Create Client Push Token API.
Request Push Notification Permission
You can add the permission request code anywhere in your application where it makes sense to prompt users for this permission.
Apple provides some guidelines
on the best practices for when and how to ask for this permission. The following example demonstrates how to request push permissions
within the application:didFinishLaunchingWithOptions:
method in the application delegate file. However, it's worth noting that this may not be the ideal location as it could interrupt the app's startup experience.
After setting a push token, the Klaviyo SDK will automatically track changes to
the user's notification permission whenever the application is opened or resumed from the background.
import KlaviyoSwift
import UserNotifications
func application(
_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
KlaviyoSDK().initialize(with: "YOUR_KLAVIYO_PUBLIC_API_KEY")
registerForPushNotifications()
return true
}
func registerForPushNotifications() {
// Register with APNs immediately so a device token is available regardless of
// notification permission status. The token is forwarded to Klaviyo via
// didRegisterForRemoteNotificationsWithDeviceToken below.
UIApplication.shared.registerForRemoteNotifications()
let center = UNUserNotificationCenter.current()
center.delegate = self
let options: UNAuthorizationOptions = [.alert, .sound, .badge]
// To use provisional push notifications (no user prompt), use:
// let options: UNAuthorizationOptions = [.alert, .sound, .badge, .provisional]
center.requestAuthorization(options: options) { _, error in
if let error = error {
print("error = ", error)
}
// Irrespective of the authorization status call `registerForRemoteNotifications` here so that
// the `didRegisterForRemoteNotificationsWithDeviceToken` delegate is called. Doing this
// will make sure that Klaviyo always has the latest push authorization status.
DispatchQueue.main.async {
UIApplication.shared.registerForRemoteNotifications()
}
}
}
func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
KlaviyoSDK().set(pushToken: deviceToken)
}
Receiving Push Notifications
Tracking Open Events
When a user taps on a push notification, Implement userNotificationCenter:didReceive:withCompletionHandler
and userNotificationCenter:willPresent:withCompletionHandler in your application delegate to handle receiving push notifications
when the app is in the background and foreground respectively.
Below is an example of how to handle push notifications in your app delegate:
// be sure to set the UNUserNotificationCenterDelegate to self in the didFinishLaunchingWithOptions method (refer the requesting push notification permission section above for more details on this)
extension AppDelegate: UNUserNotificationCenterDelegate {
// below method will be called when the user interacts with the push notification
func userNotificationCenter(
_ center: UNUserNotificationCenter,
didReceive response: UNNotificationResponse,
withCompletionHandler completionHandler: @escaping () -> Void) {
// If this notification is Klaviyo's notification we'll handle it
// else pass it on to the next push notification service to which it may belong
let handled = KlaviyoSDK().handle(notificationResponse: response, withCompletionHandler: completionHandler)
if !handled {
completionHandler()
}
}
// below method is called when the app receives push notifications when the app is the foreground
func userNotificationCenter(
_ center: UNUserNotificationCenter,
willPresent notification: UNNotification,
withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
if #available(iOS 14.0, *) {
completionHandler([.list, .banner])
} else {
completionHandler([.alert])
}
}
}
ℹ️ To ensure that push notifications are handled properly when they contain deep links (via a custom URL scheme or via a universal link), please refer to the Deep Linking section below.
Once your first push notifications are sent and opened, you should start to see Opened Push metrics within your Klaviyo dashboard.
For runnable reference examples, see SPMExample or CocoapodsExample.
Rich Push (Images & Videos)
ℹ️ Rich push notifications are supported in SDK version 2.2.0 and higher
Rich Push is the ability to add images (png, jpg, gif) and videos (mpeg, mp4) to push notification messages. Once the steps
in the Installation section are complete, you should have a notification service extension in your
project setup with the code from the KlaviyoSwiftExtension. Below are instructions on how to test rich push notifications.
Testing rich push notifications
- To test rich push notifications, you will need three things:
- A push notification payload that resembles what Klaviyo would send to you. See the following examples:
Image example:
{
"aps": {
"alert": {
"title": "Sample title for a Klaviyo push notification",
"body": "Sample body for a Klaviyo push notification"
},
"mutable-content": 1
},
"rich-media": "https://picsum.photos/200/300.jpg",
"rich-media-type": "jpg"
}
Video example:
{
"aps": {
"alert": {
"title": "Video Push Notification",
"body": "Check out this video content"
},
"mutable-content": 1
},
"rich-media": "https://example.com/videos/mp4/your_video.mp4",
"rich-media-type": "mp4"
}
- A real device's push notification token. This can be printed out to the console from the
didRegisterForRemoteNotificationsWithDeviceToken method in AppDelegate.
Once you have these three things, you can then use the push notifications tester and send a local push notification to make sure that everything was set up correctly.
Badge Count
ℹ️ Setting or incrementing the badge count is available in SDK version 4.1.0 and higher
Klaviyo supports setting or incrementing the badge count when you send a push notification. For this functionality to work, you must set up the Notification Service Extension and an App Group as outlined under the Installation section.
Autoclearing
By default, the Klaviyo SDK automatically clears the badge count on app open. If you want to disable this behavior, add a new entry for klaviyo_badge_autoclearing as a Boolean set to NO in your app's Info.plist. You can re-enable automatically clearing badges by setting this value to YES.
Handling Other Badging Sources
Klaviyo SDK will automatically handle the badge count associated with Klaviyo pushes. If you need to manually update the badge count to account for other notification sources, use the KlaviyoSDK().setBadgeCount(:) method, which will update the badge count and keep it in sync with the Klaviyo SDK. This method should be used instead of (rather than in addition to) setting the badge count using UNUserNotificationCenter and/or UIApplication methods.
Silent Push Notifications
Silent push notifications (also known as background pushes) allow your app to receive payloads from Klaviyo without displaying a visible alert to the user. These are typically used to trigger background behavior, such as displaying content, personalizing the app interface, or downloading new information from a server.
ℹ️ Silent push support is available by default. The Klaviyo SDK does not provide specific handling for silent push notifications. See enable the remote notifications capability and receive background notifications for more details.
To handle silent push notifications in your app, you'll need to implement the appropriate delegate methods yourself. Here's an example of how to handle silent push notifications:
func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
// Access custom key-value pairs from the top level
if let customData = userInfo["key_value_pairs"] as? [String: String] {
// Process your custom key-value pairs here
for (key, value) in customData {
print("Key: \(key), Value: \(value)")
}
completionHandler(.newData)
} else {
print("No key_value_pairs found in notification")
completionHandler(.noData)
}
}
ℹ️ Silent push notifications are not supported by the iOS simulator. To test silent push notifications, please use a real device.
Handling background notifications (content-available)
Klaviyo can send a standard push (title, body, and other visible notification UI) whose APNs payload also includes content-available: 1. That is different from a silent push: silent pushes never show an alert, while this is a normal user-visible notification that additionally asks iOS to wake your app in the background so you can refresh data or run other work from the same userInfo.
You still handle the visible notification through UNUserNotificationCenterDelegate when the message is presented or opened. The background wake for content-available uses the same app delegate path as silent push: application(_:didReceiveRemoteNotification:fetchCompletionHandler:). Implement that method (see the example under Silent Push Notifications) and finish by calling completionHandler with .newData, .noData, or .failed when your background work completes. Use the same Background Modes / remote-notification setup called out in that section (Apple’s background updates guide).
ℹ️ Background wakes are best-effort and may be throttled. As with silent push notifications, test this functionality on a physical device because the Simulator does not support the full remote-notification background path.
Custom Data
Klaviyo messages can also include key-value pairs (custom data) for both standard and silent push notifications. You can access these key-value pairs using the key_value_pairs key on the userInfo dictionary associated with the notification (for silent pushes, see the example above; for standard pushes, see NotificationService.swift in the example app). This enables you to extract additional information from the push payload and handle it appropriately - for instance, by triggering background processing, logging analytics events, or dynamically updating app content.
Push Action Buttons
ℹ️ Push Action Buttons is supported in SDK version 5.3.0 and higher
Klaviyo supports the ability to add custom push action buttons to push notification messages. These buttons can show custom text and can deep link or open your app when tapped. If a button is tapped, the open push event includes the corresponding button information. No additional setup is needed to support push action buttons. Push notifications can include a maximum of 3 valid buttons.
To test push action buttons, use Apple's official push notification console or a third party software such as this and send a payload with this format to resemble what the SDK would receive from Klaviyo.
{
"aps": {
"alert": {
"title": "New Arrivals Just for You",
"body": "Check out our latest collection"
},
"mutable-content": 1,
"sound": "default"
},
"body": {
"_k": { },
"action_buttons": [
{
"id": "someId",
"label": "Go to Settings",
"action": "deep_link",
"url": "klaviyotest://settings"
},
{
"id": "someOtherId",
"label": "Open App",
"action": "open_app"
}
]
}
}
Deep Linking
Klaviyo Deep Links allow you to navigate to a particular page within your app in response to the user opening a push notification, tapping an In-App Form link, or by tapping a universal link from outside of the app. The Klaviyo Swift SDK supports deep linking using either URL schemes or universal links.
Adding link-handling logic
We recommend that you create a helper method to contain the link handling logic. This may include parsing a URL into its components, then using those components to navigate to the appropriate screen in the app. By encapsulating this logic within a helper method, you can centralize your logic and reduce duplication of code as you complete the rest of your deep linking setup via url schemes and universal links.
As an example, you may add a method like the following within your AppDelegate or SceneDelegate:
func handleDeepLink(url: URL) {
// parse the URL into its components by creating a URLComponents object; i.e.,
// let components = URLComponents(url: url, resolvingAgainstBaseURL: true)
// extract the path and/or the query items from the URL components
// use your app's navigation logic to handle routing to the appropriate
// screen given the extracted path and/or query items
}
Handling URL Schemes
ℹ️ Your app needs to use version 1.7.2 at a minimum in order for the below steps to work.
URL schemes are a simple way to enable deep linking in your app. Here's how to set them up:
Step 1: Register the URL scheme
First, you need to register your URL scheme with iOS. This tells the operating system that your app can handle URLs with that scheme. You do this by adding a CFBundleURLTypes entry to your app's Info.plist:
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleTypeRole</key>
<string>Editor</string>
<key>CFBundleURLName</key>
<string>{your_bundle_identifier}</string>
<key>CFBundleURLSchemes</key>
<array>
<string>{your_url_scheme}</string>
</array>
</dict>
</array>
Replace {your_url_scheme} with the scheme you want your app to respond to, and {your_bundle_identifier} with your app's bundle identifier. You can also add this entry from the Info tab of your app target in Xcode. For detailed instructions, please see "Register your URL scheme" in Apple's official documentation.
CFBundleURLTypes is what tells iOS to route your URL scheme to your app.
Step 2: Handle the deep links in your app
Finally, you need to add code to your app to process incoming URLs and navigate to the correct content. The implementation differs depending on whether your app uses SwiftUI or UIKit for its lifecycle.
For SwiftUI Apps
If your app uses the SwiftUI app life cycle, you should use the onOpenURL(perform:) view modifier. Attach the modifier to the root view in your main App scene.
@main
struct MyApplication: App {
var body: some Scene {
WindowGroup {
ContentView()
.onOpenURL { url in
// handle the URL
// if you created a helper method (see "Adding link-handling logic", above), call it here
}
}
}
}
For UIKit Apps
If your app uses the UIKit app life cycle, you will handle incoming URLs in your SceneDelegate or AppDelegate.
For detailed instructions and code examples for the UIKit approach, please refer to Apple's official documentation: Handling incoming URLs
Handling Universal Links
ℹ️ Full trackable universal links support is available in SDK version 5.1.0 and higher.
Klaviyo supports embedding universal links with click tracking in emails. To ensure universal links are properly tracked as profile events and your app opens and processes the links correctly, you need to configure your app to handle them. At a high level, the process works like this:
- A marketer includes a universal link in a Klaviyo email. Klaviyo automatically wraps it in a unique, trackable URL, which we call a universal tracking link.
- When a user clicks the link on a device with your app installed, iOS delivers the wrapped link to your application.
- Your app passes this universal tracking link to the Klaviyo SDK by calling the
handleUniversalTrackingLink(_:) method.
- The SDK records a click event on the user's profile, and unwraps the universal tracking link into the original universal link.
- The SDK then processes the original link in one of two ways:
- Preferred: It's passed to a custom deep link handler you register with the SDK. This gives you full control over the navigation logic.
- Fallback: It's passed back to your
AppDelegate or SceneDelegate, invoking the logic you've written there to handle URLs.
Note that the instructions below will also enable your app to handle standard universal links (i.e., links that are not Klaviyo universal tracking links)
Setup
Follow these steps to configure your app to handle Klaviyo universal tracking links.
⚠️ Note that these instructions diverge somewhat from Apple's developer documentation on supporting universal links.
Step 1: Configure Universal Links in your Klaviyo account
Follow our guide on setting up universal links in your Klaviyo account dashboard.
Step 2: Add the Associated Domains Entitlement
Follow Apple's developer documentation to add the associated domains entitlement to your app.
You must add the universal link domain you configured in step 1. The domain should be prefixed with applinks:; for example:
applinks:mycompany.com
Step 3: (Recommended) Register a Deep Link Handler
Registering a handler provides a reliable, centralized place to manage incoming links from Klaviyo and simplifies your app's logic.
Registering a handler tells the Klaviyo SDK how to handle deep links. Although we have a fallback mechanism in case you don't register a handler, registering a handler increases code stability and resiliency against possible iOS changes, and can help reduce your code's complexity.
In the same location where you initialize the SDK, call registerDeepLinkHandler(_:) with a closure that handles the URL.
For example:
import KlaviyoSwift
import KlaviyoForms
...
// Chained with initialization
KlaviyoSDK()
.initialize(with: "YOUR_KLAVIYO_PUBLIC_API_KEY")
.registerDeepLinkHandler { url in
// Your code to parse the URL and use the result to navigate to a specific screen
// if you created a helper method (see "Adding link-handling logic", above), call it here
}
// **Or** called separately after initialization
KlaviyoSDK().registerDeepLinkHandler { url in
// Your code to parse the URL and use the result to navigate to a specific screen
// if you created a helper method (see "Adding link-handling logic", above), call it here
}
Step 4: Pass the universal tracking link into the Klaviyo SDK
You need to pass the incoming universal tracking link URL from the NSUserActivity object to the Klaviyo SDK by calling the Klaviyo SDK's handleUniversalTrackingLink(_:) method. This method returns true synchronously if the link is a valid Klaviyo universal tracking link. If it returns false, the link is not a Klaviyo universal tracking link, and you should handle the non-Klaviyo link as appropriate.
If your app uses an AppDelegate
See the next section if your app uses a SceneDelegate
When the user opens a Klaviyo universal tracking link, the system will deliver the link to the AppDelegate's application(_:continue:restorationHandler:) method. Within the body of this method, you'll need to extract the universal tracking link from the NSUserActivity, then pass the link to the Klaviyo SDK by calling KlaviyoSDK().handleUniversalTrackingLink(<extracted URL>).
This code shows an example of one way to implement the application(_:continue:restorationHandler:) method:
func application(
_ application: UIApplication,
continue userActivity: NSUserActivity,
restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
) -> Bool {
// Get the URL from the incoming user activity.
guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
let incomingURL = userActivity.webpageURL
else {
return false
}
if KlaviyoSDK().handleUniversalTrackingLink(incomingURL) {
return true
} else {
// handle a link that's not a Klaviyo universal tracking link
// if you created a helper method (see "Adding link-handling logic", above), call it here
}
}
If you have opted into scenes
If your app uses a SceneDelegate, the system delivers the Klaviyo universal tracking link to one of two SceneDelegate methods, depending on the App's state.
If the app is terminated, the system delivers the universal tracking link to the scene(_:willConnectTo:options:) delegate method after launch.
If the app is running or in the background, the system will deliver the universal tracking link to the scene(_:continue:) delegate method.
Within the body of both of these methods, you'll need to extract the universal tracking link from the NSUserActivity, then pass the link to the Klaviyo SDK by calling KlaviyoSDK().handleUniversalTrackingLink(<extracted URL>).
As an example, your implementation may look something like this:
func scene(
_ scene: UIScene,
willConnectTo session: UISceneSession,
options connectionOptions: UIScene.ConnectionOptions
) {
// Get the URL from the incoming user activity.
guard let userActivity = connectionOptions.userActivities.first,
userActivity.activityType == NSUserActivityTypeBrowsingWeb,
let incomingURL = userActivity.webpageURL
else {
return
}
if KlaviyoSDK().handleUniversalTrackingLink(incomingURL) {
return
} else {
// handle a link that's not a Klaviyo universal tracking link
// if you created a helper method (see "Adding link-handling logic", above), call it here
}
}
...
func scene(
_ scene: UIScene,
continue userActivity: NSUserActivity
) {
// Get the URL from the incoming user activity.
guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
let incomingURL = userActivity.webpageURL
else {
return
}
if KlaviyoSDK().handleUniversalTrackingLink(incomingURL) {
return
} else {
// handle a link that's not a Klaviyo universal tracking link
// if you created a helper method (see "Adding link-handling logic", above), call it here
}
}
Validation
To validate your deep linking setup, you can send push notifications from the Klaviyo Push editor within the Klaviyo website. You can configure the push notification to trigger a deep link via either a URL scheme or a universal link. When you send the push notification and open it on your mobile device, validate that the link is handled according to the logic you established in "Adding link-handling logic".
To validate that Klaviyo universal tracking links are working properly, you'll need to create a test email campaign through the Klaviyo website, and include in the email a universal link matching the scheme you congfigured when you set up universal links in your Klaviyo account. Send the campaign, and copy the link from the email. Open the link on your mobile device and validate that the link is handled according to the logic you established in "Adding link-handling logic".
Additionally, you can locally trigger a deep link using the following command in the terminal:
xcrun simctl openurl booted {your_URL_here}
In-App Forms
ℹ️ In-App Forms support is available in SDK version 4.2.0 and higher
In-App Forms are messages displayed to mobile app users while they are actively using an app. You can create new In-App Forms in a drag-and-drop editor in the Sign-Up Forms tab in Klaviyo. Follow the instructions in this section to integrate forms with your app. The SDK will
display forms according to their targeting and behavior settings and collect delivery and engagement analytics automatically.
In-App Forms supports advanced targeting and segmentation. In your Klaviyo account, you can configure forms to target or exclude specific segments of profiles and configure event-based triggers and delays. See the table below to understand available features by SDK version.
Prerequisites
- Imported
KlaviyoSwift and KlaviyoForms SDK modules and adding it to the app target.
- We strongly recommend using the latest version of the SDK to ensure compatibility with the latest In-App Forms features. The minimum SDK version supporting In-App Forms is
4.2.0, and a feature matrix is provided below. Forms that leverage unsupported features will not appear in your app until you update to a version that supports those features.
- Please read the migration guide if you are upgrading from 4.2.0-4.2.1 to understanding changes to In-App Forms behavior.
| Feature | Minimum SDK Version |
|---|
| Basic In-App Forms | 4.2.0 |
| Time Delay | 5.0.0 |
| Audience Targeting | 5.0.0 |
| Event Triggers | 5.1.0 |
Setup
To configure your app to display In-App Forms, call Klaviyo.registerForInAppForms() after initializing the SDK with your public API key. Once registered, the SDK may launch an overlay view at any time to present a form according to its targeting and behavior settings configured in your Klaviyo account.
For the best user experience, we recommend registering after any splash screen or loading animations have completed. Depending on your app's architecture, this might be in your AppDelegate's application(_:didFinishLaunchingWithOptions:) method.
import KlaviyoSwift
import KlaviyoForms
...
// if registering in the same location where you're initializing the SDK
KlaviyoSDK()
.initialize(with: "YOUR_KLAVIYO_PUBLIC_API_KEY")
.registerForInAppForms()
// if registering elsewhere after `KlaviyoSDK` is initialized
KlaviyoSDK().registerForInAppForms()
Note that the In-App Forms will automatically respond if/when the API key and/or the profile data changes. You do not need to re-register.
In-App Forms Session Configuration
A "session" is considered to be a logical unit of user engagement with the app, defined as a series of foreground interactions that occur within a continuous or near-continuous time window. This is an important concept for In-App Forms, as we want to ensure that a user will not see a form multiple times within a single session.
A session will time out after a specified period of inactivity. When a user launches the app, if the time between the previous interaction with the app and the current one exceeds the specified timeout, we will consider this a new session.
This timeout has a default value of 3600 seconds (1 hour), but it can be customized. To do so, pass an InAppFormsConfig object to the registerForInAppForms() method. For example, to set a session timeout of 30 minutes:
import KlaviyoForms
// e.g. to configure a session timeout of 30 minutes
let config = InAppFormsConfig(sessionTimeoutDuration: 1800)
KlaviyoSDK().registerForInAppForms(configuration: config)
Unregistering from In-App Forms
If at any point you need to prevent the SDK from displaying In-App Forms, e.g. when the user logs out, you may call:
import KlaviyoForms
KlaviyoSDK().unregisterFromInAppForms()
Note that after unregistering, the next call to registerForInAppForms() will be considered a new session by the SDK.
Personalized Forms Authentication
ℹ️ Personalization is currently in limited availability for select Klaviyo customers. Please contact your CSM to be enrolled.
ℹ️ Personalization is available in SDK version 5.5.0 and higher.
Personalized In-App Forms show content from the signed-in user's Klaviyo profile. Your app proves who the user is with a JSON Web Token (JWT).
Set up an authenticated endpoint on your backend that mints a fresh JWT for the signed-in user. Keep the signing credentials on your server. The JWT must carry valid iat and exp claims and the user's matching email claim. Keep the SDK's profile identifiers in sync with the signed-in user (see Profile Identification).
After initializing the SDK, register a provider that fetches a token from your backend:
KlaviyoSDK().registerAuthTokenProvider {
// Replace with your own call. Apply a timeout to the request.
try await authService.fetchKlaviyoJWT()
}
Register the provider once and keep it registered across profile changes.
On logout, clear the SDK profile:
KlaviyoSDK().resetProfile()
A form that is already open keeps its token until it expires, whether you call resetProfile() or unregisterAuthTokenProvider(). unregisterAuthTokenProvider() turns personalization off. It is not a logout.
Provider requirements
The SDK does not time out your provider, so your code must:
- Return or throw exactly once. Return the JWT or throw an error for each call to the provider.
The SDK calls the provider whenever it needs a fresh token, on a background task.
- Report errors by throwing. The SDK catches errors thrown from the provider, so throw instead of
returning an empty or placeholder token.
- Bound your own work. Apply a timeout to every network call. A provider that never returns blocks later token fetches until you register, unregister or reset the profile.
- Fail fast. If you cannot produce a token, for example when no user is signed in, throw instead of waiting or retrying.
- Pass on the original network error. The SDK retries after reconnect when the provider throws a
URLError, so rethrow the original URLError without wrapping it.
Monitoring Form Lifecycle Events
ℹ️ Form lifecycle events are available in SDK version 5.3.0 and higher
You can register a handler to track when forms are shown, dismissed, or when users tap call-to-action buttons. This is useful for sending form engagement data to third-party analytics platforms like Amplitude, Segment, or Mixpanel.
import KlaviyoForms
KlaviyoSDK().registerFormLifecycleHandler { event in
switch event {
case .formShown(let formId, let formName):
// Track when a form is displayed
Analytics.track("Klaviyo Form Shown", properties: [
"formId": formId,
"formName": formName
])
case .formDismissed(let formId, let formName):
// Track when a form is dismissed
Analytics.track("Klaviyo Form Dismissed", properties: [
"formId": formId,
"formName": formName
])
case .formCtaClicked(let formId, let formName, let buttonLabel, let deepLinkUrl):
// Track when a user taps a call-to-action button
Analytics.track("Klaviyo Form CTA Clicked", properties: [
"formId": formId,
"formName": formName,
"buttonLabel": buttonLabel,
"deepLinkUrl": deepLinkUrl.absoluteString
])
}
}
The handler is called on the main thread and will receive events for all form interactions. To unregister the handler:
KlaviyoSDK().unregisterFormLifecycleHandler()
Note: The handler is optional and does not affect normal form functionality. Forms will continue to display and track analytics in Klaviyo regardless of whether a handler is registered.
Geofencing
Geofencing support is available in SDK version 5.2.0 and higher.
Geofencing allows you to trigger events when users enter or exit geographic regions. The Klaviyo SDK monitors geofences configured in your Klaviyo account and automatically tracks geofence enter and exit events. The SDK automatically handles geofence synchronization with your Klaviyo account—when you add, update, or remove geofences in Klaviyo, the SDK will automatically sync these changes on the next app launch or when the API key changes.
⚠️ Important: Geofencing requires "Always" location authorization and "Precise" accuracy. The SDK will only begin monitoring geofences once the user grants these permissions. By default, if the user grants location authorization, it will be with "Precise" accuracy unless the user changes it otherwise. If the user only grants or at any point downgrades to "When In Use" permission, geofencing will not be active.
Prerequisites
- Configure location permissions and background modes in your app's
Info.plist.
- Request "Always" location authorization from users.
Setup
Step 1: Configure Info.plist
Add the following keys to your app's Info.plist:
- Location Usage Descriptions (required):
NSLocationWhenInUseUsageDescription: Your location helps the app offer location-based features and notifications while you’re using it.NSLocationAlwaysAndWhenInUseUsageDescription: This app uses your location in the background to detect when you enter or leave specific areas and send you relevant notifications.
<key>NSLocationWhenInUseUsageDescription</key>
<string>This app needs location access to show your current location and help you find nearby locations.</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>This app needs location access to monitor geofences and provide location-based notifications when the app is in the background.</string>
- Background Modes (required):
- Add
location to the UIBackgroundModes array to enable background location updates.
<key>UIBackgroundModes</key>
<array>
<string>location</string>
</array>
Note: Adding the location usage keys and location background mode to your Info.plist will require additional justification when submitting to the App Store. Refer to the guidelines outlined by Apple in sections 2.5.4 and 5.1.5.
Step 2: Request Location Authorization
Request location authorization according to Apple's guidelines. Apple recommends first requesting "When In Use" authorization, and then later requesting "Always" authorization. We highly suggest following Apple's best practices for requesting location permissions, and you can see an example of how this call is set up here.
Step 3: Register for Geofencing
Call registerGeofencing() as early as possible in your app's lifecycle, ideally after initializing the SDK. This method will:
- Begin monitoring geofences configured in your Klaviyo account
- Start tracking geofence enter and exit events
// AppDelegate
import KlaviyoSwift
import KlaviyoLocation
class AppDelegate: UIResponder, UIApplicationDelegate {
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
KlaviyoSDK()
.initialize(with: "YOUR_KLAVIYO_PUBLIC_API_KEY")
.registerGeofencing()
return true
}
}
We highly recommend registering for geofencing in didFinishLaunchingWithOptions to ensure all enter/exit events are delivered to Klaviyo no matter the app state (backgrounded, terminated).
Unregistering from Geofencing
If you need to stop monitoring geofences, you can call unregisterGeofencing():
import KlaviyoSwift
import KlaviyoLocation
KlaviyoSDK().unregisterGeofencing()
Additional Details
Sandbox Support
ℹ️ Sandbox support is available in SDK version 2.2.0 and higher
Apple has two environments with push notification support - Production and Sandbox.
The Production environment supports sending push notifications to real users when an app is published in the App Store or TestFlight.
In contrast, Sandbox applications that support push notifications are those signed with iOS Development Certificates, instead of iOS Distribution Certificates.
Sandbox acts as a staging environment, allowing you to test your applications in a environment similar to but distinct from Production without having to worry about sending messages to real users.
Our SDK supports the use of Sandbox for push as well.
Klaviyo's SDK will determine and store the environment that your push token belongs to and communicate that to our backend,
allowing your tokens to route sends to the correct environments. There is no additional setup needed.
As long as you have deployed your application to Sandbox with our SDK employed to transmit push tokens to our backend,
the ability to send and receive push on these Sandbox applications should work out-of-the-box.
Logging
The SDK logs diagnostic information to the system console via os.Logger. Logging is enabled by default
and can be toggled at runtime:
KlaviyoSDK().setLoggingEnabled(false) // silence all SDK logging
KlaviyoSDK().setLoggingEnabled(true) // re-enable logging
KlaviyoSDK().isLoggingEnabled // check the current setting
Disabling logging silences all log output from the KlaviyoSwift, KlaviyoCore, KlaviyoForms,
and KlaviyoLocation modules. It does not affect KlaviyoSwiftExtension, which runs in a separate
app-extension process.
SDK Data Transfer
Starting with version 1.7.0, the SDK will cache incoming data and flush it back to the Klaviyo API on an interval.
The interval is based on the network link currently in use by the app. The table below shows the flush interval used for each type of connection:
| Network | Interval |
|---|
| WWAN/Wifi | 10 seconds |
| Cellular | 30 seconds |
Connection determination is based on notifications from our reachability service.
When there is no network available, the SDK will cache data until the network becomes available again.
All data sent by the SDK should be available shortly after it is flushed by the SDK.
Retries
The SDK will retry API requests that fail under certain conditions. For example, if a network timeout occurs, the request will be retried on the next flush interval.
In addition, if the SDK receives a rate limiting error 429 from the Klaviyo API, it will use exponential backoff with jitter to retry the next request.
Contributing
See the contributing guide to learn how to contribute to the Klaviyo Swift SDK.
We welcome your feedback in the issues section of our public GitHub repository.
License
KlaviyoSwift is available under the MIT license. See the LICENSE file for more info.
