engageCore 4.0.0

engageCore 4.0.0

测试已测试
语言语言 Obj-CObjective C
许可证 NOASSERTION
发布最后发布2017年10月
SwiftSwift版本4.0

DiagnalbibinManikandan 维护。



 
依赖
Alamofire~> 4.5.1
AlamofireObjectMapper>= 0
SDVersion>= 0
 

  • 作者
  • Diagnal

N|Solid

Engage iOS SDK

Engage 是推动用户获取和转化的实时定向营销活动。它向用户推广内容,并访问客户情绪。

Engage iOS SDK 允许在几步内简单地将 Engage 集成到您的 iOS 应用程序中。Engage iOS SDK 需要 iOS 8.0 或更高版本。Engage iOS SDK 现在支持 Swift 5.1 和 Swift 5.2。

Swift 2.3 最新库版本:2.0.0

Swift 3.0 最新库版本:3.0.0

Swift 5.0 最新库版本:3.4.3

支持 Xcode 11 最新库版本:3.4.7

支持 Xcode 11.2 最新库版本:3.4.8

支持 Xcode 11.4 最新库版本:3.4.9

支持 Xcode 12(Swift 5.3)最新库版本:3.5.1

支持 Xcode 12.2(Swift 5.3)最新库版本:3.5.8

资源

入门指南

步骤 1: 安装框架

在 iOS 项目中导入 Engage iOS SDK 有两种方式:CocoaPods 手动导入。您应该使用这两种方式之一导入 Engage iOS SDK,而不是同时使用多种方式。以多种方式导入 SDK 会将 SDK 的多个副本加载到项目 中,导致编译器错误。

CocoaPods

  1. Engage iOS SDK 可通过 CocoaPods 获取。如果您尚未安装 CocoaPods,请通过运行以下命令安装 CocoaPods:

$ gem install cocoapods $ pod setup

根据您的系统设置,您可能需要使用 sudo 来安装 cocoapods,如下所示

`$ sudo gem install cocoapods`
`$ pod setup`
  1. 在您的项目目录(您的 *.xcodeproj 文件所在的目录)中,创建一个名为 Podfile 的纯文本文件(不包含任何文件扩展名)并添加以下行。用您的实际目标名称替换 YourTarget
source 'https://github.com/CocoaPods/Specs.git'

platform :ios, '8.0'
use_frameworks!

target :'YourTarget' do
pod 'engageCore'
end
  1. 然后运行以下命令

$ pod install

  1. 使用 Xcode 打开 *.xcworkspace 并开始使用 SDK。

步骤 2: 初始化客户端

SDK 的入口点是 Engage 类。我们建议在您的 UIApplicationDelegate 实现类中的 application(_:didFinishLaunchingWithOptions:) 方法中初始化客户端。

//Swift 2.3
Engage.initialize(application,didFinishLaunchingWithOptions: launchOptions, accountId: "ENGAGE_ACCOUNT_ID", projectId: "ENGAGE_PROJECT_ID")

//Swift 3.0
Engage.initialize(application: application,
didFinishLaunchingWithOptions:launchOptions,
accountId: "ENGAGE_ACCOUNT_ID",
projectId: "ENGAGE_PROJECT_ID")

ENGAGE_ACCOUNT_IDENGAGE_PROJECT_ID 可以从您的 Enage Dashboard 获取

用法

识别用户

identify 方法用于将您的用户和他们的操作关联到一个可识别的 userIdTraits。在 Traitsinit 方法中,所有参数都是可选的。

let traits = Traits(id: userId,
                    name: fullName,
                    email: email,
                    gender: genderValue,
                    age: age,
                    status: registrationStatus,
                    city: city,
                    country: country,
                    network: network,
                    customTraits: customTraits)
//Swift 2.3
Engage.identify(traits)

//Swift 3.0
Engage.identify(traits: traits)

如果 Traits 没有初始化 userId,则用户将被视为匿名。

示例 identify 调用

let traits = Traits(id: "4981498",
                    name: "Sudeep",
                    gender: GENDER.MALE,
                    age: 28,
                    status: "subscribed",
                    country: "India")

//Swift 2.3
Engage.identify(traits)

//Swift 3.0
Engage.identify(traits: traits)

跟踪

track 方法允许您记录用户执行的任何操作。您可以在指南中查看跟踪示例或在跟踪方法的负载中找到详细信息。

//Swift 2.3
Engage.track("eventName", params: params)

//Swift 3.0
Engage.track(eventName: "eventName", params: params)

track 方法具有以下参数

参数 类型 描述
eventName 字符串 您要跟踪事件的名称。
params [NSObject : AnyObject] 参数字典。

示例 track 调用

