Ometria 1.6.0

Ometria 1.6.0

Al JamesPeter HorvathAndrew Akehurst-RyanCatalin DemianJames Barlow 维护。



Ometria 1.6.0

  • Al James

1. why integrate Ometria in a mobile app?

Ometria 通过提供个性化的电子邮件和推送通知来帮助您的营销部门更好地理解并接触客户。

该应用有两个主要目标

  1. 获取有关客户的信息(他们喜欢什么?)
  2. 联系客户(对正确的人说正确的话)。

对于您的移动应用,这意味着

  1. 通过事件跟踪客户行为 - 由 Ometria 处理。
  2. 发送和显示推送通知 - 需要开发人员

2. Before you begin

请参阅 Ometria 帮助中心中的 配置带有 Firebase 凭证的移动应用,并按照其中的步骤操作以获取 API 密钥。

3. Install the library

将 Ometria 添加到您的 iOS 项目的最简单方法是通过使用 CocoaPods

  1. 如果您是第一次使用CocoaPods,请在终端中使用gem install cocoapods安装CocoaPods。否则,跳到第3步。
  2. 运行pod setup以创建本地CocoaPods spec镜像。
  3. 在终端中运行pod init在Xcode项目目录下创建一个Podfile,编辑生成的Podfile并添加以下行:pod 'Ometria'.
  4. 在Xcode项目目录下运行pod install。CocoaPods应下载并安装库,并创建一个新的Xcode工作空间。在Xcode中打开此工作空间或通过在终端中输入open *.xcworkspace来打开。

4. 初始化库

要初始化Ometria,您需要输入从“2. 开始之前”中的API密钥。

ℹ️虽然您可以在Android上更改推送通知中显示的图标,但苹果在这方面更为严格。因此,iOS和iPadOS上的推送通知始终使用应用程序图标,而布局的更改只能通过用户控制的偏好设置来实现。有关更多信息,请参阅推送通知界面指南

您可以在application(_:didFinishLaunchingWithOptions:)中完成此操作。

通过添加import Ometria并调用包含您的API密钥作为参数的Ometria.initialize(apiToken:)来初始化库。

一旦调用过这个方法,您就可以通过sharedInstance()在整个应用程序中访问您的实例。

Ometria使用Firebase Cloud Messaging向移动设备发送推送通知。

为此,将“Firebase/Messaging”添加为Ometria的依赖项。

  • 如果您通过CocoaPods安装了库,它将自动安装。
  • 如果您在项目中手动添加了Ometria,您应该单独安装Firebase SDK

初始化Ometria后,对Firebase Cloud Messaging进行相同的操作。

完成操作后,您将得到类似以下内容

import Ometria

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    Ometria.initialize(apiToken: "OMETRIA_API_TOKEN")
    FirebaseApp.configure()
    return
}

Ometria 默认记录在运行时遇到的任何错误。

如果您想了解后台发生的情况,可以启用高级日志记录。只需在初始化库后添加以下行即可

Ometria.sharedInstance().isLoggingEnabled = true

禁用Swizzling

方法Swizzling是在运行时更改现有选择器/方法的功能的能力。

ℹ️默认情况下,Ometria SDK 使用 Swizzling 来访问推送消息中到达的数据。我们选择这种方法是为了让实现者能够更少的工作来集成 SDK。然而,如果您不适应使用 Swizzling,我们提供了一组需要调用的方法,以便为 Ometria SDK 提供用户显示推送通知所必需的信息。

首先,您需要更新初始器,以使其不使用 Swizzling。

Ometria.initialize(apiToken: "YOUR_API_TOKEN_HERE", enableSwizzling: false)

接下来,每次 Firebase 更新时,您都需要提供 Firebase 推送令牌。您可以在 Messaging 代理方法中完成此操作。

func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String?) {
    if let token = fcmToken {
        Ometria.sharedInstance().handleFirebaseTokenChanged(token: token)
    }
}

最后,Ometria SDK 需要知道用户何时接收并交互推送通知。这些事件的详细信息可以通过以下方法提供:

func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
    Ometria.sharedInstance().handleNotificationResponse(response)
}

func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
    Ometria.sharedInstance().handleReceivedNotification(notification)
    completionHandler([.alert, .sound])
}

提供以上所有信息后,Ometria SDK 应该有将推送通知发送给用户并收集有关这些交互的信息所需的信息。

在同一个应用实例中使用多个 Ometria API 令牌(重新初始化 SDK)

