EngageSDK 1.1.0

EngageSDK 1.1.0

测试已测试
语言语言 Obj-CObjective C
许可证 Apache 2
发布最后发布2015年2月

Silverpop Development 维护。



EngageSDK 1.1.0

  • Silverpop Development

engage-sdk-ios

Silverpop Engage SDK for iOS(又称“Silverpop 移动连接器”)

为 iOS 简化的 Engage 数据库包装器

EngageSDK 是为 iOS 开发而创建的 Engage API 包装库。我们的目标是提供一个简单的库,用于与我们的 Silverpop Engage 数据库系统远程通信。

功能

EngageSDK 是 Engage 数据库 XMLAPI 和 JSON 通用事件的包装程序。SDK 帮助开发人员与 XMLAPI 和 JSON 通用事件(UBF)网络服务进行交互。与 Engage 网络服务的所有交互都需要您首先通过从 Engage 门户获得的 OAuth 2 凭证与 Engage 建立安全连接。尽管 XMLAPI 和 UBF 具有某些共同组件,但 SDK 将每个模块的交互分成单独的组件,即 UBFManager 和 XMLAPIManager。

安装 SDK

在您发布应用之前

重要提示:为生产应用增加令牌限制

Engage 每小时的每个实例上有可以生成的访问令牌数量的限制。然而,在公开部署应用之前,您必须联系您的客户关系经理或销售代表,告知他们您打算使用此连接器,并且需要增加 OAuth 访问令牌速率限制。

演示

1.1.0 演示

$ gem install cocoapods # If necessary
$ git clone [email protected]:Silverpop/engage-sdk-ios.git
$ cd engage-sdk-ios/EngageSDK-1-1-0-Demo-ios
$ pod install
$ open EngageSDK-1-1-0-Demo-ios.xcworkspace

此演示应用演示了管理收件人移动身份的过程。

有关更多信息,请参阅演示应用的 README

1.0.0 演示

EngageSDK 包含 Example 子目录中的一个示例项目。为了构建该项目,您必须通过 CocoaPods 安装依赖项。具体操作如下:

$ gem install cocoapods # If necessary
$ git clone [email protected]:Silverpop/engage-sdk-ios.git
$ cd engage-sdk-ios/Example
$ pod install
$ touch EngageSDKDemo/sample-config.h
$ open EngageSDKDemo.xcworkspace

打开 EngageSDKDemo/sample-config.h 文件,并将下面 环境设置中的定义代码粘贴过去。

安装完成后,您可以在您的模拟器或 iPhone 设备上构建和运行 EngageSDKDemo 项目。

一旦您理解了如何通过 CocoaPods 配置 Demo 项目并使用 EngageSDK 实现,您就可以准备好将 EngageSDK 集成到您的新或现有 Xcode iPhone 项目中。

开始使用

您首先想做的事情是联系 Silverpop 的客户关系经理,并要求“Silverpop 移动连接器”。他们将帮助设置您的 Engage 帐户以支持通用行为 — 这是基于 EngageSDK 的移动应用程序行为跟踪的新灵活事件跟踪系统。

接下来,您可以按照本说明文件中的说明操作,或者作为额外的服务,我们准备了一份简短的 10 分钟教程,它将带您完成下载、安装和配置过程,使您的应用正常运行。 点击这里 在我们的知识库中查看该视频教程。

环境设置

开始的最佳方式是使用 CocoaPods。请按照 CocoaPods 网站上提供的说明,使用 Ruby Gems 安装 CocoaPods。

在 Xcode 中的现有或新 iPhone 项目中,创建一个新的 C 头文件。我们将使用此文件来定义 EngageSDK 库的重要配置数据。请在#define#endif之间复制并粘贴以下行

#define ENGAGE_BASE_URL (@"YOUR ENGAGE POD API URL")
#define ENGAGE_CLIENT_ID (@"YOUR CLIENT ID GOES HERE")
#define ENGAGE_SECRET (@"YOUR SECRET GOES HERE")
#define ENGAGE_REFRESH_TOKEN (@"YOUR REFRESH TOKEN HERE")
#define ENGAGE_LIST_ID (@"YOUR LIST ID")

使用您的值配置定义,并保存更改。如果项目是打开的,请关闭它。

打开终端并打开项目文件夹。

touch Podfile

编辑此文件以添加 EngageSDK 依赖项。

pod 'EngageSDK', '~> 1.1.0'

保存并关闭。安装 Pod 依赖项。

pod install

