KlaviyoSwift

概述

KlaviyoSwift是一个用Swift编写的SDK，可以集成到您的iOS应用中。该SDK可以让您通过推送通知与客户互动。此外，您还可以利用Klaviyo的身份验证和事件跟踪功能。一旦集成，您的营销团队将能够更好地理解您的应用用户的需求，并通过APNs及时向他们发送消息。

安装选项

使用SPM安装
使用Cocoapods安装

使用 SPM 安装

KlaviyoSwift 通过 Swift 包管理器 (SPM) 提供。请按照以下步骤安装：

打开您的项目并导航到项目设置。
选择 Swift Packages 选项卡，并在包列表下方点击添加按钮。
在文本框中输入 Swift SDK 仓库的 URL https://github.com/klaviyo/klaviyo-swift-sdk 并点击 下一步。
在下一屏，选择最新的 SDK 版本并点击 下一步。
选择 KlaviyoSwift 包。
点击完成。

使用 CocoaPods 安装

KlaviyoSwift 通过 CocoaPods 提供。

要安装，将以下行添加到您的 Podfile 中

pod "KlaviyoSwift"

运行 pod install 以完成集成。

通过 pod update 保持库的更新。

事件跟踪

SDK 安装后，您可以在应用中开始跟踪事件。

请确保任何使用 Klaviyo SDK 的 .swift 文件都包含以下导入调用

import KlaviyoSwift

要添加 Klaviyo 的跟踪功能，在 AppDelegate.swift 中的 application:didFinishLaunchingWithOptions 内包含以下行

KlaviyoSDK().initialize(with: "YOUR_KLAVIYO_PUBLIC_API_KEY")

通过在 relevant 位置调用相关方法中的 create(event:) 方法，在应用程序中的任何地方开始跟踪事件。

let event = Event(name: .StartedCheckout, properties: [
    "Total Price": 10.99,
    "Items Purchased": ["Hot Dog", "Fries", "Shake"]
], identifiers: .init(email: "[email protected]"),
profile: [
    "$first_name": "Blob",
    "$last_name": "Jr"
], value: 10.99)

KlaviyoSDK().create(event: event)

参数

create 方法接受一个事件对象作为参数。事件可以使用以下参数进行构建：

name：您要跟踪的事件名称，作为一个 EventName 枚举类型。默认情况下提供了一些常用的事件名称。如果您需要记录不同名称的事件，可以使用自定义的 CustomEvent 字符串。此参数是跟踪事件的必要条件。
profile：一个包含属于您跟踪行动执行者的属性的字典。包括 $email、$phone_number 或 $id 键可以将事件与 Klaviyo 的特定配置文件关联起来。此外，SDK 将保留这些属性以用于未来 SDK 调用，因此如果之前未设置标识符，则将使用这些标识符来记录事件。此参数是可选的。
properties：一个包含特定于事件的属性的字典。此参数是可选的。
time：这是事件发生的时间戳，作为一个 Date 对象。此参数是可选的，但建议在跟踪过去事件时使用。如果是跟踪实时活动，则可以忽略此参数。
value：与此事件相关联的数值（Double 类型）。例如，购买金额。

识别人的特征

如果您的应用程序收集有关用户的额外识别特征，您可以通过 set(profileAttribute:value:) 或 set(profile:) 方法以及电子邮件、电话号码和外部 ID 的单个设置方法将它们提供给 Klaviyo。在两种情况下，我们都提供了大量常用配置文件属性，您可以使用。如果您需要更定制化的内容，则可以在创建配置文件对象时通过属性字典传递给我们。

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")

请注意，set(profile:) 方法仅接受一个表示客户属性的字典参数。这与可以接受多个参数的 trackEvent 方法不同。

匿名跟踪通知

默认情况下，Klaviyo 会在 SDK 初始化后开始对您的应用程序中的匿名用户进行跟踪。这意味着您可以在不提供任何用户信息的情况下跟踪应用程序中用户的操作。当提供电子邮件或其他主要标识符时，Klaviyo 会将匿名用户的数据合并到一个新识别的用户。