有些情况下,应用的不同流程应在不同的令牌下记录事件(例如,不同的用户角色或其他类似情景)。为了解决这个问题,我们提供重新初始化 Ometria SDK 的可能性。虽然我们目前不保存 SDK 多个实例的引用,但我们确保在重新初始化时将尝试刷新旧实例中已记录的所有事件。

重新初始化 SDK 需要执行与正常初始化时相同的步骤。请咨询 4. 初始化库,以确保一切设置正确。

5. 事件跟踪指南

您需要了解您的用户在您平台上的行为,以便了解他们。一些行为是自动可检测的,其他事件需要应用开发者来进行跟踪。

其中许多方法在名为 Ometria 数据 API 的服务器到服务器 API 中有类似的事件,以及通过单独的 JavaScript API。

注意:如果您的企业以任何方式与其他 Ometria 集成,则非常重要确保发送的值与其他集成中的值一致。

例如,客户识别事件需要一个客户 ID - 该 ID 必须在这里与数据 API 中相同。

事件在Ometria端合并为一个大型的跨渠道视图来展示您的客户行为,否则会变得非常混乱。

手动跟踪的事件

一旦初始化SDK,您可以通过调用其专用方法来跟踪一个事件

let myItem = OmetriaBasketItem(
        productId: "product-1",
        variantId: "variant-product-1"
        sku: "sku-product-1",
        quantity: 1,
        price: 12.0)
let myItems = [myItem]
let myBasket = OmetriaBasket(id: "basket-id", totalPrice: 12.0, currency: "USD", items: myItems, link: "http://sample.link.com")

Ometria.sharedInstance().trackBasketUpdatedEvent(basket: myBasket)

确定用户资料

应用程序用户刚刚识别自身,即进行了登录。

trackProfileIdentifiedEvent(customerId: String)

他们的客户ID是他们在数据库中的用户ID

有时,用户仅提供电子邮件地址而没有完全登录或没有账户。在这种情况下,Ometria可以根据电子邮件进行资料匹配

trackProfileIdentifiedEvent(email: String)

拥有customerId可以让资料匹配更稳健。

这并不排除发送电子邮件事件;为了最佳集成,您应该尽早发送这两个事件中的一个。这两个事件对于SDK的运行至关重要,因此请确保尽早发送它们。

匿名用户资料

撤销一个确定用户资料的事件。

如果用户登出或以其他方式表示此设备不再连接到同一人,请使用此功能。

trackProfileDeidentifiedEvent()

产品已查看

访客点击/轻触/查看/突出显示产品,或者以其他方式表现出对该产品的兴趣。

例如,访客搜索一个术语,并从一组结果中选择一个产品预览,或者在衣服类别中浏览,并单击特定的衬衫以查看更大的图片。

此事件涉及捕获访问者对该产品的兴趣。

trackProductViewedEvent(productId: String)

查看购物车

访客已经查看了一个包含购物车内容的专用页面、屏幕或模态。

trackBasketViewedEvent()

更新购物车

访客已经更改了他们的购物车。

trackBasketUpdatedEvent(basket: OmetriaBasket)

此事件将完整的当前购物车作为一个参数,而不仅仅是更新的部分。

这有助于从丢失或不同步的购物车事件中恢复:最新的更新总是具有权威性。

开始结账

用户已开始结账流程。

trackCheckoutStartedEvent(orderId: String)

订单完成

订单已完成并付款。

trackOrderCompletedEvent(orderId: String, basket: OmetriaBasket)

深度链接已打开

根据与包含深度链接的通知交互的实现状态,此事件可以自动跟踪或不自动跟踪。

默认实现会在用户与链接包含深度链接的通知交互时自动记录深度链接已打开事件。这是可能的,因为我们知道默认实现将在浏览器中打开链接。

如果您选择自己处理深度链接(请参阅处理包含 URLs 通知的交互指南),则应在了解有关目标屏幕(或其他目的地)的足够信息时手动跟踪此事件。

trackDeepLinkOpenedEvent(link: String, screenName: String)

查看主页

访问者查看您的应用的“主页”或着陆页面。

trackHomeScreenViewedEvent()

查看产品列表

访问者点击/轻点/查看高亮或以其他方式对产品列表表示兴趣。此类屏幕包括搜索结果、产品分组、类别、收藏或展示产品列表的任何其他屏幕。

例如,一家商店出售服装,访问者轻点“女性鞋类”以查看该类别的产品列表,或者他们搜索“蓝色毛衣”并查看该类别的产品列表。

