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

推送通知

在您的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方法，因此您不需要在您的应用程序代理类中实现它们。

然而，如果您的应用程序有需要在远程通知委托方法上自定义实现的使用场景，您可以在其中自由实现它们，并在这些委托方法内执行您的特定逻辑。

您可以在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中，点击“文件”>“新建”>“目标”。选择 Notification Service Extension
• 选择 Notification Service Extension
• 选择“Notification Service Extension”后，将创建一个新的名为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媒体内容，您应进行以下更改：

• 在NotificationService Extension下点击Info.plist
• 添加App Transport Security设置
• 在App Transport Security设置下添加Allow Arbitrary Loads并将它设置为YES

使用Carousel/Slider和缩略图推送

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

• 在Xcode中点击“文件”>“新建”>“目标”。选择 Notification Content Extension
• 选择 Notification Content Extension
• 选择“Notification Content Extension”后，将创建一个新的名为NotificationViewController的类。它应该扩展 NetmeraNotificationContentExtension 类。您的NotificationContent类应该如下所示：
• 如果您想向Carousel属性添加滑动，必须添加UserInteractionEnabled
• 接下来，您应该为您的应用和NotificationContent扩展启用“功能”中的“App Groups”，然后将“bundle_identifier.group_name”添加到您的应用组中。
• 请确认您已将应用组添加到应用中，您应该提供在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媒体内容，您应进行以下更改：

• 在Notification Content Extension下点击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 控制台创建自己的事件类。如果要在 Netmera 中创建自定义事件，必须首先在面板中定义。
您可以从内置事件子类之一或从基类 NetmeraEvent 中扩展自定义事件子类。您可以选择参数的数据类型，将它们设置为数组或强制。如果您未发送强制参数，您将收到错误（错误请求），并且请求将被拒绝。

您可以通过点击开发者 -> 事件，然后点击创建新事件的按钮来生成您自己的自定义事件。最后，Netmera 控制台会自动为您自定义事件生成源文件，因此您只需将它们添加到您的项目中即可使用，无需任何麻烦。

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

地理围栏和位置

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

pod "NetmeraLocation"
pod "NetmeraGeofence"

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

要使用位置来定位您的用户，您应在网页面板中启用位置历史记录。为此，请按照开发者 -> 应用信息 -> 应用配置 -> 启用位置历史记录执行。

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

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

⚠️即使将《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

有关更多信息，请访问开发者苹果网站

深链接

当您发送包含自定义操作按钮的推送通知时，您可以使用指定深链接作为自定义操作按钮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》以表示您将处理。然后，《handleOpenURL》方法将在使用Netmera推送操作触发URL时调用，并可以根据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 许可。