在版本1.7.0之前，Klaviyo SDK使用苹果供应商标识符（IDFV）来简化匿名追踪。从版本1.7.0开始，SDK将使用初始化SDK时生成的缓存UUID。对于使用IDFV的现有匿名配置，SDK将继续使用IDFV，而不是生成一个新的UUID。

配置文件属性和标识符

无论何时通过我们的API传递电子邮件（或其他标识符）来使用它，我们都会保留这些信息供未来的调用，以便将新的数据与正确的配置文件相关联。然而，你始终可以通过传递新的标识符进入客户属性字典来覆盖当前标识符。

KlaviyoSDK().set(email: "[email protected]")

推送通知

实现推送通知需要启用一些额外的代码片段。

为推送通知注册用户。
将结果推送令牌发送到Klaviyo。
处理用户尝试打开您的推送通知时的操作。

发送推送通知

将以下代码添加到您需要提示用户注册推送通知的应用程序中。这通常包含在application:didFinishLaunchingWithOptions:中，但也可能放置在其他位置。当调用此代码时，请确保Klaviyo SDK已配置，并且已调用set(email:)。这使得Klaviyo能够将应用程序令牌与Klaviyo客户中的配置文件匹配。

	import UserNotifications
	...
	let center = UNUserNotificationCenter.current()
	center.delegate = self as? UNUserNotificationCenterDelegate // the type casting can be removed once the delegate has been implemented
	let options: UNAuthorizationOptions = [.alert, .sound, .badge]
	// use the below options if you are interested in using provisional push notifications. Note that using this will not
	// show the push notifications prompt to the user.
	// let options: UNAuthorizationOptions = [.alert, .sound, .badge, .provisional]
	center.requestAuthorization(options: options) { granted, error in
	    if let error = error {
	        // Handle the error here.
	        print("error = ", error)
	    }

	    // Enable or disable features based on the authorization status.
	}

	UIApplication.shared.registerForRemoteNotifications()

将以下代码添加到应用程序代理文件中的application:didRegisterForRemoteNotificationsWithDeviceToken。如果您尚未添加此代码，您可能需要将其添加到应用程序代理中。

    func application(application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        KlaviyoSDK().set(pushToken: deviceToken)
    }

现在启用/接受您的应用程序推送通知的任何用户都符合接收您的自定义通知的资格。

要了解更多关于发送推送通知的信息，请查看我们的其他推送通知指南。

追踪推送通知

以下代码示例允许您跟踪用户何时打开推送通知。

将以下代码添加到您的应用程序代理中。

extension AppDelegate: UNUserNotificationCenterDelegate {
    func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
	let handled = KlaviyoSDK().handle(notificationResponse: response, withCompletionHandler: completionHandler)
	if !handled {
	   // not a klaviyo notification should be handled by other app code
	}
    }
}

发送并打开您的前几个推送通知后，您应该在Klaviyo仪表板中开始看到“打开推送通知”指标。

处理前台推送

以下代码示例允许在您的应用程序正在运行时显示推送通知。

    func userNotificationCenter(_ center: UNUserNotificationCenter,
                                  willPresent notification: UNNotification,
                                  withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
        var options: UNNotificationPresentationOptions =  [.alert]
        if #available(iOS 14.0, *) {
          options = [.list, .banner]
        }
        completionHandler(options)
    }

如果用户在应用程序打开时点击通知，则此事件被视为一个打开推送事件。

处理深度链接

⚠️ 为了保证以下步骤能正常运行，您的应用程序需要使用版本1.7.2或更高版本。

以下两种使用案例可以与深度链接相关

当您通过深度链接向您的应用程序推送通知时。
其他可能通过短信、电子邮件、网页浏览器等方式通过深度链接进入您的应用程序的情况。

