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 Key。

推送通知

在您的 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收到弹出通知或应用内消息时，如果应用程序处于前台状态，它立即呈现相应的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 Extension中点击Info.plist
• 添加App Transport Security Settings
• 在App Transport Security Settings下，添加Allow Arbitrary Loads并将其设置为YES

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

首先，您应该为应用程序创建一个新的通知内容扩展。为了做到这一点，您应该按照以下步骤操作

• 在Xcode中，点击“文件”>“新建”>“目标”。选择通知内容扩展
• 选择通知内容扩展
• 在您选择通知内容扩展后，将创建一个新的名为NotificationViewController的类。它应该从NetmeraNotificationContentExtension类扩展。您的NotificationContent类应该看起来像这样
• 如果您想添加轮播的slide属性，必须添加UserInteractionEnabled
• 之后，您应该从功能为应用程序和NotificationContent扩展启用App Groups，并将"bundle_identifier.group_name"添加到您的app groups中。
• 确保您已将app groups添加到您的应用程序中，您应该在设置Netmera.start()方法的应用委托方法中提供app group名称，如下所示：

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呈现的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)

⚠️即使将 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 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)")
}

您应该检查给定的URL是否执行相应的操作，并在`shouldHandleOpenURL`中返回true>`。当URL通过Netmera推送操作触发时，将调用`handleOpenURL`方法，您可以使用它基于URL的内容执行适当的操作。

pod "NetmeraNotificationInbox"

// 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)

inboxManager?.inbox(callback: { result in
	// List inbox
}

// 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
}

inboxManager?.nextPage(callback: { result in
	// List inbox
}

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