//Swift 2.3
var params = [NSObject : AnyObject]()
params["content_title"] = "How to Create a Tracking Plan"
params["content_id"] = "1234"
Engage.track("play_content", params: params)

//Swift 3.0
var params = [AnyHashable : Any]()
params["content_title"] = "How to Create a Tracking Plan"
params["content_id"] = "1234"
Engage.track(eventName: "play_content", params: params)

使用内置事件

Engage iOS SDK 预置事件功能可让您跟踪您的应用中最常用到的特定操作和事件。例如,内容视图事件可以按以下方式记录

//Swift 2.3
let eventCreator = ContentEventCreator(contentId: "series_2332")
 eventCreator.putType("series")
			 .putTitle("Game of thrones")
			 .putSource("Details page")
Engage.track(event.onContentView())

//Swift 3.0
let eventCreator = ContentEventCreator.init(contentId: contentID!).putType(type: "Movie").putTitle(title:  "Test Title")
Engage.track(event: event.onContentView())
            

Engage iOS SDK 支持以下事件创建器

事件创建器 描述
ApplicationEventCreator 应用事件事件的事件创建器
AdvertisementEventCreator 广告播放事件的事件创建器
ContentEventCreator 媒体内容事件的事件创建器
DownloadEventCreator 内容下载事件的事件创建器
PlayerEventCreator 媒体播放事件的事件创建器
PurchaseEventCreator 购买事件的事件创建器
SearchEventCreator 搜索事件的事件创建器
UserEventCreator 用户事件的事件创建器

注意:为了跟踪 AppLaunch 事件,您应该从 UIApplicationDelegate 实现类的 application(_:didFinishLaunchingWithOptions:) 中调用 ApplicationEventCreatoronAppLaunch() 事件。

//Swift 2.3
Engage.track(ApplicationEventCreator().onAppLaunch())

//Swift 3.0
Engage.track(event: ApplicationEventCreator().onAppLaunch())

推广活动

推广活动是由SDK在推广页面定义的事件触发的。您可以通过注册 CampaignEventDelegate 来了解何时触发推广活动,并根据用户与推广活动的互动获取动作字符串。

//Swift 2.3
Engage.registerForCampaignEvents(campaignEventDelegateImpl)

//Swift 3.0
Engage.registerForCampaignEvents(campaignEventDelegate: self)

CampaignEventDelegate 应由 CampaignEventDelegateImpl 对象实现。

func onCampaignTriggered(campaign : EngageCampaign) -> Bool {
///Return false if you don't want to show the campaign dialog
return true
}

func onCampaignAction(campaign : EngageCampaign) {
//use campaign object properties to perform appropriate actions in your roject
}

推送通知

Engage支持推送通知推广活动,这是一种非常有力的运行目标推广活动的方式。请按照以下步骤配置推送通知。

APNS配置

要使Engage中的推送通知推广活动生效,您需要配置应用程序以使用推送服务。有关此过程的详细说明,请参阅APNS配置文档

为通知注册

步骤1 : 前往项目目标,点击功能确保已启用“推送通知”,并在后台模式下选择“远程通知”。

步骤2 : 您需要在UIApplicationDelegate的 didFinishLaunchingWithOptions 方法中注册远程通知。

//swift2.3
func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
	let settings: UIUserNotificationSettings = UIUserNotificationSettings(forTypes: [.Alert, .Badge, .Sound], categories: nil)
	application.registerUserNotificationSettings(settings)
	application.registerForRemoteNotifications()
}

//Swift 3.0
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .sound, .badge]) {
            (granted, error) in
            if granted {
                application.registerForRemoteNotifications()
            }
        }
}

**步骤3** : 如果注册推送通知成功,您将在UIApplicationDelegate的 didRegisterForRemoteNotificationsWithDeviceToken 方法中收到回调。下一步是,您需要使用方法 Engage.registerForRemoteNotificationsWithDeviceToken(deviceToken) 从Engage注册远程通知。

//Swift 2.3
//Register remote notifications from engage. 
func application(application: UIApplication, 					    didRegisterForRemoteNotificationsWithDeviceToken 
deviceToken: NSData) {
	Engage.registerForRemoteNotificationsWithDeviceToken(deviceToken)
}

//Swift 3.0
func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {      Engage.registerForRemoteNotificationsWithDeviceToken(deviceToken: deviceToken)
}

通知Engage SDK已接收/已打开事件

Engage 使用静默推送通知进行推送通知活动。为了使 Engage 推送通知活动生效,您需要告知 Engage SDK 在您端接收/打开通知的事件。

您可以使用

//Swift 2.3
Engage.onNotificationRecieved(userInfo)
//Swift 3.0  
Engage.onNotificationRecieved(userInfo: userInfo)

//Swift 2.3
Engage.onNotificationOpened(userInfo)

