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 密钥值。

<?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 密钥值

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 密钥。

推送通知

在您的 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() 方法，它返回远程通知 payload 的对象表示。您可以使用此方法在您的 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()
  }
}

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

pod "NetmeraNotificationServiceExtension"

⚠️作为补充，如果您想允许您的应用接收http媒体内容，您应该进行以下更改

• 点击“NotificationService扩展”下的Info.plist
• 添加应用传输安全设置
• 在应用传输安全设置下添加“允许任意加载”并将其设置为“是”

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

首先，您应该在应用中创建一个新的通知内容扩展。为此，您应该遵循以下步骤

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

import UserNotifications
import UserNotificationsUI
import NetmeraNotificationContentExtension

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

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

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

pod "NetmeraNotificationContentExtension"

‼️在主界面中删除默认标签。

⚠️作为补充，如果您想允许您的应用接收http媒体内容，您应该进行以下更改

• 点击“NotificationContent扩展”下的Info.plist
• 添加应用传输安全设置
• 在应用传输安全设置下添加“允许任意加载”并将其设置为“是”

分析

内部事件

默认情况下，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)

以下列出了所有内置事件类列表——按用例分类——及其示例用法：

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

自定义事件

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

您可以通过点击“开发者 -> 事件”并创建新的事件来生成自定义事件。最后，Netmera Dashboard 将自动为您的自定义事件生成源文件，以便您可以轻松地将它们添加到项目中并使用，而无需任何麻烦。

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

地理围栏 & 位置

在您的 pod 文件中，您应该添加 NetmeraLocation 和 NetmeraGeofence，然后按如下方式安装到您的应用程序目标：

pod "NetmeraLocation"
pod "NetmeraGeofence"

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

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

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

将适当的授权字符串添加到应用程序目标的应用程序配置文件 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)

⚠️即使用户 nil，userId 也不能被移除。

向用户添加自定义属性

类似于事件，如果您使用内置属性的集合不足以满足使用案例，您可以使用 Netmera Dashboard 创建自定义的 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 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 中检查给定的URL，是否希望执行操作并返回 true 如果要处理。然后当URL通过Netmera推送操作触发时，将调用 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 参数描述失败的 reasons。

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

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

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

您可以使用 -countForStatus: 方法以这种方式显示用户有关根据收件箱状态的总推送通知数量的信息

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

5. 轻量级获取

// TODO

许可证

本软件根据 Apache License 2.0 许可。