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：您可以从网页界面的开发者 -> 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接收到弹出通知或应用内消息时，如果应用程序处于前台状态，它将立即呈现相应的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
• 您选择“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

使用轮播/滑块和小部件推送

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

• 在Xcode中，点击“文件 > 新建 > 目标”。选择Notification Content Extension
• 选择Notification Content Extension
• 您选择“Notification Content Extension”后，将创建一个新的类，名为NotificationViewController，它应该从NetmeraNotificationContentExtension类扩展。您的NotificationContent类应如下所示
• 如果您想向轮播属性添加滑块，必须添加UserInteractionEnabled
• 在此之后，您应该从功能中为您的应用程序和NotificationContent扩展启用App Groups，然后添加"bundle_identifier.group_name"到您的app groups中。
• 确保您已将app groups添加到您的应用程序中，您应在应用程序委托方法中设置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 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)

⚠️即使您将其设置为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是否要执行某些操作，如果需要，则返回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 数组将包含这三页中的所有 30 个对象。因此，您可以在将推送通知显示给用户时，仅依赖此数组来在一个表格视图或集合视图中显示。

如果由于某些原因操作失败，则完成块将带有描述失败原因的 nonnull 错误 参数被调用。

如果您在该方法在该页已无更多内容的情况下调用，则方法将立即调用带有适当错误的完成块。

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

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

您可以使用 -countForStatus: 方法像这样显示您的用户有关根据收件箱状态推送通知总数的消息：

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

5. 轻量级获取

// TODO

许可

本软件根据 Apache License 2.0 许可。