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. 将 Netmera 框架导入您的 AppDelegate.swift 文件中

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

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

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

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

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

当SDK收到弹出通知或应用内消息时，如果应用处于前台状态，它会立即呈现相应的web视图内容。如果应用在接收到弹出通知时处于后台状态，SDK将在应用回到前台状态时呈现web视图内容。

您可能希望禁用这种立即呈现的行为，例如当用户观看视频、处于他们最喜欢的游戏关卡中，或即将完成他们的订单购买时。您使用以下两个方法来管理此过程

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媒体内容，您应该执行以下更改

• 在NotificationService扩展下单击“Info.plist”
• 添加App Transport Security设置
• 在App Transport Security设置下添加允许任意加载并将它设置为YES

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

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

• 在Xcode中单击“文件 > 新建 > 目标”。选择通知内容扩展
• 选择通知内容扩展
• 选择“通知内容扩展”后，将创建一个名为NotificationViewController的新类。它应扩展自NetmeraNotificationContentExtension类。您的NotificationContent类应如下所示
• 如果您想添加滑到轮播功能的属性，必须添加可用手势交互
• 之后，您应该从功能中启用您的应用和通知内容扩展的应用组，然后将"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媒体内容，您应该执行以下更改

• 在通知内容扩展下单击“Info.plist”
• 添加App Transport Security设置
• 在App Transport Security设置下添加允许任意加载并将它设置为YES

分析

内部事件

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

• 安装（第一次打开）应用
• 应用程序打开
• 每次前台使用时间
• 推送通知（如果已从仪表板配置）
• 推送打开
• 如果已设置任何地理围栏区域，进入/退出动作
• Netmera提供的Web视图内采取的操作
• 日志事件（在发生错误时触发）

除了默认的事件跟踪，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不会从设备收集任何位置信息。如果您想使用需要位置信息的功能，例如地理围栏消息和根据位置定位目标用户，您必须启用应用程序的位置跟踪。

要使用位置针对您的用户，您应该在Web面板中启用位置历史记录。为了做到这一点，请按照开发者 -> 应用信息 -> 应用配置 -> 启用位置历史记录进行操作。

启用应用程序的位置跟踪

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

⚠️即使将其设置为null，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

有关更多信息，请访问https://developer.apple.com/documentation/apptrackingtransparency/attrackingmanager

深度链接

当你发送带有自定义操作按钮的推送通知时，您可以通过指定深度链接（即自定义操作按钮的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 是一个核心类，提供了对推送通知操作所需的方法和属性，例如获取推送对象或更新推送对象状态，但您不能直接初始化 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 数组将包含这3页中的所有30个对象。因此，您可以在单独使用此数组时，向用户显示推送通知，或在表格视图或收集视图中显示。

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

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

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

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

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

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

5. 轻量级获取

// TODO

许可证

此软件根据 Apache License 2.0 许可。