此事件应在以下情况下触发

  • 搜索结果
  • 类别列表
  • 任何类似的屏幕
trackProductListingViewedEvent(listingType: String?, listingAttributes: [String: Any]?)

屏幕浏览

跟踪访客独立的屏幕浏览可以帮助我们跟踪他们在应用中的参与情况以及他们的旅程进程。

在网站上类似的事件可能就是跟踪独立的页面浏览。

所有常见的电子商务屏幕都有自己的顶级事件:浏览了购物篮、浏览了产品列表等。

您的应用可能有一种对营销人员跟踪参与度有用的特定类型页面。

例如,如果您正在进行促销活动,查看特定的屏幕表明对促销感兴趣,之后营销人员可能希望跟进。

为了跟踪这些自定义屏幕,请使用 屏幕浏览 事件

trackScreenViewedEvent(screenName: String, additionalInfo: [String: Any])

自定义事件

您的应用可能有营销团队感兴趣的具体流程或页面。

例如,营销人员可能希望向任何注册过特定促销或与应用中的按钮或特定元素交互的用户发送电子邮件或通知。

如果您发送与该动作相对应的自定义事件,他们就可以启动该动作的 自动化营销活动

请查阅营销团队的具体要求,了解他们可能需要什么。特别是如果他们已经在使用 Ometria 进行电子邮件营销,他们将了解自动化营销活动和自定义事件。

trackCustomEvent(customEventType: String, additionalInfo: [String: Any]?)

OmetriaBasket

OmetriaBasket 是一个描述购物篮内容的对象。

属性

  • currency: (String, required) - 用ISO货币格式表示货币的字符串。例如:"USD""GBP"
  • price: (float, required) - 表示价格的浮点数。
  • items: (Array[OmetriaBasketItem]) - 包含此购物车中项条目的数组。
  • link: (String) - 指向此购物车 Web 或内页面的deeplink。可用于发送给用户的通知中,例如:“忘记结账了?这里是您的购物车,继续结账:”。点击该链接应直接将他们带到购物车页面。

OmetriaBasketItem

OmetriaBasket 是一个描述购物篮内容的对象。

它可以根据应用的不同规则和促销活动具有自己的价格和数量。

属性

  • productId: (String, required) - 表示此产品唯一识别符的字符串。
  • sku: (String, optional) - 表示库存单位,可以用来识别特定项目。
  • quantity: (Int, required) - 此条目表示的项目数量。
  • price: (Float, required) - 表示单个项目价格的浮点数。该货币由包含此项目的OmetriaBasket确定

自动跟踪的事件

以下事件由SDK自动跟踪。

仅联接和初始化SDK即可充分利用这些功能;无需进一步集成。

事件 描述
应用已安装 应用刚刚安装。通常无法在应用真正安装时发送,而是在应用首次启动时才发送。
应用启动 有人刚刚打开了应用。
应用进入前台 应用已被启动,但在后台。它刚刚被带到前台。
应用进入后台 应用正在积极使用,但它刚刚被发送到后台。
推送令牌刷新 Firebase生成的推送令牌已更新。
收到通知 系统收到了推送通知。
交互通知 用户刚刚点击了/轻触了/打开了通知。
发生错误 客户端发生错误。我们试图检测实际通知有效载荷方面的问题,所以我们不期望需要反馈给最终用户的任何错误。

刷新跟踪事件

为了减少电源和带宽消耗,Ometria库不会逐个发送事件,除非您要求它这样做。

相反,它在应用运行时将事件组合成批量发送给后端,当以下其中之一发生时:

  • 已经收集了10个事件,
  • Firebase令牌刷新(pushtokenRefreshed事件),
  • notificationReceived事件(这不能在iOS上可靠工作,因为操作系统阻止应用程序了解此情况),
  • appForegrounded事件,
  • appBackgrounded事件。

您可以通过调用以下方法来要求库在任何时候将所有剩余事件发送到后端:

Ometria.sharedInstance().flush()

清除跟踪事件

您可以完全清除所有已跟踪但尚未刷新的事件。

为此,请调用以下方法:

Ometria.sharedInstance().clear()

调试事件

要查看捕获了哪些事件,你可以检查Ometria SDK生成的日志(如果启用了日志记录)。你可以筛选“Ometria”单词。SDK会将所有事件按发生顺序记录下来,并记录它们的推送过程,即当它们被发送到Ometria移动事件API时。任何与推送相关的潜在错误(API问题或事件验证问题)也会在这里显示。

