BlueConic SDK for iOS

BlueConic iOS SDK 使开发者能够轻松地从其应用中收集配置文件数据。本节解释了如何将 BlueConic 集成到您的 iOS 应用中。

您可以使用 iOS SDK 进行以下操作

• 设置和检索配置文件属性值。
• 从移动设备收集应用的用户的统计数据。
• 注册点击、查看和转换。
• 使用 BlueConic 的交互。
• 使用 BlueConic 的连接
• BlueConicClient 框架

BlueConicClient 框架

BlueConicClient 框架是与 BlueConic 通信的基础。它提供了通过创建移动插件来开发您自己的交互的方式。开发者可以创建自己的移动插件并将它们实现在其 iOS 应用中。如果您的应用要与 BlueConic 通信，您必须使用 BlueConicClient 框架。除了创建自己的插件外，BlueConicClient 框架还允许您使用标准 BlueConic 插件。它包含多个插件，是标准 BlueConic 插件的移动版本，如监听器和交互。这样，BlueConic 就可以获取普通访客信息、行为和兴趣，并通过在您的应用中显示有用的交互与其互动。

• 安装
• 开始之前
• 入门
• 使用 BlueConic SDK
• 配置 BlueConic
• BlueConicClient 方法
• InteractionContext 方法
• BlueConicPlugin 方法
• 连接方法
• 许可证

安装

BlueConicClient 通过 CocoaPods 提供。要安装
它，只需将以下行添加到您的 Podfile 中

pod "BlueConicClient"

开始之前

在您开始实现 SDK 之前，请确保您有以下内容

• Xcode 的最新版本（v7.1 或更高版本）。
• BlueConic SDK for iOS
• 一个您可以用来实现 BlueConicClient SDK for iOS 的 iOS 应用。

SDK 的二进制分发文件为 iOS 8 构建。如果您的移动应用支持 iOS 7，请在您的源代码中嵌入源分发。

要测试您的移动应用，您将需要一个访问 BlueConic 环境的权限。有两个选项

• 您是否正在代表一个已设置BlueConic环境的BlueConic客户工作？如果是，请让BlueConic客户的代表请求一个可测试您移动应用的沙箱环境。
• 或者，您可以自行请求免费的Pyxis环境，并使用该环境测试您的移动应用。

入门

在开始实现SDK之前，请使用以下步骤来设置您的环境

将BlueConicClient框架添加到您的应用中：有三种方式可以这样做

• 使用CocoaPods安装 在Podfile中添加BlueConicClient。
• 添加BlueConicClient框架 在Xcode中，将BlueConicClient.framework拖入"General"选项卡下的"Embedded Binaries"部分以将iOS的BlueConicClient.framework添加到您的项目中。
• 将BlueConicClient作为源添加（支持iOS 7） 在Xcode中，将BlueConicClient源添加到您的项目中。

添加BlueConic的配置密钥：在"Supporting Files"下找到您的应用的信息属性列表文件。选择project-Info.plist，通过右键单击顶部行并选择"Add row"来添加新行。设置以下键名

bc_server_url

双击值字段，并输入您的BlueConic服务器的主机名的URL。例如

http://example.blueconic.net

添加BlueConic模拟器的URL Scheme密钥：在"Supporting Files"下找到您的应用的信息属性列表文件。选择project-Info.plist，通过右键单击顶部行并选择"Add row"来添加新行。设置以下键名

URL types

这创建了一个包含更多属性行的数组。通过单击名称前面的三角形图标打开"URL types"，右键单击"Item 0"并选择"Add row"。您也可以在该项目中添加新项，并在该项内部添加新行。设置以下键名

URL Schemes

这又会创建另一个数组。向该数组的"Item 0"添加新行，并输入您的应用的"Bundle Identifier"，例如

com.blueconic.testApp

可选，添加BlueConic的调试密钥
在"Supporting Files"下找到您的应用的信息属性列表文件。
选择project-Info.plist，通过右键单击顶部行并选择"Add row"来添加新行。设置以下键名

bc_debug

单击类型并根据需要选择'Boolean'。如果希望从BlueConic SDK接收调试日志，请将值设置为"YES"。添加调试密钥是可选的；如果不想从SDK接收调试日志，则无需添加。

导入BlueConic
iOS的BlueConic SDK使您能够为BlueConic配置设置和检索配置文件属性值，并允许执行与该BlueConic配置文件相关的交互。这些方法可以在应用的任何位置使用。在使用BlueConicClient方法之前，请确保导入框架并获取实例。