为了使深度链接正常工作，需要一些配置，并且这些配置与处理深度链接的常规要求没有区别，您可以遵循Apple官方文档中的步骤，并结合此处突出显示的步骤进行操作

选项 1：修改公开跟踪

如果您计划在您的应用中使用通用链接进行深度链接，则需要按照以下方法修改推送公开跟踪。

extension AppDelegate: UNUserNotificationCenterDelegate {
    func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
        let handled = KlaviyoSDK().handle(notificationResponse: response, withCompletionHandler: completionHandler) { url in
            print("deep link is ", url)
        }
        if !handled {
           // not a klaviyo notification should be handled by other app code
        }
    }
}

请注意，深度链接处理程序将在主线程上调用。如果您想处理URI方案，除了通用链接以外，您应按照以下说明实现。

选项 2：使用URL方案

如果您不需要通用链接支持，则可以代替实现适用于您的应用的URL方案和深度链接处理程序，如选项 1 中所示，可以省略深度链接处理程序。在这种情况下，Klaviyo SDK将自动跟踪所有URL。

步骤 1：注册URL方案

为了使Apple将深度链接路由到您的应用，您需要在应用程序的Info.plist文件中注册一个URL方案。这可以通过从项目设置的信息标签中使用Xcode提供的编辑器或直接编辑Info.plist文件来完成。

所需字段如下

标识符 - 您与方案一起提供的标识符区分了您的应用与其他声明支持同一方案的应用。为确保唯一性，请指定一个包含您的公司域名和应用程序名称的反向DNS字符串。尽管使用反向DNS字符串是一种最佳实践，但它不能阻止其他应用注册相同的方案并处理相关的链接。
URL方案 - 在URL Schemes框中，指定您用于URL的前缀。
角色 - 由于您的应用将编辑角色，请选择编辑器角色。

要直接编辑Info.plist，只需填写您的应用程序特定详细信息，并将其粘贴到plist中。

<key>CFBundleURLTypes</key>
<array>
	<dict>
		<key>CFBundleTypeRole</key>
		<string>Editor</string>
		<key>CFBundleURLName</key>
		<string>{your_unique_identifier}</string>
		<key>CFBundleURLSchemes</key>
		<array>
			<string>{your_URL_scheme}</string>
		</array>
	</dict>
</array>

步骤 2：白名单支持的网络协议

自 iOS 9 以来，苹果要求您应用可以打开的网络协议也必须在 Info.plist 中列出。这以上步骤 1 为补充。即使您的应用没有打开其他应用，您也必须列出您应用的 URL 协议，以便深度链接可以正常工作。

这需要在 Info.plist 中直接完成

<key>LSApplicationQueriesSchemes</key>
<array>
	<string>{your custom URL scheme}</string>
</array>

步骤 3：在您的应用中实现处理深度链接

步骤 1 和 2 为您配置了接收深度链接的应用，但现在您需要弄清楚如何在应用中处理它们。

如果您使用的是 UIKit，您需要在应用的 app delegate 中实现 application:openURL:options:。

SDK 仓库中有一个示例应用 (Examples/KlaviyoSwiftExamples)，您可以从中获取如何在应用中实现深度链接的示例。

示例

func application(
    _ app: UIApplication,
    open url: URL,
    options: [UIApplication.OpenURLOptionsKey : Any] = [:]
) -> Bool {
    guard let components = NSURLComponents(url: url, resolvingAgainstBaseURL: true)
    else {
       print("Invalid deep linking URL")
       return false
    }

    print("components: \(components.debugDescription)")

    return true
}

如果您使用的是 SwiftUI，您可以在要处理深度链接的视图中实现 onOpenURL(perform:) 作为视图修饰符。这可能不是您场景的根。

示例

@main
struct MyApplication: App {
  var body: some Scene {
    WindowGroup {
      ContentView()
        .onOpenURL { url in
          // handle the URL that must be opened
        }
    }
  }
}

