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 initialize方法。

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方法，因此您不需要在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
• 选择通知服务扩展后，将创建一个名为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 Settings
• 在 App Transport Security Settings 下添加 Allow Arbitrary Loads 并将其设置为 YES

使用 Carousel / Slider 和缩略图推送

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

• 在Xcode中点击文件 > 新建 > 目标。选择 Notification Content Extension
• 选择 Notification Content Extension
• 选择通知内容扩展后，将创建一个名为NotificationViewController的新类。它应扩展自 NetmeraNotificationContentExtension 类。您的NotificationContent类应如下所示
• 如果您想为Carousel添加滑动属性，请添加 UserInteractionEnabled
• 之后，您应从能力中为您的应用和NotificationContent扩展启用应用组，然后将 "bundle_identifier.group_name" 添加到您的应用组中。
• 确保您已添加应用组到您的应用中，您应在 AppDelegate 方法中提供 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 Settings
• 在 App Transport Security Settings 下添加 Allow Arbitrary Loads 并将其设置为 YES

分析

内部事件

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

• 首次安装/打开应用
• 应用打开
• 每次前台使用中在应用内部经过的时间
• 推送收据（如果通过仪表板配置）
• 推送打开
• 如果有设置地理围栏区域，则进入/退出操作
• 在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不会从设备收集任何位置信息。如果您想使用需要位置信息的功能，例如地理围栏消息和通过位置过滤目标用户，您必须启用应用程序的位置跟踪。

要使用位置来定位您的用户，您应启用Web面板中的位置历史记录。为此，请按照以下步骤操作：开发者 -> 应用信息 -> 应用配置 -> 启用位置历史记录。

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

将适当的授权字符串添加到您的应用程序目标的Info.plist文件中

• 如果您的应用程序将使用地理围栏消息且支持iOS 10和更早版本，您必须设置NSLocationAlwaysUsageDescription键并添加一个适当的描述来解释为什么您的应用程序将使用区域监控；对于iOS 11及更高版本，您必须设置NSLocationAlwaysAndWhenInUseUsageDescription并添加一个适当的描述。
  • 在这种情况下，SDK将监控Netmera仪表板内部配置的地理围栏区域内的进入/退出动作。
• 如果您的应用程序只需偶尔的位置历史信息，您可以将NSLocationWhenInUseUsageDescription键并添加一个适当的描述。
  • 在这种情况下，SDK将在每次会话中仅发送一次最新位置。

请求位置授权

在适当的位置调用以下方法请求用户的地理位置授权

Netmera.requestLocationAuthorization()

⚠️您可以使用setNetmeraMaxActiveRegions方法设置Geofence的最大区域数量。如果您设置的活动区域数量大于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 Dashboard 创建一个自定义的 NetmeraUser 子类。

如果要在 Netmera 上创建自定义属性，必须在面板中先定义它们。（开发者-Profil 属性）

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 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. 更新推送通知的状态

推送通知可能有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个对象。因此，在将推送通知显示给用户时，您可以单独依赖此数组，无论是在表格视图还是集合视图中。

如果由于某种原因操作失败，则完成块将使用描述失败原因的 null error 参数调用。

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

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

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

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

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

5. 轻量级获取

// TODO

许可证

本软件根据Apache许可证2.0许可。