CocoaPods 从 GitHub 克隆 EngageSDK 文件,并创建一个所有依赖项都配置好的 Xcode 工作空间(AFNetworking、AFOAuth2),并将您的现有项目链接到一个“Pods”项目,该项目组织和管理您的依赖项,并将它们作为静态库链接到您的项目中。

打开 Xcode 工作空间,并通过添加以下行到您的代码中来导入 EngageSDK 库的公共头文件

#import "YOURSUPERSECRETCONFIGFILE.h"
#import <EngageSDK/EngageSDK.h>

提示

您可能想在 .gitignore 文件中添加以下行

#CocoaPods
*/Pods/*
*/Podfile.lock
*/YOURSUPERSECRETCONFIGFILE.h

一些开发者可能需要在安装 CocoaPods 之前安装 Xcode 命令行工具。

如果遇到 Ruby Gems 问题,请尝试执行 gem 系统更新: gem update --system

Engage SDK

要在您的 AppDelegage 类中初始化 EngageSDK,包括 (XMLAPIManager)[#XMLAPIManager] 和 (UBFManager)[UBFManager],请执行以下调用。

[EngageSDK initializeSDKClient:ENGAGE_CLIENT_ID secret:ENGAGE_SECRET token:ENGAGE_REFRESH_TOKEN host:ENGAGE_BASE_URL engageDatabaseListId:ENGAGE_LIST_ID];

UBFManager

UBFManager 管理通过 Engage JSON 通用事件 Web 服务发布 UBF 事件。应该在一个 AppDelegate 类中创建一个 UBFManager 单例实例。如果在 AppDelegate 中未初始化 UBFManager,而是在应用中的其他位置初始化,可能会导致某些 UBF 事件(如“安装”或“会话开始”)无法捕获,因为这些事件可能发生在应用中的其他任何地方初始化 UBFManager 实例之前。

目标

UBFManager 的目标是为了简单地实现将 UBF 通用事件发布到 Engage,同时隐藏给 SDK 用户的更复杂的任务管理层,例如(网络可达性、持久性和身份验证)。

  • 跟踪 UBF 事件 - 将你的个体事件发布到 Engage。考虑本地缓存,并且直到达到 "ubfEventCacheSize" 配置值时才发布事件。一旦达到该值,则将事件批量发送到 Engage,以减少网络流量。如果你不希望启用本地缓存,可以设置 "ubfEventCacheSize" 的值。
  • handleLocalNotification - 当应用程序接收到本地通知时,SDK 用户调用的工具方法。
  • handlePushNotificationReceived - 接收推送通知的工具方法。此方法还将处理通知中 EngageSDK 参数值(如当前活动(可配置))的搜索。
  • handleNotificationOpened - 打开通知的工具方法。方法将处理通知中 EngageSDK 参数值(如当前活动(可配置))的搜索。
  • handleExternalURLOpened - 打开外部 URL 的工具方法(例如设备上的电子邮件或网站深度链接)并处理通知中 EngageSDK 参数值(如当前活动(可配置))的搜索。

备注

有关 UBFManager 创建的备注。UBFManager 透明地处理网络可达性、事件持久性和客户端身份验证。UBFManager 的初始创建将使用你从 Engage 站点收到的凭据建立 OAuth 2 安全连接。即使没有建立成功的身份验证连接,UBF 事件也可以立即发布到 UBFManager。提交给管理器的事件将被简单队列和持久化,直到身份验证成功,然后它们才会被刷新到 Engage。如果设备当前没有网络可达性,UBFManager 还将本地排队和持久化事件。如果应用程序在恢复网络可达性之前关闭或关机,则事件将在下一次打开应用程序时发布。除了应用程序从设备中删除或 SDK 用户从 EngageLocalEventStore 中删除之外,本地区件在所有情况下都是持久的。

在初始 UBFManager 创建后(见 EngageSDK),你可以随时使用以下方式引用单例:

UBFManager *ubfManager = [UBFManager sharedInstance];

UBF 事件增强插件服务

在创建并发送 UBF 事件到 UBFManager 之后,UBF 还可以进一步使用来自 IOS 硬件或用户定义的外部服务接收到的数据进行增强。该功能保持了 SDK 的最大灵活性,因为它使用户能够定义自己的增强插件,在将 UBF 事件发布到 Engage API 之前对其进行增强。默认情况下,SDK 使用此框架来增强 UBF 事件的位置坐标和位置名称,例如。用户可以通过实现 UBFAugmentationPluginProtocol 接口来创建任何插件。以下是一个简单的“天气 UBF 增强插件”示例:

UBFWeatherAugmentationPlugin.h

@interface UBFWeatherAugmentationPlugin : NSObject <UBFAugmentationPluginProtocol>

-(BOOL)processSyncronously;
-(BOOL)isSupplementalDataReady;
-(UBF*)process:(UBF*)ubfEvent;

@end

UBFWeatherAugmentationPlugin.m

@implementation UBFWeatherAugmentationPlugin

-(id)init {
    self = [super init];
    if (self) {
        //Custom init logic
    }
    return self;
}

-(BOOL)processSyncronously {
    return YES; //Other plugins depend on this Plugins output for processing
}

-(BOOL)isSupplementalDataReady {
    // Your logic to decide if the data needed for the plugin to process is ready or not. Lets assume our fake weather data is.
    return YES;
}

-(UBF*)process:(UBF*)ubfEvent {
    if (ubfEvent) {
        [ubfEvent setAttribute:@"Temperatue In Celsius" value:@"100"];
        [ubfEvent setAttribute:@"Temperatue In Fahrenheit" value:@"212"];
    }
    return ubfEvent;
}

@end

为了防止UBF事件停滞或无限期地等待增强数据,为单个UBF增强放置了一个可配置的增强超时。无论你有1个插件还是1000个插件,都需要调整以满足您的需求。超时达到后,UBF事件将以传递给增强插件服务时的相同状态发布到Engage API。

通用行为API

在连接并发送通用行为之前,您应假定指定了有效的用户身份,通过XMLAPI指定了身份。请参阅MobileIdentityManager

目标完成

[[UBFManager sharedInstance] trackEvent:[UBF goalCompleted:@"LISTENED TO MVSTERMIND" params:nil]];

目标放弃

[[UBFManager sharedInstance] trackEvent:[UBF goalAbandoned:@"LISTENED TO MVSTERMIND" params:nil]];

带参数的命名事件

[[UBFManager sharedInstance] trackEvent:[UBF namedEvent:@"PLAYER LOADED" params:@{ @"Event Source View" : @"HomeViewController", @"Event Tags" : @"MVSTERMIND,Underground" }]];

XMLAPIManager

XMLAPIManager负责将XMLAPI消息发布到Engage web服务。应在AppDelegate类中创建XMLAPIManager单例实例。

初步创建XMLAPIManager之后(请参阅EngageSDK),您可以通过以下方式使用单例:

XMLAPIManager *xmlapiManager = [XMLAPIManager sharedInstance];

创建匿名用户(已弃用)

弃用,改用它里的接收者设置方法 MobileIdentityManager

// Conveniently calls addRecipient and stores anonymousId within EngageConfig
[[XMLAPIManager sharedInstance] createAnonymousUserToList:ENGAGE_LIST_ID success:^(ResultDictionary *ERXML) {
    if ([ERXML isSuccess]) {
        NSLog(@"SUCCESS");
    }
    else {
        NSLog(@"%@",[ERXML faultString]);
    }
} failure:^(NSError *error) {
    NSLog(@"SERVICE FAIL");
}];

识别已注册的用户

XMLAPI *selectRecipientData = [XMLAPI selectRecipientData:@"[email protected]" list:ENGAGE_LIST_ID];

[[XMLAPIManager sharedInstance] postXMLAPI:selectRecipientData success:^(ResultDictionary *ERXML) {
        if ([ERXML isSuccess]) {
            NSLog(@"SUCCESS");
            // VERY IMPORTANT!!!
            // Universal Behaviors reads this value
            [EngageConfig storeMobileUserId:[ERXML valueForShortPath:@"RecipientId"]];
        }
        else {
            NSLog(@"%@",[ERXML faultString]);
        }
    } failure:^(NSError *error) {
        NSLog(@"SERVICE FAIL");
    }];

将匿名用户转换为已注册用户(已弃用)

弃用,改用它里的接收者设置方法 MobileIdentityManager

// Conveniently links anonymous user record with the primary user record according to the mergeColumn
[[XMLAPIManager sharedInstance] updateAnonymousToPrimaryUser:[EngageConfig primaryUserId]
                                                   list:ENGAGE_LIST_ID
                                      primaryUserColumn:@"CONTACT_ID"
                                            mergeColumn:@"MERGE_CONTACT_ID"
                                                success:^(ResultDictionary *ERXML) {
                                                    if ([[ERXML valueForShortPath:@"SUCCESS"] boolValue]) {
                                                        NSLog(@"SUCCESS");
                                                    }
                                                    else {
                                                        NSLog(@"%@",[ERXML valueForShortPath:@"Fault.FaultString"]);
                                                    }
                                                } failure:^(NSError *error) {
                                                    NSLog(@"SERVICE FAIL");
                                                }];

MobileIdentityManager

MobileIdentityManager可用于管理用户身份。它可以在需要时自动创建新的用户身份以及合并现有的身份。此功能旨在取代创建匿名用户的手动过程。

除了正常的app安全令牌配置之外,在调用MobileIdentityManager方法之前,必须配置以下设置。

  • 接收者列表应已创建,并且在配置中设置了listId
  • EngageConfig.plist应配置有代表移动用户ID合并的接收者ID合并日期的列名。如果倾向于使用这些值,EngageConfigDefaults.plist可以定义默认值。
  • 必须 在接收者列表中创建移动用户ID合并的接收者ID合并日期列,其名称与您的EngageConfig.plist设置匹配。
  • 可选:如果您倾向于在单独的AuditRecord关系表中保存合并历史记录,可以将mergeHistoryInAuditRecordTable设置为YES,并将auditRecordListId设置为相应的列表ID。如果启用,您应在调用checkIdentityForIds之前负责创建具有审核记录ID旧接收者ID新接收者ID创建日期列的AuditRecord表。
设置接收者身份
/**
 * Checks if the mobile user id has been configured yet.  If not
 * and the 'enableAutoAnonymousTracking' flag is set to true it is auto generated
 * using either the {@link EngageDefaultUUIDGenerator} or
 * the generator configured as the 'mobileUserIdGeneratorClassName'.  If
 * 'enableAutoAnonymousTracking' is 'NO' you are responsible for
 * manually setting the id using {@code EngageConfig#storeMobileUserId}.
 * <p/>
 * Once we have a mobile user id (generated or manually set) a new recipient is
 * created with the mobile user id.
 * <p/>
 * On successful completion of this method the EngageConfig will contain the
 * mobile user id and new recipient id.
 *
 * @param didSucceed custom behavior to run on success of this method
 * @param didFail custom behavior to run on failure of this method
 */
-(void)setupRecipientWithSuccess:(void (^)(SetupRecipientResult* result))didSucceed
                         failure:(void (^)(SetupRecipientFailure* failure))didFail;
设置接收者使用情况
[[MobileIdentityManager sharedInstance] setupRecipientWithSuccess:^(SetupRecipientResult *result) {

    NSString *messageFormat = @"Recipient Id: %@\nMobile User Id: %@";
    NSString *message = [NSString stringWithFormat:messageFormat, [result recipientId], [EngageConfig mobileUserId]];
    NSLog(@"%@", message);

    // do any other custom behavior

} failure:^(SetupRecipientFailure *failure) {
    NSLog(@"Setup Recipient failure");

    // do any other custom behavior
}];
检查身份并合并收件人
/**
 * Checks for an existing recipient with all the specified ids.  If a matching recipient doesn't exist
 * the currently configured recipient is updated with the searched ids.  If an existing recipient
 * does exist the two recipients are merged and the engage app config is switched to the existing
 * recipient.
 * <p/>
 * When recipients are merged a history of the merged recipients is recorded.  By default it uses the
 * Mobile User Id, Merged Recipient Id, and Merged Date columns, however if you prefer to store
 * the merge history in a separate AuditRecord table you can set you EngageConfig.plist properties accordingly.
 * <p/>
 * WARNING: The merge process is not currently transactional.  If this method errors the data is likely to
 * be left in an inconsistent state.
 *
 * @param fieldsToIds Dictionary of column name to id value for that column.  Searches for an
 *                             existing recipient that contains ALL of the columns in the dictionary.
 *                             <p/>
 *                             Examples:
 *                             - Key: facebook_id, Value: 100
 *                             - Key: twitter_id, Value: 9999
 * @param didSucceed custom behavior to run on success of this method
 * @param didFail custom behavior to run on failure of this method
 */
 -(void)checkIdentityForIds:(NSDictionary *)fieldsToIds
                   success:(void (^)(CheckIdentityResult* result))didSucceed
                   failure:(void (^)(CheckIdentityFailure* failure))didFail;
检查身份使用情况
[[MobileIdentityManager sharedInstance] checkIdentityForIds:@{ @"facebook_id" : @"fbuser" } success:^(CheckIdentityResult *result) {

    NSString *newRecipientId = [result recipientId];
    NSString *mergedRecipientId = [result mergedRecipientId];
    NSString *mobileUserId = [result mobileUserId];

    NSString *messageFormat = @"Current recipient id: %@\nMerged recipient id: %@\nMobile user id: %@";
    NSString *message = [NSString stringWithFormat:messageFormat, newRecipientId, mergedRecipientId, mobileUserId];
    NSLog(@"%@", message);

    // do any other custom behavior

} failure:^(CheckIdentityFailure *failure) {
    NSLog(@"Check Identity failure");

    // do any other custom behavior
}];

本地事件存储

UBF事件在用户的设备上的本地SQLite数据库中持久化。事件可以有5种状态之一。分别是NOT_POSTEDSUCCESSFULLY_POSTEDFAILED_POSTHOLDEXPIRED

  • NOT_POSTED
    • 即将发送到Engage的UBF事件已准备好,但由于网络不可达或队列缓存大小尚未满足而暂不能发送。
  • SUCCESSFULLY_POSTED
    • 已成功发送到Engage的UBF事件。这些事件在达到可配置的时间后会自动清除。
  • FAILED_POST
    • UBF事件在尝试发送到Engage时已达到最大重试次数。一旦进入此状态,则不再尝试发送该UBF事件。
  • HOLD
    • 处于此状态的UBF事件已经初步创建,但数据尚未完全设置。在超时前如果无法成功通过增强服务运行,则UBF事件将被移动到NOT_POSTED状态,并将在下一次刷新时发送到Engage。设置超时有助于确保事件不会因为某些外部增强事件迟迟收不到而卡在HOLD状态。
  • EXPIRED
    • 未能完成增强的UBF事件在超时后将移至EXPIRED状态。EXPIRED事件与NOT_POSTED事件一样,有资格发送到Engage。

EngageSDK模型

EngageSDK有2个主要模型,SDK用户应该关注

UBF

是用于生成发布到UBFManager并最终发送到Engage的JSON通用事件的实用类。该类维护一个属性字典,属性值因创建的事件类型不同而不同。提供给实用方法的任何NSDictionary值将优先于实用方法从设备中检索的值。

UBF核心值

  • 设备版本
  • 操作系统名称
  • 操作系统版本
  • 应用程序名称
  • 应用程序版本
  • 设备ID
  • 移动用户ID/主用户ID
  • 匿名ID
  • 收件人ID

XMLAPI

使用辅助工具发送XMLAPI资源,例如SelectRecipientData

// create a resource encapsulating your request to select by email address
XMLAPI *selectRecipientData = [XMLAPI selectRecipientData:@"[email protected]" list:ENGAGE_LIST_ID];

[[XMLAPIManager sharedInstance] postXMLAPI:selectRecipientData success:^(ResultDictionary *ERXML) {
    // SUCCESS = TRUE
    if ([ERXML isSuccess]) {
        NSLog(@"SUCCESS");
    }
    // SUCCESS = FALSE
    // This is a specific XMLAPI failure, status 2xx
    else {
        NSLog(@"%@",[ERXML faultString]);
    }
} failure:^(NSError *error) {
    // This is a status > 400
    NSLog(@"SERVICE FAIL");
}];

XMLAPI资源

示例1

<Envelope>
    <Body>
        <SelectRecipientData>
            <LIST_ID>45654</LIST_ID>
            <EMAIL>[email protected]</EMAIL>
            <COLUMN>
                <NAME>Customer Id</NAME>
                <VALUE>123-45-6789</VALUE>
            </COLUMN>
        </SelectRecipientData>
    </Body>
</Envelope>

等价于

XMLAPI *selectRecipientData = [XMLAPI resourceNamed:XMLAPI_OPERATION_SELECT_RECIPIENT_DATA
                                             params:@{
                               @"LIST_ID" : @"45654",
                               @"EMAIL" : @"[email protected]",
                               @"COLUMNS" : @{ @"Customer Id" : @"123-45-6789" } }];

或等价于

XMLAPI *selectRecipientData = [XMLAPI resourceNamed:XMLAPI_OPERATION_SELECT_RECIPIENT_DATA];
[selectRecipientData addParams:@{ @"LIST_ID" : @"45654", @"EMAIL" : @"[email protected]" }];
[selectRecipientData addColumns:@{ @"Customer Id" : @"123-45-6789" }];

示例2

<Envelope>
    <Body>
        <SelectRecipientData>
            <LIST_ID>45654</LIST_ID>
            <RECIPIENT_ID>702003</RECIPIENT_ID>
        </SelectRecipientData>
    </Body>
</Envelope>

等价于

XMLAPI *selectRecipientData = [XMLAPI resourceNamed:XMLAPI_OPERATION_SELECT_RECIPIENT_DATA params:@{@"RECIPIENT_ID" : @"702003"}];

示例3

<Envelope>
    <Body>
        <SelectRecipientData>
            <LIST_ID>45654</LIST_ID>
            <EMAIL>[email protected]</EMAIL>
        </SelectRecipientData>
    </Body>
</Envelope>

等价于

XMLAPI *selectRecipientData = [XMLAPI selectRecipientData:@"[email protected]" list:@"45654"];

XMLAPIOperation

为了方便,您可以在XMLAPIOperation类中找到受支持的XMLAPI操作常量。

深度链接

配置

EngageSDK通过两个plist文件进行配置。一个plist文件(EngageConfigDefaults.plist)包含在SDK中,并使用下表中的配置值来推广一键式SDK方法。第二个plist文件是一个EngageConfig.plist文件,你可以(可选地)将其提供在你的项目的辅助文件中。你定义的EngageConfig.plist值始终优先于EngageConfigDefaults.plist文件中定义的配置值。建议您简单地将EngageConfigDefaults.plist文件复制并重命名为EngageConfig.plist,然后在您的项目中更改到所需的配置值。

EngageConfigManager

EngageSDK配置值在应用程序启动后存储在内存中的NSDictionary中。接收这些单个配置值是通过EngageConfigManager管理的。管理器会查询NSDictionary以获取请求的字段。EngageConfigManager接受EngageConfig中定义的常量,它们提供更多的描述性名称,指向下表中指定的实际配置值。

配置值

配置

配置名称 默认值 意义 格式
LocalEventStore->expireLocalEventsAfterNumDays 30天 在从本地存储清除engage事件之前的天数 数字
General->databaseListId {YOUR_LIST_ID} Engage Portal中的Engage数据库列表ID 字符串
General->ubfEventCacheSize 3 在批量发布之前本地缓存的事件 数字
General->defaultCurrentCampaignExpiration 1天 默认情况下当前活动即将过期的时间 EngageExpirationParser String
ParamFieldNames->ParamCampaignValidFor CampaignValidFor 从外部事件参数解析活动有效的参数名称 字符串
ParamFieldNames->ParamCampaignExpiresAt CampaignExpiresAt 从外部事件参数解析活动过期时间的参数名称 字符串
ParamFieldNames->ParamCurrentCampaign CurrentCampaign 从外部事件参数解析当前活动的参数名称 字符串
ParamFieldNames->ParamCallToAction CallToAction 从外部事件参数解析调用动作的参数名称 字符串
Session->sessionLifecycleExpiration 30分钟 触发会话结束事件之前,本地应用程序会话有效的时间 EngageExpirationParser String
Networking->maxNumRetries 3 在最终将其标记为失败并停止尝试之前,事件重试的次数 数字
UBFFieldNames->UBFSessionDurationFieldName 会话持续时长 JSON通用事件会话持续时长字段名 字符串
UBFFieldNames->UBFTagsFieldName 标签 JSON通用事件标签字段名 字符串
UBFFieldNames->UBFDisplayedMessageFieldName 显示的消息 JSON通用事件显示消息字段名 字符串
UBFFieldNames->UBFCallToActionFieldName 呼叫动作 JSON通用事件调用动作字段名 字符串
UBFFieldNames->UBFEventNameFieldName 事件名称 JSON通用事件名称字段名 字符串
UBFFieldNames->UBFGoalNameFieldName 目标名称 JSON通用事件目标字段名 字符串
UBFFieldNames->UBFCurrentCampaignFieldName 活动名称 JSON通用事件当前活动字段名 字符串
UBFFieldNames->UBFLastCampaignFieldName 最后活动 JSON通用事件最后活动字段名 字符串
UBFFieldNames->UBFLocationAddressFieldName 位置地址 JSON通用事件位置地址字段名 字符串
UBFFieldNames->UBFLocationNameFieldName 位置名称 JSON通用事件位置名称字段名 字符串
UBFFieldNames->UBFLatitudeFieldName 纬度 JSON通用事件纬度字段名 字符串
UBFFieldNames->UBFLongitudeFieldName 经度 JSON通用事件经度字段名 字符串
定位服务->最后已知位置日期格式 yyyy'-'MM'-'dd 用户最后已知位置日期格式 字符串
定位服务->最后已知位置时间戳列 最后位置地址时间 Engage数据库中最后已知位置时间对应的列名 字符串
定位服务->最后已知位置列 最后位置地址 Engage数据库中最后已知位置对应的列名 字符串
定位服务->位置距离过滤器 10 在调用更新位置信息代理前,位置变化的米数 数字
定位服务->位置精度级别 kCLLocationAccuracyBest 期望的位置精度级别 字符串
定位服务->位置缓存寿命 1小时 在被视为过期的位置坐标之前的寿命 EngageExpirationParser String
定位服务->坐标位置标记超时 15秒 在事件发布且不包含该信息之前获取CLPlacemark的超时时间 EngageExpirationParser String
定位服务->位置坐标获取超时 15秒 在事件发布且不包含该信息之前获取CLLocation的超时时间 EngageExpirationParser String
定位服务->启用 YES 定位服务是否启用对UBF事件 布尔值
增强->增强超时 15秒 增强UBF事件的超时时间 EngageExpirationParser
接收者->启用自动匿名跟踪 true 如果设置为true,允许为接收者自动生成移动用户ID。如果设置为false,则需要手动设置移动用户ID。 布尔值
接收者->移动用户ID生成类名 EngageDefaultUUIDGenerator 如果将enableAutoAnonymousTracking属性设置为true,则用于自动生成移动用户ID的类。
接收者->移动用户ID列 移动用户ID 存储移动用户ID的列名。 字符串
接收者->合并接收者ID列 合并接收者ID 在检查身份过程中,如果需要则填充合并接收者ID列的列名。 字符串
接收者->合并日期列 合并日期 存储合并日期的列名。在检查身份过程中,如果需要则填充合并接收者ID列。 字符串
接收者->合并收件历史记录到营销数据库 YES 如果需要将合并接收者的审计历史记录存储在营销数据库中。 布尔值
审计记录->审计记录主键列名 审计记录ID 只有当mergeHistoryInAuditRecordTable设置为YES时才需要。在审计记录表中生成的主键列名。 字符串
审计记录->审计记录主键生成类名 EngageDefaultUUIDGenerator 只有当mergeHistoryInAuditRecordTable设置为YES时才需要。用于为审计记录表生成主键的类。
审计记录->旧接收者ID列名 旧接收者ID 只有当mergeHistoryInAuditRecordTable设置为YES时才需要。在检查身份过程中合并接收者时,这是旧接收者ID的列名。 字符串
审计记录->新接收者ID列名 新接收者ID 只有当mergeHistoryInAuditRecordTable设置为YES时才需要。在检查身份过程中合并接收者时,这是假设接收者ID的列名。 字符串
审计记录->创建日期列名 创建日期 只有当mergeHistoryInAuditRecordTable设置为YES时才需要。在检查身份过程中合并接收者时,这是合并发生时的时间戳的列名。 字符串
审计记录->合并历史记录到审计记录表 NO 如果需要将合并接收者的审计历史记录存储在单独的审计记录表中。 布尔值
审计记录->审计记录列表ID 审计记录关系表的列表ID。只有当mergeHistoryInAuditRecordTable设置为YES时才需要。 字符串

EngageExpirationParser

EngageSDK与多种日期和过期时间进行交互。这些值既来自外部参数也来自内部配置。为了确保这些值的解释最为准确,EngageSDK创建了一个灵活的格式,以及一个特别格式,被称作“EngageExpirationParser字符串”。这个“EngageExpirationParser字符串”值可以接受任意数量的基于时间值,并提供几个方便的方法来访问从解析的值中特定的时间单位。时间单位是从创建对象时提供的参考日期计量的,或者,如果未提供参考日期,则时间字符串被视为“有效期限”值而非“过期时间”值。

EngageExpirationExamples

假设当前日期为2014年6月10日 00:00:00

EngageExpirationParser String 过期日期
1天15分钟 6/11/2014 00:15:00
15分钟1天0秒 6/11/2014 00:15:00
65分钟 6/10/2014 01:05:00
3秒 6/10/2014 00:00:03

会话

EngageSDK为通用行为实现了预定义的会话事件。会话配置为:如果用户至少5分钟没有使用您的应用,将超时。会话结束时,计算时长时将排除任何非活动期。

通知

本地通知和推送通知都需要SDK用户启用其应用程序以订阅和监听通知。这些通知钩子定义在应用程序的UIApplicationDelegage(AppDelegate)实现类中。那些钩子的完整参考资料可以在此处找到。本地和推送通知钩子的使用示例见下。

本地通知接收

- (void)application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification {
    [[UBFManager sharedInstance] handleLocalNotificationReceivedEvents:notification withParams:nil];
}

推送通知接收

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)pushNotification  {
    [[UBFManager sharedInstance] handlePushNotificationReceivedEvents:pushNotification];
}