完成以上步骤后，您可以从 Klaviyo 网站内的 Klaviyo Push 编辑器中发送推送通知。在这里，您可以通过 Klaviyo 向您的应用发送推送通知，确保在步骤 3 中实现的处理程序中显示此 URL。

此外，您还可以在终端中使用以下命令在本地触发深度链接，以确保您的代码正在正常工作。

xcrun simctl openurl booted {your_URL_here}

富推送通知

⚠️ 自版本 2.2.0 开始，SDK 支持富推送通知。详细信息请访问：2.2.0 及以上版本

富推送通知是指添加图片到您的推送通知消息中，这项功能自 iOS 10 开始由 Apple 支持。为此，Apple 需要您实现一个通知服务扩展。以下是设置您的应用程序以接收富推送通知的步骤。

步骤 1：将通知服务应用程序扩展添加到您的项目中

通知服务应用程序扩展作为单独的包包装在您的 iOS 应用程序中。要添加此扩展到您的应用程序

在 Xcode 中选择“文件 > 新建 > 目标”。
从 iOS > 应用程序扩展部分中选择“通知服务扩展”目标。
单击“下一步”。
指定您的应用程序扩展的名称和其他配置详细信息。
单击“完成”。

⚠️默认情况下，您的通知服务扩展的部署目标可能是最新的 iOS 版本，而不是您希望支持的最小版本。这可能会导致 iOS 版本低于通知服务扩展部署目标的设备不显示附加的媒体。⚠️

步骤 2：实现通知服务应用程序扩展

通知服务应用程序扩展负责下载媒体资源并将其附加到推送通知中。

一旦完成步骤 1，您应该在通知服务扩展目标下看到一个名为 NotificationService.swift 的文件。从现在开始，根据您使用的依赖项管理器的不同，步骤可能会有所不同。

Swift Package Manager (SPM)

点击新创建的推送服务扩展目标
在“常规”>“框架和库”中，使用左下角的+按钮添加 KlaviyoSwiftExtension。
然后，在 NotificationService.swift 文件中添加来自此文件的两个必需的代理代码。此示例涉及调用 Klaviyo 以使我们能够下载并将媒体附加到推送通知。

CocoaPods

在 Podfile 中将 KlaviyoSwiftExtension 添加为新增推送服务扩展目标的一个依赖项。

示例
```
target 'NotificationServiceExtension' do
    pod 'KlaviyoSwiftExtension', '2.1.0-beta1'
end
```
请确保替换上面推送服务扩展目标的名称。
一旦添加了依赖项，请确保执行 pod install。
然后在 NotificationService.swift 文件中添加来自此文件的两个必需的代理代码。此示例涉及调用 Klaviyo 以使我们能够下载并将媒体附加到推送通知。

步骤 3: 测试您的丰富推送通知

本地测试

您需要做以下三件事：

任何推送通知测试工具，例如这个。
与Klaviyo向您发送的推送通知相似的推送通知有效载荷。以下有效载荷应该可以正常工作，只要图像有效

{
  "aps": {
    "alert": {
      "title": "Free apple vision pro",
      "body": "Free Apple vision pro when you buy a Klaviyo subscription."
    },
    "mutable-content": 1
  },
  "rich-media": "https://www.apple.com/v/apple-vision-pro/a/images/overview/hero/portrait_base__bwsgtdddcl7m_large.jpg",
  "rich-media-type": "jpg"
}

真实设备的推送通知令牌。这可以通过从AppDelegate中的didRegisterForRemoteNotificationsWithDeviceToken方法打印到控制台来实现。

一旦我们有了这三样东西，我们就可以使用推送通知测试工具发送本地推送通知，以确保一切设置正确。

沙盒支持

苹果有支持推送通知的两个环境——生产环境和沙盒。生产环境可以在将应用发布到App Store或TestFlight时支持向真实用户发送推送通知。相比之下，支持推送通知的沙盒应用是使用iOS开发证书签名的，而不是iOS分发证书。沙盒作为一个预发布环境，允许你在类似于生产环境但又不完全相同的环境中测试应用程序，而无需担心向真实用户发送消息。

