KlaviyoSwift

概述

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

安装选项

使用 SPM 安装
使用 Cocoapods 安装

使用 SPM 安装

KlaviyoSwift 可通过 Swift Package Manager (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")

通过在相关位置调用 create(event:) 方法，在任何您希望跟踪事件的区域内开始跟踪。

let klaviyo = KlaviyoSDK()

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)

klaviyo.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:) 方法将其提供给 Klaviyo，并通过 properties。在两种情况下，我们都提供了广泛使用的配置文件属性，您可以从中选择使用。如果您需要更定制的属性，则始终可以通过创建配置文件对象时通过属性字典传递给我们这些属性。

let profile = Profile(email: "[email protected]", firstName: "Blob", lastName: "Jr")
KlaviyoSDK().set(profile: profile)

// or setting individual properties
KlaviyoSDK().set(profileAttribute: .firstName, "Blob")
KlaviyoSDK().set(profileAttribute: .lastName, "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, completionHandler: completionHandler)
            if not 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：修改 Open Tracking

如果您计划在应用中使用通用链接进行深链接，您需要按照以下说明修改推送打开跟踪。

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

请注意，深链接处理程序将在主线程上被调用回。如果您想要处理 URI 协议以及通用链接，请按照以下描述实现。

选项 2：使用 URL 方案

如果您不需要通用链接支持，则可以实施应用中的 URL 方案，并且可以省略选项 1 中指示的 deepLinkHandler。在这种情况下，Klaviyo SDK 会自动追踪所有 URL。

第1步：注册URL方案

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

以下是需要填写的字段：

标识符 - 与您提供的方案关联的标识符区分您的应用与其他声明支持相同方案的应用。为确保唯一性，指定一个包含您公司域名和应用程序名称的反向DNS字符串。虽然使用反向DNS字符串是一种最佳实践，但它并不能阻止其他应用注册同一方案并处理相关的链接。
URL方案 - 在URL方案框中，指定您用于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步：白名单支持的URL方案

自从iOS 9以来，苹果要求应用程序可以打开的URL方案也必须在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推送编辑器发送推送通知。在这里，您可以通过Klaviyo构建和发送推送通知，以确保URL出现在步骤3中实现的处理器中。

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

xcrun simctl openurl booted {您的_URL_here}

富推送通知

⚠️ 此功能目前仅限邀请制

富推送通知是苹果从iOS 10开始支持的在推送通知消息中添加图片、GIF和视频的功能。为了执行此操作，苹果要求您应用程序实现一个通知服务扩展。遵循以下步骤应有助于设置应用程序以接收富推送通知。

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

通知服务应用扩展是作为iOS应用程序内部的单独包来分发的。要将此扩展添加到您的应用程序中

选择File > New > Target在Xcode中。
从iOS > 应用程序扩展部分中选择通知服务扩展目标。
点击Next。
指定应用程序扩展的名称和其他配置详细信息。
点击Finish。

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

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

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

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

Swift Package Manager(SPM)

⚠️ 由于当前该功能仅限受邀使用，请使用 SDK 和扩展的预发布版本（2.1.0-beta1）。

点击新建的通知服务扩展目标。
在“通用”>“框架和库”中，使用左下角的加号按钮添加 KlaviyoSwiftExtension。
然后，在 NotificationService.swift 文件中，从此处添加两个必需的代理的代码。此示例涵盖了调用 Klaviyo 以便我们将媒体下载并附加到推送通知。

Cocoapods

⚠️ 由于当前该功能仅限受邀使用，请使用 SDK 和扩展的预发布版本（2.1.0-beta1）。

在您的 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 方法打印到控制台。

一旦我们有了这三样东西，我们就可以使用推送通知测试器发送一个本地推送通知，以确保所有设置都已正确完成。

使用 Klaviyo 进行测试

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

一个建议的临时解决方案是创建一个测试航班构建，其中包含用于丰富推送通知的上述更改，在测试航班构建上执行一些操作以识别设备并确保您能够在 Klaviyo 中看到该设备。一旦您有了该设备的推送令牌，将其添加到任何配置文件中，可以创建包含该配置文件的列表或分段，并发送带有图像的推送活动以测试完整的端到端集成。

SDK 数据传输

从版本1.7.0开始，SDK将缓存传入数据，并按间隔将其回flush到Klaviyo API。间隔基于应用当前使用的网络链接。下表显示了用于每种连接的flush间隔。

网络	间隔
WWAN/Wifi	10秒
蜂窝网络	30秒

连接确定基于我们可达性服务的通知。如果没有可用的网络，SDK将缓存数据，直到网络再次可用。由SDK发送的所有数据应在SDK进行flush后立即可用。

重试

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

许可证

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

KlaviyoSwift 3.2.0

KlaviyoSwift 3.2.0

KlaviyoSwift 3.2.0

KlaviyoSwift

概述

安装选项

使用 SPM 安装

使用 CocoaPods 安装

事件跟踪

参数

识别人的特征

匿名跟踪通知

配置文件属性和标识符

推送通知

发送推送通知

跟踪推送通知

前台推送处理

处理深链接

选项 1：修改 Open Tracking

选项 2：使用 URL 方案

第1步：注册URL方案

第2步：白名单支持的URL方案

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

富推送通知

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

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

Swift Package Manager(SPM)

Cocoapods

第3步：测试您的丰富推送通知

本地测试

使用 Klaviyo 进行测试

SDK 数据传输

重试

许可证