Netmera iOS SDK 快速入门指南

欢迎使用 Netmera iOS SDK 快速入门指南。本指南提供了将 Netmera iOS SDK 集成到您的 iOS 应用中的逐步教程。

要求

• Xcode 13 或更高版本
• iOS 11.0 或更高版本

安装

1. 将 Netmera 添加到您的 Podfile

pod "NetmeraAnalytic" // to use Netmera analytic features
#pod "NetmeraAnalyticAutotracking" // to use auto tracking features
#pod "NetmeraNotification" // to use Netmera push notification features
#pod "NetmeraAdvertisingId" // to use Netmera advertising identifier features
#pod "NetmeraLocation" // to use Netmera location features
#pod "NetmeraGeofence" // to use Netmera geofence features
#pod "NetmeraNotificationInbox" // to use Netmera push inbox features

2. 在您的终端中运行 pod install 命令。

初始化

1. 在您的 AppDelegate.swift 文件中导入 Netmera 框架

import NetmeraAnalytic
import NetmeraNotification
import NetmeraLocation
import NetmeraNotificationInbox
import NetmeraAdvertisingId

2. 在您的 App 中初始化 Netmera。

初始化 Netmera 有两种方式。

第一种选项：（推荐）

使用 Plist 进行配置。将 Netmera-Config.plist 文件添加到您的项目中。将以下代码复制到 Plist 文件中，并用您的实际 API Key 值替换 API_KEY 占位符。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>sdk_params</key>
	<dict>
		<key>app_group_name</key>
		<string>{AppGroupName}</string>
		<key>use_ui_scene</key>
		<false/>
		<key>api_key</key>
		<string>{API_KEY}</string>
		<key>base_url</key>
		<string>{BaseURL}</string>
		<key>custom_events</key>
		<array>
			<string>{YourCustomEvent}</string>
		</array>
	</dict>
	<key>location_max_active_region</key>
	<string></string>
	<key>in_app_message_settings</key>
	<dict>
		<key>TextColor</key>
		<string>{hexcolor. For ex-&gt; 16777215}</string>
		<key>TitleColor</key>
		<string>{hexcolor. For ex-&gt; 16777215}</string>
		<key>BackgroundColor</key>
		<string>{hexcolor. For ex-&gt; 16777215}</string>
		<key>CancelButtonBackgroundColor</key>
		<string>{hexcolor. For ex-&gt; 16777215}</string>
		<key>TitleFont</key>
		<string>{font family name. ex -&gt; ariel}</string>
		<key>TextFont</key>
		<string>{font family name. ex -&gt; ariel}</string>
		<key>CancelButtonRadius</key>
		<string>{10 sd px}</string>
		<key>ShadowOpacity</key>
		<string>{0-1}</string>
		<key>BottomPaddingRatio</key>
		<string>{between 0.01 - 1}</string>
		<key>CancelButtonImage</key>
		<string>{imagename}</string>
	</dict>
	<key>blacklist_screen_names</key>
	<array/>
</dict>
</plist>

在您的 application(_:didFinishLaunchingWithOptions:) 方法中调用 Netmera 的初始化方法。

Netmera.initialize()

第二种选项

将以下代码添加到您的 application(_:didFinishLaunchingWithOptions:) 方法中，并用您的实际 API Key 值替换 API_KEY 占位符

let netmeraParams = NetmeraParams(
  apiKey: "API_KEY",
  baseUrl: "", // Optional; For On-premise setup
  appGroupName: "", // Optional; to use carousel&slider push
  customEvents: [CustomLoginEvent.self] // Optional; give list of all custom event class type
)
Netmera.initialize(params: netmeraParams)
Netmera.setLogLevel(.debug) // Options can be .debug, .info, .error, .fault

SDK_API_KEY：您可以从您的 web 控制面板中的开发者 -> API -> Sdk Api Key 获取该 API Key。

推送通知

在您的 Podfile 中，您应该添加 NetmeraNotification 并按以下方式将其安装到您的应用目标中；

pod "NetmeraNotification"

在适当的位置调用以下方法，以便从用户请求推送通知授权：

Netmera.requestPushNotificationAuthorization(for: [.alert, .badge, .sound])

调用此方法将立即提示用户推送通知权限对话框，因此您在通知用户您的应用程序如何利用推送通知后调用此方法是重要的。

