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 密钥值替换 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 密钥值替换 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 方法，因此您不需要在 App Delegate 类中实现它们。

但是，如果您的应用程序有需要自定义实现远程通知委托方法的用例，您可以自由实现它们并在这些委托方法中执行您特定的逻辑。

您可以在 UIApplicationDelegate 协议参考中找到有关推送通知委托方法的详细信息。

在委托方法中访问 NetmeraPushObject
SDK 提供了 [Netmera recentPushObject]/Netmera.recentPushObject() 方法，它返回远程通知负载的对象表示。您可以使用此方法在您的 UIApplicationDelegate 方法中访问对应于远程通知的 NetmeraPushObject 实例。

禁用/启用弹出窗口、应用内消息和小部件

当SDK接收到弹窗通知或在应用内消息时，如果应用处于前台状态，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中点击“文件 > 新建 > 目标”，选择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()
  }
}

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

pod "NetmeraNotificationServiceExtension"

⚠️此外，如果您希望允许您的应用程序接收http媒体内容，您应该进行以下更改

• 点击“NotificationService Extension”下的Info.plist
• 添加“App Transport Security Settings”
• 在“App Transport Security Settings”下添加“Allow Arbitrary Loads”并设置为“是”

使用Carousel / Slider和Thumbnail Push

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

• 在Xcode中点击“文件 > 新建 > 目标”，选择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)
  }
}

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

pod "NetmeraNotificationContentExtension"

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

⚠️此外，如果您希望允许您的应用程序接收http媒体内容，您应该进行以下更改

• 点击“Notification Content Extension”下的Info.plist
• 添加“App Transport Security Settings”
• 在“App Transport Security Settings”下添加“Allow Arbitrary Loads”并设置为“是”

分析

内部事件

默认情况下，Netmera SDK会自动跟踪并报告有关应用程序使用的以下行为

• 安装（首次打开）应用
• 应用打开
• 每次前台使用的应用内部经过的时间
• 推送通知接收信息（如果从仪表板配置）
• 推送打开
• 如果已设置的任何区域，对geofence区域的进入/退出动作
• 在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 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 的项目 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。然后，当触发带有 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 许可。