单击通知打开应用程序 - 应用程序AppDelegate类

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    if (launchOptions != nil) {
        // Launched from push notification or local notification
        NSDictionary *notification = nil;
        if ([launchOptions objectForKey:UIApplicationLaunchOptionsRemoteNotificationKey]) {
            notification = [launchOptions objectForKey:UIApplicationLaunchOptionsRemoteNotificationKey];
        } else if ([launchOptions objectForKey:UIApplicationLaunchOptionsLocalNotificationKey]) {
            notification = [launchOptions objectForKey:UIApplicationLaunchOptionsLocalNotificationKey];
        } else {
            //Other application logic
        }

        [[UBFManager sharedInstance] handleNotificationOpenedEvents:notification];
    }
}

通过单击外部DeepLink打开应用程序 - 应用程序AppDelegate类片段

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation {
    NSURL *ubfEventUid = [[UBFManager sharedInstance] handleExternalURLOpenedEvents:url];
}

DeepLink配置

EngageSDK通过利用MobileDeepLinking库来处理DeepLink。**您必须 在应用程序中创建一个MobileDeepLinkingConfig.json文件**。MobileDeepLinkingConfig.json定义了EngageSDK将如何解析呈现在您的应用程序中的DeepLink参数,并且最终作为UBF事件的一部分发送。详细信息可以参考MobileDeepLinking网站。至少,您必须定义一个“handler”来处理URL解析。EngageSDK处理器名称为“postSilverpop”,下文提供了一个示例配置。至少,您应当在MobileDeepLinkingConfig.json文件中包含下面的示例配置中的“defaultRoute”部分。您还可以使用MobileDeepLinking注册您自己的自定义处理器并将其添加到配置文件中的处理器列表中。