‼️如果您从推送提供者（如 Apple）收到推送通知权限请求，则调用适当的方法对于让 Netmera SDK 正确处理交互式推送按钮非常重要。如果未执行此操作，可能导致 SDK 无法正确处理这些按钮。

启用推送通知

在 Xcode 中从签名和功能 -> 功能 -> 推送通知中启用推送通知。

//in didFinishLaunchingWithOptions
// ‼️ Implement UNUserNotificationCenterDelegate methods in AppDelegate
UNUserNotificationCenter.current().delegate = self

func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
	//
}
func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
	//
}

高级推送通知管理

推送通知代理方法

除非您需要特殊用法，否则 Netmera 处理所有与远程通知相关的 UIApplicationDelegate 方法，因此您不需要在您的 App Delegate 类中实现它们。

然而，如果您的应用程序有需要自定义实现远程通知代理方法的用例，您可以自由实现它们，并在这些代理方法中执行您特定的逻辑。

您可以在 UIApplicationDelegate 协议参考 中找到有关与推送通知相关的代理方法详细信息的详细信息。

在代理方法中访问 NetmeraPushObject
SDK提供了[Netmera recentPushObject]/Netmera.recentPushObject()方法，该方法返回远程通知有效负载的对象表示。您可以使用此方法来访问在UIApplicationDelegate方法内部对应于远程通知的NetmeraPushObject实例。

禁用/启用弹出窗口、应用内消息和部件

当SDK接收到弹出窗口通知或应用内消息时，如果应用程序处于前台状态，它将立即呈现对应的网页视图内容。如果应用程序在接收到弹出窗口时处于后台状态，SDK将在应用程序恢复前台状态时呈现网页视图内容。

对于用户观看视频、正在进行他们最喜欢游戏关卡或即将完成购买订单等情况，您可能希望禁用这种立即呈现的行为。您可以使用以下两个方法来管理此过程

Netmera.setEnabledPopupPresentation(true) // to enable showing popup and widget push 
Netmera.setEnabledPopupPresentation(false) // to disable showing popup and widget push

Netmera.setEnabledInAppMessagePresentation(true) // to enable showing banner push 
Netmera.setEnabledInAppMessagePresentation(false) // to disable showing banner push 

⚠️如果您希望应用处于后台时接收到弹出窗口或应用内消息，您应该在“功能”中启用远程通知。

⚠️并且当设备关闭且在低电量模式下时，设备无法接收弹出窗口或应用内消息，因为这会使该模式禁用后台应用刷新模式。

使用媒体推送

首先，您应该为您的应用程序创建一个新的通知服务扩展。为了实现这一点，您应该遵循以下步骤

• 在Xcode中点击“文件>新建>目标”。选择通知服务扩展
• 选择通知服务扩展
• 选择“通知服务扩展”后，将创建一个名为NotificationService的新类。它应该从MyNetmeraNotificationServiceExtension类扩展。您的NotificationService类应该如下所示

import UserNotifications
import NetmeraNotificationServiceExtension

class NotificationService: NotificationServiceExtension {
  override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
    super.didReceive(request, withContentHandler: contentHandler)
  }

  override func serviceExtensionTimeWillExpire() {
    super.serviceExtensionTimeWillExpire()
  }
}

在您的pod文件中，您应该添加NetmeraNotificationServiceExtension并将其安装到您的扩展目标中，如下所示。

pod "NetmeraNotificationServiceExtension"

⚠️作为附加，如果您想允许您的应用程序接收http媒体内容，您应该进行如下更改

• 在通知服务扩展下单击“Info.plist”
• 添加App Transport Security设置
• 在App Transport Security设置下添加Allow Arbitrary Loads并将其设置为YES

使用轮播/滑动和缩略图推送

首先，您应该为您的应用程序创建一个新的通知内容扩展。为了实现这一点，您应该遵循以下步骤

• 在Xcode中点击“文件>新建>目标”。选择通知内容扩展
• 选择通知内容扩展
• 选择“通知内容扩展”后，将创建一个名为NotificationViewController的新类。它应该从NetmeraNotificationContentExtension类扩展。您的NotificationContent类应该如下所示
• 如果您想添加幻灯片到轮播属性，必须添加UserInteractionEnabled
• 之后，您应该为您应用和通知内容扩展启用应用分组，然后将“bundle_identifier.group_name”添加到您的应用分组中。
• 您应该确保已将应用分组添加到您的应用中，应在AppDelegate方法中提供Netmera.start()中的应用分组名称，如下设置Netmera.start()方法；