//Swift 3.0
Engage.onNotificationRecieved(userInfo: userInfo)

来告知 Engage SDK 关于通知已接收/打开。这两种方法都会返回一个非空对象 NotificationData,如果接收到的通知是 Engage 通知。如果返回一个非空的 NotificationData 对象,您可以在应用程序中轻松地跳过处理这些通知。

步骤 1:在 UIApplicationDelegate 中实现 application(_:didReceiveRemoteNotification:fetchCompletionHandler:) 方法。

首先,您需要识别 didReceiveRemoteNotification 是否因为用户点击推送通知或因为用户接收推送通知而被调用。您可以使用应用程序状态来识别这一点。

switch application.applicationState {
    case .active:
        //app is currently active, iOS won't be showing any notifications in this case. Applications needs to perform operations based on the user notifications.
        break
    case .inactive:
        //app is transitioning from background to foreground (user taps notification), do what you need when user taps here
        break
    case .background:
        //app is in background, and notification is just received when app is in background.Perform any background fetches if needed.
         break
}
//Swift 2.3
// Example
func application(application: UIApplication, didReceiveRemoteNotification userInfo: [NSObject : AnyObject], fetchCompletionHandler completionHandler: (UIBackgroundFetchResult) -> Void) {
if(application.applicationState == .Inactive ) {
//User has interacted with a received notification. Inform Engage SDK a notification is opened
	if let notificationData = Engage.onNotificationOpened(userInfo) {
	 // Application can use the NotificationData object to perform any custom navigations , deep links etc.
	}
} 
else if (application.applicationState == .Background) {
//Inform Engage SDK that an event has been recieved.
  let notificationData = Engage.onNotificationRecieved(userInfo)
	}
else {
/*
Application is in Active State/ Foreground.
Inform Engage SDK that an event has been recieved.
Also ,since iOS won't be displaying a notification since application is already in foreground , application Developer can use the NotificationData object to show some custom inapp notifications or custom UI. if you are planning to show some custom UI / Inapp notifications , the you need to inform engage SDK if the user is interacted with that UI.

For iOS 10 and above you could use UNUserNotificationCenterDelegate to control whether you need to show the notification when application is in foreground.
*/
	let notificationData = Engage.onNotificationRecieved(userInfo)
	}
completionHandler(.NewData)
}

//Swift 3.0
func application(_ application: UIApplication,didReceiveRemoteNotification userInfo: [AnyHashable : Any],fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
        if(application.applicationState == .inactive ) {
            //User has interacted with a received notification. Inform Engage SDK a notification is opened
            if let notificationData = Engage.onNotificationOpened(userInfo: userInfo) {
                // Application can use the NotificationData object to perform any custom navigations , deep links etc.
            }
        }
        else if (application.applicationState == .background) {
            //Inform Engage SDK that an event has been recieved.
            let notificationData = Engage.onNotificationRecieved(userInfo: userInfo)
        }
        else {
            /*
             Application is in Active State/ Foreground.
             Inform Engage SDK that an event has been recieved.
             Also ,since iOS won't be displaying a notification since application is already in foreground , application Developer can use the NotificationData object to show some custom inapp notifications or custom UI. if you are planning to show some custom UI / Inapp notifications , the you need to inform engage SDK if the user is interacted with that UI.
             
             For iOS 10 and above you could use UNUserNotificationCenterDelegate to control whether you need to show the notification when application is in foreground.
             */
            let notificationData = Engage.onNotificationRecieved(userInfo: userInfo)
        }
        completionHandler(.newData)
    }

富推送通知活动(iOS 10 及以上版本)

集成(添加通知服务扩展)

步骤 1:进入 AppDelegate.swift,并在 appdelegate 中导入 UserNotification.framework,然后在 didFinishLaunchingWithOptions 中添加此代码。

UNUserNotificationCenter.currentNotificationCenter().delegate = self

步骤 2:您可以通过通知服务扩展启用富推送通知。在项目中创建一个通知服务扩展。在 Xcode 中,选择 File -> New -> Target 并选择通知服务扩展模板。

步骤 3:一旦添加了通知服务扩展目标,您现在可以从 pod 集成 engageCoreServiceExtension 到通知扩展目标中。

您的最终 pod 文件将看起来像下面这样

source 'https://github.com/CocoaPods/Specs.git'

platform :ios, '8.0'
use_frameworks!

target :'YourTarget' do
pod 'engageCore'
end

target "Your Notification Extension" do
    inherit! :search_paths 
    pod 'engageCoreServiceExtension'
end

然后运行以下命令

$ pod install

使用 Xcode 打开 *.xcworkspace 并开始使用 SDK。

步骤 4:一旦添加了新目标,您将有一个名为 NotificationService.swift 的新文件。