import BlueConicClient

let client = BlueConicClient.getInstance(self)

#import <BlueConicClient/BlueConicClient-swift.h>

BlueConicClient *client = [BlueConicClient getInstance:self];

在调用getInstance时，请确保提供当前ViewController作为参数。如果没有可用的ViewController，请传递一个空的ViewController。

在添加URL Scheme值后，选择AppDelegate类并添加以下方法以启用模拟器功能

// in the AppDelegate.swift file
func application(application: UIApplication, openURL url: NSURL, sourceApplication: String?, annotation: AnyObject?) -> Bool {
    BlueConicClient.getInstance(nil).setURL(url)
    return true
}

// in the AppDelegate.m file
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation {
    [[BlueConicClient getInstance:nil] setURL:url];
    return YES;
}

使用 BlueConic SDK

在每个ViewController的viewDidAppear(animated: Bool)中检索BlueConicClient的实例并创建一个PAGEVIEW事件
在实例上调用的createEvent方法中，传递一个包含screenName属性映射的对象。屏幕名称显示在旅程模拟器中，并且可以用于侦听规则或限制交互到特定的屏幕。确保在调用BlueConicClient上的"getInstance"时提供当前ViewController作为参数。如果没有可用的ViewController，则传递一个空的ViewController。

// in the ExampleViewController.swift file
import UIKit
import BlueConicClient

class ExampleViewController: UIViewController {
  private var _blueConicClient: BlueConicClient?

  override func viewDidAppear(animated: Bool) {
    super.viewDidAppear(animated)
    // Get the BlueConicClient instance.
    self._blueConicClient = BlueConicClient.getInstance(self)

    // Set screen name to identify the ViewController
    self._blueConicClient?.createEvent("PAGEVIEW", properties: ["screenName": "Main/ExampleViewController"])
  }
}