import UserNotifications
import UserNotificationsUI
import NetmeraNotificationContentExtension

class NotificationViewController: NotificationContentExtension {
  override func viewDidLoad() {
    super.viewDidLoad()
  }

  override func didReceive(_ notification: UNNotification) {
    super.didReceive(notification)
  }
}

在您的pod文件中，您应该添加NetmeraNotificationContentExtension并将其安装到您的扩展目标中，如下所示。

pod "NetmeraNotificationContentExtension"

‼️在MainInterface中删除默认标签。

⚠️作为附加，如果您想允许您的应用程序接收http媒体内容，您应该进行如下更改

• 在通知内容扩展下单击“Info.plist”
• 添加App Transport Security设置
• 在App Transport Security设置下添加Allow Arbitrary Loads并将其设置为YES

分析

内部事件

默认情况下，Netmera SDK会自动跟踪并报告以下关于应用使用的行为

• 安装（首次打开）应用
• 应用打开
• 每次前台使用在应用内部度过的时间
• 推送收据（如果从仪表板进行配置）
• 推送打开
• 如果设置过任何地理围栏区域，则在该区域内进入/退出动作
• 在Netmera呈现的网页视图中采取的操作
• 日志事件（触发错误时）

除了默认的事件跟踪之外，SDK 提供了一组丰富的内置事件类，您可以使用这些类来报告您的应用程序内部用户的相应行为。

相对于接受事件内部的无结构信息，SDK 通过这些 NetmeraEvent 子类方式，要求预定义一组与事件属性及其数据类型相关的约束。这种方法允许 Netmera 验证给定事件属性的类型，并对特定事件类型强制某些属性。这些限制对于在 Netmera 服务器上执行事件分析操作提供可靠数据至关重要。

您可以使用以下代码模式轻松发送事件

// Generate event instance
// This can be any NetmeraEvent subclass
let event = NetmeraLoginEvent(userId: "user_id")
Netmera.send(event)

以下是所有内置事件类列表 - 按用途分类 - 以及它们的示例用法

• 常见事件
  • 屏幕视图事件
  • 登录事件
  • 注册事件
  • 搜索事件
  • 分享事件
  • 应用内购买事件
  • 横幅点击事件
  • 类别查看事件
  • 电池级别事件
• 商业事件
  • 商品查看事件
  • 商品评分事件
  • 商品评论事件
  • 订单取消事件
  • 购买事件
  • 购物车查看事件
  • 添加到购物车事件
  • 从购物车移除事件
  • 添加到愿望单事件
• 媒体事件
  • 内容评论事件
  • 内容评分事件
  • 内容查看事件

自定义事件

如果 SDK 提供的事件不能满足您的需求，您还可以使用 Netmera Dashboard 生成您自己的事件类。如果自定义事件要在 Netmera 中创建，它必须首先在面板中定义。
您可以从内置事件子类之一或从基本的 NetmeraEvent 类扩展您的自定义事件子类。您可以选择参数的数据类型，使它们成为数组或将它们设置为必需的。如果您不发送必需的参数，您将收到错误（错误的请求），并拒绝该请求。

您可以通过点击“开发者 -> 事件”并点击“创建新事件”按钮来生成您自己的自定义事件。最终，Netmera Dashboard 将自动为您的自定义事件生成源代码文件，这样您就可以轻松地将它们添加到项目中使用。

将源文件添加到您的项目后，您可以触发该自定义事件。

地理围栏 & 位置

在您的 pod 文件中，您应该添加 NetmeraLocation 和 NetmeraGeofence，然后像这样安装到您的应用目标中；

pod "NetmeraLocation"
pod "NetmeraGeofence"

默认情况下，Netmera SDK 不会从设备收集任何位置信息。如果您想使用 Netmera 需要位置信息的功能，比如地理围栏消息以及根据位置过滤目标用户，您必须在您的应用程序中启用位置跟踪。

为了使用位置来定位您的用户，您应启用 Web 面板中的位置历史记录。为此，请遵循“开发者 -> 应用信息 -> 应用配置 -> 启用位置历史记录”。

为您的应用程序启用位置跟踪

将适当的授权字符串添加到您的应用程序目标的 Info.plist 文件中