打开此类,并扩展 EngageNotificationServiceExtension 类。该类中的代码如下

import UserNotifications
import engageCoreServiceExtension
class NotificationService: EngageNotificationServiceExtension {
}

通知 Engage SDK 关于通知接收/打开事件

步骤 1:您需要告知 Engage SDK 用户已打开富推送通知。您可以通过实现 UNUserNotificationCenterDelegatedidReceiveNotificationResponse 方法来完成这一操作。

您可以通过检查对象 Engage.onNotificationOpened 返回的 nil 值来验证收到的通知是否来自 Engage。

//Swift 2.3
if let notificationData = Engage.onNotificationOpened(response.notification.request.content.userInfo) {
//Notification from Engage
}

//Swift 3.0
if let notificationData = Engage.onNotificationOpened(userInfo: response.notification.request.content.userInfo) {
//Notification from Engage
}

此外,应用程序还可以使用 response.actionIdentifier 检查用户是否通过点击通知或任何交互按钮进行了交互。

以下是一个 UNUserNotificationCenterDelegate 的实现示例:

extension AppDelegate : UNUserNotificationCenterDelegate  {
func userNotificationCenter(center: UNUserNotificationCenter, didReceiveNotificationResponse response: UNNotificationResponse, withCompletionHandler completionHandler: () -> Void) {
/* Called to let your app know which action was selected by the user for a given notification.Invoked when user taps on either notification or any custom interactive buttons in notifications.*/
 if let notificationData = Engage.onNotificationOpened(response.notification.request.content.userInfo) {
 if response.actionIdentifier == UNNotificationDefaultActionIdentifier {
  //User has interacted with the notification.
  }
  else {
  /*User has interacted with the notification interactive buttons.*/
  }
 }
}
    
func userNotificationCenter(center: UNUserNotificationCenter, willPresentNotification notification: UNNotification, withCompletionHandler completionHandler: (UNNotificationPresentationOptions) -> Void) {
/*Called when a notification is delivered to a foreground app.
Call completion handler if you want to display the notification even if the user is in foreground.*/ 
 completionHandler([.Alert])
}  
} 

//Swift 3.0

extension AppDelegate : UNUserNotificationCenterDelegate {
func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void){
/* Called to let your app know which action was selected by the user for a given notification.Invoked when user taps on either notification or any custom interactive buttons in notifications.*/
 if let notificationData = Engage.onNotificationOpened(userInfo: response.notification.request.content.userInfo) {
 if response.actionIdentifier == UNNotificationDefaultActionIdentifier {
  //User has interacted with the notification.
  }
  else {
  /*User has interacted with the notification interactive buttons.*/
  }
 }
}
    
func userNotificationCenter(_ center: UNUserNotificationCenter,
willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
/*Called when a notification is delivered to a foreground app.
Call completion handler if you want to display the notification even if the user is in foreground.*/ 
    completionHandler(.alert)
}  
}

关闭用户

如果用户从您的应用程序中注销,您需要通知 Engage SDK 停止跟踪事件作为当前用户。

为了停止跟踪当前用户,您需要调用 Engage.shutDown()

调用关闭后,EngageSDK 将禁用所有事件跟踪,直到您再次调用 identify。当新用户登录或您想跟踪匿名用户时,需要再次调用 Engage.identify(traits)

对 UNNotificationContentExtension 的支持

如果您想自定义丰富推送通知的 UI,可以通过在应用程序中集成 UNNotificationContentExtension 来实现。

要在 Engage 推送通知激活时调用 UNNotificationContentExtension,您需要在 UNNotificationContentExtension 的 info.plist 中添加 UNNotificationExtensionCategory。

EngageSDK 用于所有丰富推送通知的 UNNotificationExtensionCategoryengage.notifications

有关 UNNotificationContentExtension 的更多详细信息,请参阅 apple documentation

辅助类

辅助类提供了一种简单的方法,如果您已经使用事件分析框架,则可以轻松集成 Engage iOS SDK Engage.track("eventName", params: params)

我们目前支持 FirebaseAnalytics。

要使用辅助类,请将它们添加到您的项目中。有关 FirebaseAnalytics 的辅助类,请在此处查看 这里

如果您已经集成了 FirebaseAnalytics,只需用 EngageFIRAnalytics 替换所有以 FIRAnalytics 开头的调用即可。

示例

替换

//Swift 2.3
FIRAnalytics.logEventWithName(name, parameters: parameters)

//Swift 3.0
Analytics.logEvent(name, parameters: parameters)

//Swift 2.3
EngageFIRAnalytics.logEventWithName(name, parameters: parameters)

//Swift 3.0
EngageFIRAnalytics.logEventWithName(name: name, parameters: parameters)