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初始化方法。

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：您可以从Web面板的开发者 -> 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()方法，该方法返回远程通知负载的对象表示形式。您可以使用此方法来访问对应于远程通知的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 Settings
• 在App Transport Security Settings下，添加Allow Arbitrary Loads并将其设置为YES

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

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

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

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 Settings
• 在App Transport Security Settings下，添加Allow Arbitrary Loads并将其设置为YES

分析

内部事件

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

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

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

SDK 不是接受事件内部的无结构化信息，而是通过这些 NetmeraEvent 子类预设一组关于事件属性及其数据类型的约束。这种方法使得 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 不会从设备收集任何位置信息。如果您想使用需要位置信息的功能，如地理围栏消息和根据位置过滤目标用户，您必须为应用程序启用位置跟踪。

为了使用位置信息来定位您的用户，您应从 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)

⚠️即使将 nil 设置为 userId，也不能删除。

向用户添加自定义属性

类似于事件，如果内置属性集对于用例不足，您可以使用 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 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)")
}

您应检查给定的 URL 是否需要进行操作，并在 shouldHandleOpenURL 中返回 true 以执行操作。然后，当 URLs 被触发 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 参数调用。

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

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

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

您可以使用 -countForStatus: 方法显示用户根据收件箱状态推送通知的总数，如下所示：

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

5. 轻量级获取

// TODO

许可

本软件根据Apache License 2.0进行许可。