KlaviyoSwift 1.6.0

KlaviyoSwift 1.6.0

TestsTested
LangLanguage SwiftSwift
License MIT
ReleasedLast Release Oct 2022
SPMSupports SPM

Maintained by Klaviyo, Chris Conlon, Klaviyo Dev Team, Noah Durell.



  • By
  • Mobile @ Klaviyo

KlaviyoSwift

CI Status Swift Swift Package Manager Version License Platform

Overview

KlaviyoSwift is an SDK, written in Swift that can be integrated into your iOS App. This will allow you to message your users via push notifications from Klaviyo. In addition you will be able to take advantage of Klaviyo's identification and event tracking functionality. Once integrated, your marketing team will be able to better understand your app users' needs and send them timely messages via APNS.

Installation Options

  1. SPM
  2. CocoaPods

SPM

KlaviyoSwift is available via Swift Package Manager (SPM). Follow the steps below to get it setup.

Import the SDK

Open your project and navigate to your project’s settings. Select the Swift Packages tab and click on the add button below the packages list. Enter the URL of our Swift SDK repository (https://github.com/klaviyo/klaviyo-swift-sdk) in the text field and click Next. On the next screen, select the SDK version (1.6.0 as of this writing) and click Next.

Select the Package

Select the KlaviyoSwift package and click Finish.

CocoaPods

KlaviyoSwift is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod "KlaviyoSwift"

Then run pod install to complete the integration. The library can be kept up-to-date via pod update.

Example Usage: Event Tracking

Once integration is complete you can begin tracking events in your app. First, make sure any .swift files using the Klaviyo SDK contain the import call.

import KlaviyoSwift

Adding Klaviyo's tracking functionality requires just a few lines of code. To get started, add the following line to AppDelegate.swift, within application:didFinishLaunchingWithOptions:

Klaviyo.setupWithPublicAPIKey(apiKey: "YOUR_KLAVIYO_PUBLIC_API_KEY")

Once Klaviyo has been set up, you can begin tracking events anywhere within your application. Simply call Klaviyo's trackEvent method in the relevant location.

let klaviyo = Klaviyo.sharedInstance

let customerDictionary : NSMutableDictionary = NSMutableDictionary()
customerDictionary[klaviyo.KLPersonEmailDictKey] = "[email protected]"
customerDictionary[klaviyo.KLPersonFirstNameDictKey] = "John"
customerDictionary[klaviyo.KLPersonLastNameDictKey] = "Smith"

let propertiesDictionary : NSMutableDictionary = NSMutableDictionary()
propertiesDictionary["Total Price"] = 10.99
propertiesDictionary["Items Purchased"] = ["Milk","Cheese", "Yogurt"]
Klaviyo.sharedInstance.trackEvent(
    eventName: "Completed Checkout",
    customerProperties: customerDictionary,
    properties: propertiesDictionary
)

Example Usage: Identifying traits of People

Assuming that setupWithPublicAPIKey has already been implemented elsewhere in the application, you can identify traits about a person using trackPersonWithInfo:

let klaviyo = Klaviyo.sharedInstance

let personInfoDictionary : NSMutableDictionary = NSMutableDictionary()
personInfoDictionary[klaviyo.KLPersonEmailDictKey] = "[email protected]"
personInfoDictionary[klaviyo.KLPersonZipDictKey] = "02215"


klaviyo.trackPersonWithInfo(personDictionary: personInfoDictionary)

Argument Description

The track function can be called with anywhere between 1-4 arguments:

eventName This is the name of the event you want to track. It can be any string. At a bare minimum this must be provided to track an event.

customerProperties (optional, but recommended) This is a NSMutableDictionary of properties that belong to the person who did the action you're recording. If you do not include an $email or $id key, the event cannot be tracked by Klaviyo.

properties (optional) This is a NSMutableDictionary of properties that are specific to the event. In the above example we included the items purchased and the total price.

eventDate (optional) This is the timestamp (an NSDate) when the event occurred. You only need to include this if you're tracking past events. If you're tracking real time activity, you can ignore this argument.

Note that the only argument trackPersonWithInfo takes is a dictionary representing a customer's attributes. This is different from trackEvent, which can take multiple arguments.

Anonymous Tracking Notice

By default, Klaviyo will begin tracking unidentified users in your app once the SDK is initialized. This means you will be able to track events from users in your app without any user information provided. When an email or other primary identifier is provided Klaviyo will merge the data from the anonymous user to a new identified user.

Integrating with Shopify's Mobile SDK

If your application makes use of Shopify's Mobile Buy SDK, then Klaviyo can easily port that data into your Klaviyo account. Simply add the following line of code to your app within your Shopify completion handler or wherever your checkout code creates Shopify's BuyCheckout instance (if it is within the completion handler, it should be referenced as checkout. If you are building the checkout object manually then use whichever name you created):

Klaviyo.sharedInstance.setUpUserEmail(userEmail: checkout.email)

Special Properties

As was shown in the event tracking example, special person and event properties can be used. This works in a similar manner to the Klaviyo Analytics API. These are special properties that can be utilized when identifying a user or event. They are:

KLPersonEmailDictKey 
KLPersonFirstNameDictKey
KLPersonLastNameDictKey
KLPersonPhoneNumberDictKey
KLPersonTitleDictKey
KLPersonOrganizationDictKey
KLPersonCityDictKey
KLPersonRegionDictKey
KLPersonCountryDictKey
KLPersonZipDictKey
KLEventIDDictKey
KLEventValueDictKey

Lastly, cases where you wish to call trackEvent with only the eventName parameter and not have it result in anoynmous user tracking, you can use setUpUserEmail to configure your user's email address. By calling this once, usually upon application login, Klaviyo can track all subsequent events as tied to the given user. However, you are also free to override this functionality by passing in a customer properties dictionary at any given time:

    Klaviyo.sharedInstance.setUpUserEmail(userEmail: "[email protected]")

Sending Push Notifications

To be able to send push notifications, you must add two snippets of code to your application. One to register users for push notifications, and one that will send Klaviyo their tokens.

Add the below code to your application wherever you would like to prompt users to register for push notifications. This is often included within application:didFinishLaunchingWithOptions:, but it can be placed elsewhere as well. Make sure that whenever this code is called that the Klaviyo SDK has been configured and that setUpUserEmail: has been called. This is so that Klaviyo can match app tokens with customers.

    import UserNotifications

...

    if #available(iOS 10, *) {
        var options: UNAuthorizationOptions = [.alert, .sound, .badge]
        if #available(iOS 12.0, *) {
            options = UNAuthorizationOptions(rawValue: options.rawValue | UNAuthorizationOptions.provisional.rawValue)
        }
        UNUserNotificationCenter.current().requestAuthorization(options: options) { (granted, error) in
            // Enable / disable features based on response
        }
        UIApplication.shared.registerForRemoteNotifications()
    } else {
        let types : UIUserNotificationType = [.alert, .badge, .sound]
        let setting = UIUserNotificationSettings(types:types, categories:nil)
        UIApplication.shared.registerUserNotificationSettings(setting)
        UIApplication.shared.registerForRemoteNotifications()
    }