第6节:推送通知指南

当设置正确时,Ometria可以为您的移动应用程序发送个性化的推送通知。

请按照以下步骤操作

  1. 通过创建appId并启用推送通知权限,使您的应用程序能够接收推送通知。
  2. 设置一个Firebase账户并将其连接到Ometria。
  3. 在Firebase账户上启用云消息服务,并提供应用程序的SSL推送证书。
  4. 在应用程序中配置推送通知。
  5. 向您的应用程序添加一个通知服务扩展,以便启用接收丰富内容通知。

在您的应用程序中配置推送通知

在继续操作之前,您必须已经配置了以下内容

  • Ometria SDK
  • Firebase

一旦您成功创建或修改了您的应用程序以支持推送通知,您就可以在AppDelegate中配置所有内容,如下所示

import UserNotifications

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate, UNUserNotificationCenterDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        Ometria.initialize(apiToken: "OMETRIA_API_TOKEN")
        FirebaseApp.configure()
        configurePushNotifications()

        return true
    }

    func configurePushNotifications() {
        UNUserNotificationCenter.current().delegate = self
        let authOptions: UNAuthorizationOptions = [.alert, .badge, .sound]
        UNUserNotificationCenter.current().requestAuthorization(options: authOptions) {
            [weak self] (granted, error) in

            print("Permission granted: \(granted)")
            guard granted else { return }
            self?.getNotificationSettings()
        }
        UIApplication.shared.registerForRemoteNotifications()
    }

    func getNotificationSettings() {
        UNUserNotificationCenter.current().getNotificationSettings { settings in
            print("Notification settings: \(settings)")
            guard #available(iOS 12.0, *), settings.authorizationStatus == .provisional ||
            settings.authorizationStatus == .authorized else {
                return
            }

            DispatchQueue.main.async {
                UIApplication.shared.registerForRemoteNotifications()
            }
        }
    }

    func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        print("Reaching Did register for remote notifications")
        // handle your own device token handling here
    }

    func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
        print("Reaching Did receive notification response")
        // handle how your app reacts to receiving a push notification while it is running in foreground
    }

    func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
        print("Reaching Will present notification")
        // handle how you want your notification to be presented while the app is running in foreground
    }
}

Ometria SDK将自动获取所有必需的令牌并将它们提供给后端。

这样,您的应用程序将开始接收Ometria的通知。处理当前应用程序正在前台运行时的这些通知由您自己来完成。

处理与通知的交互

Ometria 允许您在推送通知中发送 URL 和跟踪信息,并允许您在设备上处理这些通知。

默认情况下,Ometria SDK 会自动处理包含 URL 的推送通知的任何交互,并打开它们以在浏览器中查看。

但是,它允许开发者根据需要处理这些 URL(例如,将用户带到应用中的特定屏幕)。

要获取对这些交互和 URL 的访问权限,请实现 OmetriaNotificationInteractionDelegate

以下是在代码中实现的方式

import UserNotifications

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate, UNUserNotificationCenterDelegate,  OmetriaNotificationInteractionDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        Ometria.initialize(apiToken: "OMETRIA_API_TOKEN")
        Ometria.sharedInstance().notificationInteractionDelegate = self

        return true
    }

    // This method will be called each time the user interacts with a notification from Ometria
    // Write your own custom code in order to properly redirect the app to the screen that should be displayed.
    func handleOmetriaNotificationInteraction(_ notification: OmetriaNotification) {
        print(notification.deepLinkActionUrl)
    }
}

OmetriaNotification 对象还提供了对通知有效负载中其他字段的访问权限,包括您选择发送的自定义跟踪属性。

可以在上述方法中访问所有这些字段。

如果开发者需要以 OmetriaNotificationInteractionDelegate 之外的上下文访问 OmetriaNotification 对象,Ometria SDK 为此提供了一个名为 parseNotification(_ content:UNNotificationContent) 的方法。

import UserNotifications

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate, UNUserNotificationCenterDelegate,  OmetriaNotificationInteractionDelegate {

    func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
        let notificationContent = notification.request.content
        let ometriaNotification = Ometria.sharedInstance().parseNotification(notificationContent)
        completionHandler([.alert, .sound])
    }
}

启用富内容通知

从 iOS 12.0 开始,Apple 允许常规应用接收和显示包含媒体内容(如图像)的通知。