• 如果您的应用程序将使用地理围栏消息并支持 iOS 10 及更低版本，您 必须 设置 NSLocationAlwaysUsageDescription 键并添加一个适当的说明，解释为什么您的应用程序将使用区域监控；对于 iOS 11 和更高版本，您必须设置 NSLocationAlwaysAndWhenInUseUsageDescription 并添加一个适当的说明。
  • 在这种情况下，SDK 将监控 Netmera Dashboard 内配置的地理围栏区域的进入/退出操作。
• 如果您的应用程序只需要偶尔的位置历史信息，您可以设置 NSLocationWhenInUseUsageDescription 键并添加一个适当的说明。
  • 在这种情况下，SDK 将在每个会话中只发送一次最新位置。

请求位置授权

通过在适当的位置调用以下方法请求用户的位置授权：

Netmera.requestLocationAuthorization()

⚠️您可以使用 setNetmeraMaxActiveRegions 方法设置地理围栏的最大区域数。如果您设置的最大活动区域数大于 20 或小于 0，它将默认设置为 20。

用户

使用 NetmeraUser 类以结构化的方式将您的应用程序用户的详细信息发送到 Netmera。通常在用户登录应用程序后，会通知 Netmera 关于应用程序用户的属性。

设置属性

在您积累了有关用户的信息后，应创建一个 NetmeraUser 对象，设置值，然后调用以下示例如下所示的 [Netmera updateUser:] 方法

var user = NetmeraUser()
user.userId = userId
user.name = name
user.surname = surname
user.email = email
Netmera.updateUser(user: user)

⚠️即使将 userId 设置为 nil，也无法删除。

向用户添加自定义属性

类似于事件，如果内置属性集合不足以满足用例，则可以使用 Netmera 仪表板生成一个自定义的 NetmeraUser 子类。

如果要在 Netmera 中创建自定义属性，则必须首先在面板中定义它。（开发者 - 个人资料属性）

Netmera 将自动生成您自定义用户类的源文件，以便您轻松地将它们用于发送有关自定义属性的信息。

跟踪透明度

在您的 pod 文件中，应添加 NetmeraAdId 并安装到您的应用程序目标中，如下所示；

pod "NetmeraAdId"

请求用户授权以访问应用程序相关的数据，以跟踪用户或设备。

Netmera.requestAdvertisingAuthorization()

将向用户显示授权提示，以便 Netmera 访问设备广告标识符。

要启用或禁用应用程序中的跟踪透明度，您可以使用以下代码

Netmera.setAuthorizedAdvertisingIdentifier(authorized: true) // to enable tracking transparency within app
Netmera.setAuthorizedAdvertisingIdentifier(authorized: false) // to disable tracking transparency within app

更多信息请访问 developer.apple

深度链接

当您发送带有自定义操作按钮的推送通知时，您可以将用户重定向到应用中的任何自定义页或视图，只需指定深度链接作为自定义操作按钮的 URL。为此，您需要首先在项目中创建一个 URL 模式（your_deeplink_scheme://）。
使用 Xcode 编辑您的 Info.plist 文件
• 添加一个新的键 URL 类型。Xcode 会自动将其设置为包含名为 Item 0 的字典的数组。
• 在 Item 0 中，添加一个键 URL 标识符。将值设置为您的自定义方案。
• 在 Item 0 中，添加一个键 URL 方案。这将自动成为一个包含名为 Item 0 的字符串的数组。
• 将 URL 方案中的 Item 0 设置为您的自定义方案。
完成时，您可以确认新 URL 方案已添加到您的应用程序的 Info.plist 文件中。

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
	print("openUrl: \(url)")
	return true
}

通用链接

要检测 Netmera 推送行动提供的通用链接，该链接通常采用 https://your_domain/scheme?query 的形式，您需要在 iOS 应用中实现一个自定义处理程序。具体来说，您应在 didFinishLaunchingWithOptions 方法中添加以下代码，并确保您的 AppDelegate 遵循 NetmeraPushDelegate 协议。

//in didFinishLaunchingWithOptions
// Implement NetmeraPushDelegate in your AppDelegate
Netmera.setPushDelegate(self)

然后，您可以通过实现以下两个代理方法来处理通用链接

func shouldHandleOpenURL(_ url: URL, for pushObject: NetmeraBasePush) -> Bool {
	if url.host == "your_domain" {
		return true
	}
	return false
}

func handleOpenURL(_ url: URL, for pushObject: NetmeraBasePush) {
	print("openUrl \(url)")
}

您应在 shouldHandleOpenURL 中检查给定的 URL，是否想要执行操作，如果想要处理则返回 true。然后，当 URL 被触发时，将调用 handleOpenURL 方法，您可以使用它根据 URL 的内容执行相应的操作。