Add the below line of code to the application delegate file in application:didRegisterForRemoteNotificationsWithDeviceToken: (note that you might need to add this code to your application delegate if you have not done so already)

    func application(application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        Klaviyo.sharedInstance.addPushDeviceToken(deviceToken: deviceToken)
    }

That's it! Now any users that accept push notifications from your app will be eligible to receive your custom notifications. For information on how to send push notifcations through Klaviyo, please check our support docs.

Tracking Push Notifications

If you would like to track when a user opens a push notification then there is a little more code that you will need to add to your application.

In your application delegate, under application:didFinishLaunchingWithOptions: add the following:

    if let launch = launchOptions, let data = launch[UIApplicationLaunchOptionsKey.remoteNotification] as? [AnyHashable: Any] {
        Klaviyo.sharedInstance.handlePush(userInfo: data as NSDictionary)
    }

Under application:didReceiveRemoteNotification: add the following:

func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable: Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
    
    if application.applicationState == UIApplicationState.inactive || application.applicationState ==  UIApplicationState.background {
        Klaviyo.sharedInstance.handlePush(userInfo: userInfo as NSDictionary)
    }

That is all you need to do to track opens. Now once your first push notifications have been sent and been opened, you should start to see Opened Push metrics within your Klaviyo dashboard.

Authors

Katy Keuper, Chris Conlon ([email protected]), Noah Durell ([email protected])

License

KlaviyoSwift is available under the MIT license. See the LICENSE file for more info.