我们的SDK同样支持使用沙盒进行推送。Klaviyo的SDK将确定并存储您推送令牌所属的环境，并将其传达给我们的后端，使您的令牌能够将发送路由到正确的环境。无需进行额外设置。只要您已经使用我们的SDK将应用部署到沙盒，并将推送令牌传输到我们的后端，这些沙盒应用的发送和接收推送功能应该可以正常运行。

使用Klaviyo进行测试

遗憾的是，目前我们不支持使用Klaviyo进行调试构建的测试。因此，如果您尝试向调试构建发送测试推送通知，您将在Klaviyo上看到错误。

建议的一个临时解决方法是创建一个测试飞行版本，其中包含上述修改以实现丰富的推送通知，然后在测试飞行版本上执行一些操作以识别设备，并确保您能在 Klaviyo 中看到该设备。一旦您获得了该设备的推送令牌（在任何配置文件中），都可以使用该配置文件创建一个列表或细分，并通过带图片的推送活动对这个完整的端到端集成进行测试。

SDK 数据传输

从版本 1.7.0 开始，SDK 将缓存传入的数据，并根据应用程序当前使用的网络链接以间隔将其刷新回 Klaviyo API。间隔基于应用程序目前使用的网络连接类型。下表显示了每种连接类型所使用的刷新间隔

网络	间隔
WWAN/Wifi	10 秒
Cellular	30 秒

连接确定基于我们的可达性服务的通知。在没有网络时，SDK 将缓存数据，直到网络再次可用。SDK 发送的所有数据应在 SDK 刷新后不久即可获得。

重试

SDK 会重新尝试在某些条件下失败的 API 请求。例如，如果出现网络超时，请求将在下一个刷新间隔时重试。此外，如果 SDK 从 Klaviyo API 收到速率限制错误 429，它将使用带抖动的指数退避来重试下一个请求。

许可证

KlaviyoSwift 在 MIT 许可证下提供。有关更多信息，请参阅 LICENSE 文件。

UserDefaults访问

截至2023年秋季，苹果要求访问特定苹果API的应用程序在申请中提供此访问原因。Klaviyo SDK的早期版本使用UserDefaults存储有关当前用户的数据。今天，当SDK启动时，它必须访问这些数据以转换为新的格式。以下是我们为您的应用提交提供的示例原因（如果被要求）

UserDefaults is accessed by the Klaviyo SDK within our app to migrate some user data (previously stored there). None of this data is shared with other apps.

如果您的应用程序或其他SDK也访问UserDefaults，您可能需要修改原因，以包括该使用方式。使用“NSPrivacyAccessedAPICategoryUserDefaults”作为NSPrivacyAccessedAPITypes字典中NSPrivacyAccessedAPIType关键字的值。有关更多信息，请参阅此指南。

KlaviyoSwiftExtension 3.2.0

KlaviyoSwiftExtension 3.2.0

KlaviyoSwiftExtension 3.2.0

KlaviyoSwift

概述

安装选项

使用 SPM 安装

使用 CocoaPods 安装

事件跟踪

参数

识别人的特征

匿名跟踪通知

配置文件属性和标识符

推送通知

发送推送通知

追踪推送通知

处理前台推送

处理深度链接

选项 1：修改公开跟踪

选项 2：使用URL方案

步骤 1：注册URL方案

步骤 2：白名单支持的网络协议

步骤 3：在您的应用中实现处理深度链接

富推送通知

步骤 1：将通知服务应用程序扩展添加到您的项目中

步骤 2：实现通知服务应用程序扩展

Swift Package Manager (SPM)

CocoaPods

步骤 3: 测试您的丰富推送通知

本地测试

沙盒支持

使用Klaviyo进行测试

SDK 数据传输

重试

许可证

UserDefaults访问