{
    "logging": "true",
    "defaultRoute": {
        "handlers": [
            "postSilverpop"
        ]
    },
    "routes": {
        "test/:testId": {
            "handlers": [
                         "postSilverpop"
                         ],
            "routeParameters": {
                "testId": {
                    "required": "true",
                    "regex": "[0-9]"
                },
                "CurrentCampaign": {
                    "required": "false"
                },
                "utmSource": {
                    "required": "false"
                }
            }
        },
        "campaign/:CurrentCampaign": {
            "handlers": [
                "postSilverpop"
            ],
            "routeParameters": {
                "CurrentCampaign": {
                    "required": "true"
                },
                "CampaignEndTimeStamp": {
                    "required": "false"
                }
            }
        }
    }
}

当前活动

如果您注意到了上面的配置值,它包含一个值为“CurrentCampaign”的参数。#define#define CURRENT_CAMPAIGN_PARAM_NAME @"CurrentCampaign" 也具有默认值“CurrentCampaign”。当打开 URL 并调用 UBFManager 时,CURRENT_CAMPAIGN_PARAM_NAME 值用于搜索匹配的参数。如果找到匹配项,则将该参数的值设置为 Engage 所有后续 UBF 事件的“活动名称”。活动在通过推送通知打开的 URL 设置后具有默认过期时间 86400 秒(1 天)。如果该值不可取,您还可以提供 objective-c #define CAMPAIGN_EXTERNAL_EXPIRATION_DATETIME_PARAM @"CampaignEndTimeStamp" 值,这是一个 Linux 标准时间戳,表示您希望指定的活动何时过期。这里有一个方便的时间戳工具,可计算这些值。时间戳应为 GMT