收件箱

在您的 pod 文件中，应添加 NetmeraNotificationInbox 并安装到您的应用程序目标中，如下所示；

pod "NetmeraNotificationInbox"

如果您的应用程序需要关于 Netmera 之前发送到设备的推送通知的信息，您可以使用 NetmeraInbox 类从 Netmera 获取这些信息。

此用例的最常见用途是在应用程序内以收件箱样式界面显示通知列表。

NetmeraInbox 是核心类，提供执行推通知操作所需的方法和属性，例如获取推送对象或更新推送对象的状提，但你不能直接初始化一个 NetmeraInbox 实例。你需要从 SDK 获取实例，然后在此实例上执行未来的邮箱操作。以下是使用 Netmera 邮箱功能的常见工作流程。

1. 确定要获取的推通知属性

首先，你必须创建一个 NetmeraInboxFilter 实例来定义筛选属性。通过设置此 NetmeraInboxFilter 实例的相关属性，你决定哪些推通知将被包含在获取列表中。

NetmeraInboxFilter 类提供根据以下选项的筛选

• 邮箱状态：已读/未读/已删除
• 分类：推通知所属的分类。
• 是否包括已过期的推通知。
• 页面大小：此选项不是用于筛选，而是确定一次请求中将获取的块的大小。

// 1. Define inbox manager
var  inboxManager: NetmeraInboxManager?
// 2. Create filter for fetching inbox
let filter = NetmeraInboxFilter(status: status,
								pageSize: 10,
								shouldIncludeExpiredObjects: true,
								categories: ["category_names"] //Optional
								)
// 3. Crete inbox manager instance
self.inboxManager = Netmera.inboxManager(with: filter)

2. 获取第一页并获取 NetmeraInbox 实例

现在，你可以使用以下代码从 Netmera 请求返回匹配筛选对象的推通知对象列表

inboxManager?.inbox(callback: { result in
	// List inbox
}

3. 更新推通知的状提

推通知可能有 3 种不同的状态，如下所示：

• 未读
• 已读
• 已删除

这三种状态允许你为用户实现简单的通知邮箱界面，其中用户可以阅读消息、标记以前已读的消息为未读、删除消息，如果需要可以再次恢复。

你可以使用 -updateStatus:forPushObjects:completion: 方法在邮箱内对推通知进行状态之间的转换。调用此方法将启动一个异步请求来更新指定推通知的状态，并且当请求的结果返回时将调用指定的完成块。

以下是一个示例实现，它从邮箱中删除了前 5 个推通知对象

// To update status of given push objects
inboxManager?.updateStatus(status, for: [object]) { result in
	// List inbox
}

// To update status of all push objects
inboxManager?.updateStatusForAllPushObjects(status) { result in
	// List inbox
}

4. 获取更多页面

如果你将自定义的 pageSize 值作为筛选选项，第一次获取操作的结果可能不会包含所有匹配给定筛选标准的推通知对象。在这种情况下，你可以使用以下代码获取下一个对象的块

inboxManager?.nextPage(callback: { result in
	// List inbox
}

NetmeraInbox 实例作为 -fetchInboxUsingFilter:completion: 方法的结果存储了递增获取的对象列表。具体来说，inbox.objects 属性将包括在此时的所有获取对象列表。例如，如果你将 pageSize 设置为 10，总共获取 3 页（一页通过 -fetchInboxUsingFilter:completion:，两页通过 -fetchNextPageWithCompletionBlock:），则 inbox.objects 数组将包含这三页中的所有 30 个对象。因此，当你在表视图或集合视图中向用户展示推送通知时，你可以完全依赖于这个数组。

如果由于某种原因操作失败，完成块将带有描述失败原因的 nonnull error 参数被调用。

如果你在没有任何更多页面时调用此方法，方法将立即用一个适当的错误调用完成块。

ℹ️ 你可以检查是否已获取所有页面通过 NetmeraInbox 实例的 hasNextPage 属性。当所有页面都已获取时，它将具有值 NO。

根据状提获取推通知的数量

你可以使用类似于 -countForStatus: 方法的代码向用户展示根据邮箱状提的推通知总数信息

self.inboxManager?.count(for: NetmeraInboxStatus.read)

5. 轻量级获取

// TODO

许可协议

本软件遵循 Apache License 2.0 许可协议。