```Objective-C
in the ExampleViewController.h file
#import <UIKit/UIKit.h>
#import <BlueConicClient/BlueConicClient-Swift.h>

@interface ExampleViewController : UIViewController
@end

// Objective-C: in the ExampleViewController.m file
#import "ExampleViewController.h"

@interface ExampleViewController ()

@property BlueConicClient* client;

@end

@implementation ExampleViewController

- (void)viewDidAppear:(BOOL)animated {
  [super viewDidAppear:animated];
  // Get the BlueConic instance
  self.client = [BlueConicClient getInstance:self];

  // Set screen name to identify the ViewController
  [self.client createEvent:@"PAGEVIEW" properties:@{@"screenName": @"MAIN/ExampleViewController"}];
}

@end

检索和存储配置文件属性
BlueConic iOS SDK 可以让您设置和检索 BlueConic 配置文件的属性值。这些方法可以在任何地方使用。以下示例计算特定活动打开的次数并将此数字存储在 BlueConic 配置文件中

// Get the BlueConicClient instance.
self._blueConicClient = BlueConicClient.getInstance(self)

// Get the current value from the profile, this value is returned as a String.
let profileValue: String? = self._blueConicClient?.getProfileValue(self.PROPERTY_ID)

var newValue = 1
if (profileValue != nil && Int(profileValue!) != nil) {
  newValue = Int(profileValue!)! + 1
}

// Set the new value in the profile
self._blueConicClient?.setProfileValue(self.PROPERTY_ID, value:String(newValue))

// Get the BlueConic instance
self.client = [BlueConicClient getInstance:self];

// Get the current value from the profile, this value is returned as a String.
NSString* profileValue = [self.client getProfileValue:PROPERTY_ID];

int newValue = [profileValue intValue] + 1;

// Set the new value in the profile
[self.client setProfileValue:PROPERTY_ID value:[NSString stringWithFormat:@"%d", newValue]];

注册事件
可以在插件的 onLoad 中进行注册事件的调用。代码片段展示了如何触发点击事件。可能的事件有：“CLICK”、“VIEW”和“CONVERSION”

self._client?.createEvent("CLICK", properties: ["interactionId": self._context?.getInteractionId()])

[self.client createEvent:@"CLICK" properties:@{@"interactionId": [self.context getInteractionId]}];

配置 BlueConic

本节介绍了如何将您的移动应用程序频道添加到您的 BlueConic 宇宙，以及如何定义自定义配置属性，以便您可以在 BlueConic 段中使用它们。

将移动频道添加到您的宇宙

要开始在您的移动应用程序中测量活动并维护访客配置文件的属性值，必须将您的移动应用程序频道添加到 BlueConic 宇宙中的某个域。第一次启动应用程序时，BlueConic 将检测到它。然后必须将其添加到某个域中的“移动应用程序”类型频道中。有关管理频道的完整信息，请参阅管理频道。

自定义配置文件属性

如果要让您的移动应用程序能够将自定义属性添加到访客配置文件中并在 BlueConic 段中使用它们，则必须将这些自定义配置文件属性添加到您的插件中。有关编写自定义插件的完整信息，请参阅插件类型。有关添加自定义配置文件属性的信息

为宇宙创建位置

将您的 UIView 元素连接到您的 ViewController，以便您的 ViewController 具有连接/属性您的 UI 元素。
这可以在故事板中完成。打开您的故事板，点击 Xcode 顶部工具栏中的 'Assistant Editor'-按钮，这将允许您有_splitscreen。在左侧您将看到实际的故事板，在右侧是绑定到所选视图的 ViewController。按住 'Control'-键 将您故事板中的其中一个 View 元素拖到 ViewController。在释放鼠标按钮后，应显示一个配置弹出窗口，连接方式应为 'Outlet'，名称需要设置（注意名称应该等于您的位置 ID）。按下连接按钮，它应该看起来像

@IBOutlet weak var viewName: UIView!

@property (strong, nonatomic) IBOutlet UIView* viewName;

此元素的标识为 'viewName'，可以在宇宙中使用为 '#viewName'。BlueConic SDK 目前仅支持基于标识符选择元素。

BlueConicClient 方法

BlueConic 客户端的实现，处理配置文件检索和存储。这可能是来自缓存、客户端上的持久性存储或直接向 BlueConic 服务器发送请求。

import BlueConicClient

#import <BlueConicClient/BlueConicClient-Swift.h>

getInstance(context: UIViewController?) -> BlueConicClient

获取 BlueConic 客户端的实例。

let client: BlueConicClient = BlueConicClient.getInstance(self)

BlueConicClient *client = [BlueConicClient getInstance:self];

getProfileValue(property: String) -> String

返回给定配置文件属性的第一个值。

let hobby: String = client.getProfileValue("hobby")

NSString *hobby = [client getProfileValue:@"hobby"];

getProfileValues(property: String) -> [String]?

返回给定配置文件属性的所有值。

let hobbies: [String] = client.getProfileValues("hobbies")

NSArray *hobbies = [client getProfileValues:@"hobbies"];

getViewController() -> UIViewController?

返回当前的 ViewController。

let viewController = client.getViewController()

UIViewController *viewController = [client getViewController];

getView(selector: String) -> UIView?

根据给定的标识符返回一个视图组件，如果没有找到匹配项，则返回 nil。

@IBOutlet weak var view: UIView!
let view: UIView? = client.getView("#view")

@property (weak, nonatomic) IBOutlet UIView* view;
UIView *view = [client getView:@"#view"];

getScreenName() -> String

返回在 createEvent 中设置的 screenName 或 ViewController 的标题。

client.createEvent("PAGEVIEW", properties: ["screenName": "Main/HOMETAB"])
var screenName: String = client.getScreenName()

[client createEvent:@"PAGEVIEW" properties:@{@"screenName": @"MAIN/HOMETAB"}];
NSString *screenName = [client getScreenName];

addProfileValue(property: String, value: String)

向配置文件添加单个属性值。如果某个属性已经有值，新值也会被添加。属性值的需要是唯一的；多次传递相同的值将不会产生效果。

client.addProfileValue("hobbies", value:"tennis")

[client addProfileValue:@"hobbies" value:@"tennis"];

addProfileValues(property: String, values: [String])

将属性值添加到配置文件中。可以从集合中添加属性值到配置文件。如果某个属性已经有值，新值也会被添加。属性值的需要是唯一的；多次传递相同的值将不会产生效果。

let hobbyArray = ["tennis", "soccer"]
client.addProfileValues("hobbies", values:hobbyArray)

NSArray *hobbyArray = [NSArray arrayWithObjects:@"tennis", @"soccer", nil];
[client addProfileValues:@"hobbies" values:hobbyArray];

setProfileValue(name: String, value: String)

在配置文件上设置值。如果传递一个已经是值的属性，则会删除旧值。

client.setProfileValue("hobbies", value:"tennis")

[client setProfileValue:@"hobbies" value:@"tennis"];

setProfileValues(name: String, values: [String])

在配置文件上设置值。如果传递一个已经是值的属性，则会删除旧值。

let hobbyArray = ["tennis", "soccer"]
client.setProfileValues("hobbies", values:hobbyArray)

NSArray *hobbyArray = [NSArray arrayWithObjects:@"tennis", @"soccer", nil];
[client setProfileValues:@"hobbies" values:hobbyArray];

setLocale(locale: String)

用于获取参数的本地化设置。默认情况下使用BlueConic中配置的默认本地化。注意：当前仅有效本地化为'en_US'和'nl_NL'。

client.setLocale("en_US")

[client setLocale:@"en_US"];

setURL(url: NSURL)

检查应用程序是否使用模拟器数据启动。如果是，我们将尝试获取用户名和移动会话ID以连接到模拟器。意图应如下所示：<appID>://<hostname>/<username>/<mobilesSessionId>。

// Implement in AppDelegate.swift
func application(application: UIApplication, openURL url: NSURL, sourceApplication: String?, annotation: AnyObject?) -> Bool {
    BlueConicClient.getInstance(nil).setURL(url)
    return true
}

// Implement in AppDelegate.m
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation {
    [[BlueConicClient getInstance:nil] setURL:url];
    return YES;
}

createEvent(eventType: String, properties: Dictionary?)

注册指定类型带有给定属性的事件。对于“PAGEVIEW”事件，可以传递屏幕名，以便在BlueConic的“where”选项卡上限制交互。对于“VIEW”、“CLICK”或“CONVERSION”事件，应传递交互ID以注册该事件。

client.createEvent("PAGEVIEW", properties: ["screenName": "Main/HOMETAB"])
client.createEvent("CLICK", properties: ["interactionId": self._context.getInteractionId()])

[client createEvent:@"PAGEVIEW" properties:@{@"screenName": @"MAIN/HOMETAB"}];
[client createEvent:@"CLICK" properties:@{@"interactionId": [self._context getInteractionId]}];

InteractionContext 方法

交互上下文接口

getInteractionId() -> String?

返回交互ID。

let interactionId: String? = context.getInteractionId()

NSString *interactionId = [context getInteractionId];

InteractionContext 方法

交互上下文接口

getInteractionId() -> String?

返回交互ID。

let interactionId: String? = context.getInteractionId()

NSString *interactionId = [context getInteractionId];

getParameters() -> Dictionary

以映射的形式返回交互参数。

let parameters: Dictionary<String, [String]> = context.getParameters()

NSDictinoary *parameters = [context getParameters];

getConnection(id: String) -> Connection?

通过ID返回连接。

let context: InteractionContext!
let connection: Connection? = context.getConnection(connectionId)

InteractionContext *context;
Connection *connection = [context getConnection:connectionId];

getView() -> UIView?

返回交互的视图。

let view: UIView? = context.getView()

UIView *view = [context getView];

getPositionIdentifier() -> String?

返回位置的'selector'。

let position: String? = context.getPositionIdentifier()

NSString *position = [context getPositionIdentifier];

BlueConicPlugin 方法

BlueConic插件接口

init(client: BlueConicClient, context: InteractionContext)

创建一个新的插件实例以及客户端和交互上下文。函数应由客户端插件覆盖。

public required convenience init(client: BlueConicClient, context: InteractionContext) {
    self.init()
}

- (instancetype) initWithClient: (BlueConicClient *)client context:(InteractionContext *)context {
    self = [super init];
    return self;
}

onLoad()

当插件在服务器上注册并处于活动状态时，将触发onLoad函数。函数应由客户端插件覆盖。

public func onLoad() {
    // Implementation of the plugin
}

- (void) onLoad {
    // Implementation of the plugin
}

onDestroy()

当插件在服务器上注册并处于活动状态时，将触发onLoad函数。函数应由客户端插件覆盖。

public override func onDestroy() {
    // Implementation of the plugin
}

- (void) onDestroy {
    // Implementation of the plugin
}

连接方法

连接接口

getId() -> String

返回连接的ID。

let context: InteractionContext!
let connection: Connection? = context.getConnection(connectionId)
let connectionId = connection.getId()

InteractionContext *context;
Connection *connection = [context getConnection:connectionId];
NSString *connectionId = [connection getId];

getParameters() -> Dictionary

返回连接的参数。

let context: InteractionContext!
let connection: Connection? = context.getConnection(connectionId)
let connectionParameters: Dictionary<String, [String]> = connection.getParameters()

InteractionContext *context;
Connection *connection = [context getConnection:connectionId];
NSDictionary *connectionParameters = [connection getParameters];

许可证

BlueConicClient可在商业许可证下使用。有关更多信息，请参阅LICENSE文件。