CurrentCampaign 和 CampaignEndTimeStamp Deep link 示例

以下是假设您的应用程序配置为打开包含“Silverpop”主机值的 URL 时的一些深链接示例。

Silverpop://campaign/TestCurrentCampaign?CampaignEndTimeStamp=1419465600    //Campaign Name set to "TestCurrentCampaign" and Expires on December 25th 2014 at 12AM
Silverpop://campaign/TestCurrentCampaign   //Campaign Name set to "TestCurrentCampaign" and Expires 1 Day after the URL is opened in the application
Silverpop://campaign/TestCurrentCampaign?CampaignEndTimeStamp=30931200    //Campaign Name set to "TestCurrentCampaign" and Expires on December 25th 1970 at 12AM. So campaign is never activated

向通用行为服务发布事件

事件被缓存并以较大的批次发送以提高效率。自动派遣的时间会有所不同,但通常发生在将应用程序发送到后台时。如果您想控制事件何时发布,可以告诉 UBFClient 发布任何已缓存的事件。

手动发布缓存中的所有事件

[[UBFManager sharedInstance] postEventCache];

进一步的问题、问题或评论?

我们在 Silverpop 社区设置了论坛以促进协作,共同分享成功故事和解决共同的问题。我们邀请您在那里分享您的想法、问题和故事。