Ometria 使用此功能进一步增强您应用程序的功能,但这需要您添加一个新的目标扩展,用于截获所有包含有效负载中的 'mutable-content: 1' 的推送通知。

要执行此操作,请转到 文件 > 新建 > 目标,然后选择 通知服务扩展 > 下一步

您的目标列表中将显示新项目

接下来,请确保 Ometria SDK 也适用于此新目标,通过更新 podfile包括您刚刚添加的新目标和将 Ometria 指定为一个依赖项。

注意:如果您尝试运行 pod install 并构建扩展,您将遇到一些编译错误。

由于我们正在尝试在扩展上运行 Ometria,因此 SDK 中的某些方法不受支持,尽管没有使用。

要消除这些错误并使所有功能正常工作,您必须更新 podfile,使之最终类似于以下内容

 platform :ios, '10.0'

target 'OmetriaSample' do
  use_frameworks!

  pod 'Ometria', :path => '../../SDK'

  target 'OmetriaSampleNotificationService' do
    pod 'Ometria', :path => '../../SDK'
  end

  end

post_install do |installer|
  installer.pods_project.targets.each do |target|
    if target.name == 'Ometria'
      target.build_configurations.each do |config|
        config.build_settings['APPLICATION_EXTENSION_API_ONLY'] = 'No'
      end
    end
  end
end

完成此操作后,您就可以运行应用程序和您刚刚创建的扩展了。

最后完成实现并允许 Ometria 截获通知,请在 NotificationService 类中打开内容并替换为以下内容

import UserNotifications
import Ometria

class NotificationService: OmetriaNotificationServiceExtension {

}

现在您可以接收来自 Ometria 的通知,并且您还能够看到附加到通知中的图像。

7. 统一链接指南

Ometria 通过指向您网站的 URL 发送个性化的电子邮件。为了在您的应用程序中打开这些 URL,请确保遵循本指南。

先决条件

首先,确保您已为您的账户设置了一个启用 SSL 的 Ometria 跟踪域。您可能已经为您的内容邮件配置了此域,如果没有,请联系您的 Ometria 联系人设置一个,并应提供给您该域。

为您的应用程序启用关联域权益

为此,请在 Xcode 中选择您的项目,然后转到 目标 > 您的应用程序目标 > 签名与能力,并添加 关联域 能力。

一旦启用,按照以下方式输入您的 Ometria 跟踪域。

这将确保当您的客户点击 Ometria 电子邮件中的链接时,您的应用程序打开而不是浏览器。

注意: 这不会将您的网站域与应用程序关联,只有跟踪域。

创建一个apple-app-site-association文件并将其发送给您的Ometria联系人。

apple-app-site-association文件用于在域名与您的应用之间建立关联。您可以在这里了解更多信息,但在此指南中,我们将使用最基本示例,其看起来应如下所示

{
    "applinks": {
        "details": [
            {
                "appID": "<Your_team_identifier>.<Your_bundle_id>",
                "paths": ["*"]
            }
        ]
    }
}

将其保存并命名为"apple_app_site_association"(请注意,没有使用扩展名,尽管它只是一个普通的JSON文件)。然后将其发送给您的Ometria联系人——我们将为您上传此文件,使其可在跟踪域名后面可用。

完成这些步骤后,您应该能够通过选择从Ometria收到的URL来成功打开您的应用。

在应用内部处理通用链接

最后一步是在您的应用中处理URL,并将用户带到应用的相应部分。请注意,您需要实现网站URL与您的应用界面之间的映射。

参见将推送通知链接到应用界面

如果您处理的是指向您的网站的正常URL,您可以将其分解为不同的路径组件和参数。这将允许您获取导航到应用正确屏幕所需的信息。

然而,Ometria邮件包含混淆的跟踪URL,您需要在使用映射到应用屏幕之前将这些URL转换回原始URL,指向您的网站。为此,SDK提供了一个名为processUniversalLink的方法

func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    if let url = userActivity.webpageURL {
        // you can check here whether the URL is one that you can handle without converting it back
        Ometria.sharedInstance().processUniversalLink(url) { (url, error) in
            if let url = url {
                // you can now handle the retrieved url as you would any other url from your website
            } else {
                // an error may have occurred
            }
        }
    }
}

警告:上述方法运行异步。根据设备的互联网速度,处理时间可能会有所不同。为了获得最佳效果,您可以在处理URL时实现一个显示加载状态的界面。

如果您一切都做得正确,那么应用现在应该能够打开通用链接并允许您在应用内处理它们。