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. 在您的应用中初始化 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：您可以从 Web 控制台的“开发者 -> 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接收到弹出通知或应用内消息时，如果应用处于前台状态，它会立即显示对应的网页内容。如果应用在收到弹出通知时处于后台状态，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
• 添加应用程序传输安全设置
• 在应用程序传输安全设置下，添加允许任意加载并将其设置为YES

使用画布/滑块和缩略图推送

首先应为您的应用创建一个新的通知内容扩展。为了做到这一点，您应该按照以下步骤进行：

• 在Xcode中点击“文件”>“新”>“目标”。选择通知内容扩展
• 选择通知内容扩展
• 选择通知内容扩展后，将创建一个新的名为NotificationViewController的类。它应该扩展自NetmeraNotificationContentExtension类。您的NotificationContent类应该看起来像这样：
• 如果您想向画布属性添加滑动功能，必须添加UserInteractionEnabled。
• 之后，您应该分别从应用和通知内容扩展的功能中启用App Groups，然后将“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)
  }
}

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

pod "NetmeraNotificationContentExtension"

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

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

• 在通知内容扩展下点击Info.plist
• 添加应用程序传输安全设置
• 在应用程序传输安全设置下，添加允许任意加载并将其设置为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 不会从设备收集任何位置信息。如果您想使用需要位置信息（例如地理围栏消息）和针对位置过滤目标用户的功能，您必须为您的应用程序启用位置跟踪。

为了使用位置来针对您的用户，您应该从网页面板中启用位置历史记录。为此，请按照开发者 -> 应用程序信息 -> 应用程序配置 -> 启用位置历史记录执行操作。

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

将适当的授权字符串添加到您的应用程序目标 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 types。Xcode将自动将其变成一个包含一个名为Item 0的字典的数组。
• 在Item 0中，添加一个键URL identifier。将值设置为您的自定义方案。
• 在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 是一个核心类，提供了执行推送通知操作所需的方法和属性，例如获取推送对象或更新推送对象的_status。但是，您不能直接初始化一个 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. 更新推送通知的状态

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

• 未读
• 已读
• 已删除

这三个状态允许您为用户实现一个简单的通知收件箱界面，其中他们可以阅读消息，将以前已阅读的消息标记为未读，删除消息，并在需要时将其恢复。

您可以使用 -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 许可。