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 的 initialize 方法。

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：您可以从您的网页面板的“开发者”->“API”->“SDK API Key”获取该 API Key。

推送通知

在您的 pod 文件中，您应该添加 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接收到弹出通知或应用内消息时，如果应用处于前台状态，它将立即展示相应的WebView内容。如果应用在接收弹出时处于后台状态，SDK将在应用回到前台状态时展示WebView内容。

您可能希望禁用这种即时展示行为，例如当用户正在观看视频、在玩最喜欢的游戏等级中间、或者即将完成购物时。您可以使用以下两个方法来管理这个过程

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传输安全设置
• 在App传输安全设置下，添加允许任意加载并设置其为YES

使用旋转木马/滑块和缩略图推送

首先您应该在应用中创建一个新的通知内容扩展。为了做到这一点，您需要按照以下步骤操作

• 在Xcode中，点击“文件 > 新建 > 目标”。选择通知内容扩展
• 选择通知内容扩展
• 选择通知内容扩展后，将创建一个名为NotificationViewController的新类。它应该从NetmeraNotificationContentExtension类扩展。您的NotificationContent类应该看起来像这样
• 如果您想添加旋转木马属性中的滑动，必须添加UserInteractionEnabled
• 之后，您应该为您的应用程序和通知内容扩展在功能中启用应用组，并将"bundle_identifier.group_name"添加到应用组中。
• 确保您已将应用组添加到应用中，您应在AppDelegate方法中提供在设置Netmera.start()方法的app组名称，如下所示；

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传输安全设置
• 在App传输安全设置下，添加允许任意加载并设置其为YES

分析

内部事件

Netmera SDK默认自动跟踪并报告关于应用程序使用的以下行为

• 安装（首次打开）应用
• 应用打开
• 每次前台使用中应用内经过的时间
• 推送接收（如果从仪表板配置）
• 推送打开
• 如果有设置任何地理围栏区域的进入/退出动作
• Netmera展示的WebView内部的操作
• 记录事件（错误发生时触发）

除了默认的事件跟踪外，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仪表板生成自己的事件类。如果要在Netmera中创建自定义事件，必须首先在面板中定义它。
您可以从内置事件子类或从基本NetmeraEvent类扩展您的自定义事件子类。您可以选择参数的数据类型，将它们设置为数组或强制设置它们。如果您未发送强制参数，您将得到错误（请求无效）并且请求将被拒绝。

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

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

地理围栏和位置

在您的pod文件中，您应该在添加NetmeraLocation和NetmeraGeofence后将其安装到您的应用目标，如下所示；

pod "NetmeraLocation"
pod "NetmeraGeofence"

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

为了使用位置来定位您的用户，您应该从网络面板中启用位置历史记录。为了做到这一点，请按照“开发者”->“应用信息”->“应用配置”->“位置历史记录已启用”操作。

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

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

• 如果您的应用程序将使用地理围栏消息并支持iOS 10及以下版本，您必须设置NSLocationAlwaysUsageDescription密钥并添加适当的描述，说明您的应用程序将使用区域监测；对于iOS 11及以上版本，您必须设置NSLocationAlwaysAndWhenInUseUsageDescription和适当的描述。
  • 在这种情况下，SDK将监控Netmera仪表板内配置的地理围栏区域进入/退出动作。
• 如果您的应用程序只需要偶尔的位置历史记录信息，您可以设置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方案（你的_deeplink_scheme://）。
使用Xcode编辑您的Info.plist文件。
• 添加一个新的键URL类型。Xcode将自动将其作为包含名为Item 0的字典的数组。
• 在Item 0中，添加一个键URL标识符。将值设置为您的自定义方案。
• 在Item 0中，添加一个键URL Schemes。这将自动成为一个包含一个名为Item 0的字符串的数组。
• 将URL Schemes的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 中检查是否想要执行操作，如果想要执行，则返回 true。然后在触发带有Netmera推送操作的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 数组将包含这 3 页中的所有 30 个对象。因此，在将推送通知显示给您的用户时，您只可以依靠这个数组，无论是在表格视图还是集合视图中。

如果由于某些原因操作失败，则完成块将使用描述失败原因的 nonnull error 参数调用。

如果没有更多页面，则立即使用适当的错误调用完成块。

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

根据状态获取推送通知的数量

您可以使用 -countForStatus: 方法向您的用户显示有关根据邮箱状态的推送通知总数的消息，如下所示：

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

5. 轻量级获取

// TODO

许可证

本软件根据 Apache License 2.0 许可。