TapPoint SDK

TapPoint® SDK 可让您轻松与 TapPoint® 信号网络交互，为您提供以下功能

1. 连接到 TapPoint®（验证）
2. 下载触发信息（同步）
3. 检测触发事件并在应用中对其进行响应（监控）
4. 将分析信息发送到 TapPoint®（报告）

TapPoint® SDK 参考文档也可在 TapPoint 开发者门户 上找到。

开始使用

先决条件

要使触发事件工作，您需要一个物理蓝牙信标或使用 iPhone 作为虚拟信标。

在 iTunes 应用商店中有一些现成的应用可以作为虚拟信标使用，包括我们的 Virtual Beacon app。这是开始使用最简单的方法。

如果您想深入了解，Apple 的 AirLocate 示例 代码显示了如何构建虚拟信标。

无论您有虚拟信标还是物理信标，请按照以下方式配置它

UUID中的字母大小写无所谓。这些信标在使用应用名为：sdk_reference_app（详见：使用TapPoint进行身份验证章节）时会被触发。

TapPoint® SDK使用指南

本指南也可在我们的门户入门指南找到。

先决条件

在Xcode中，请确保满足以下条件

• 部署目标设置为iOS 8.0或更高版本
• SDK版本设置为iOS 8.0 SDK或更高版本
• CFBundleDisplayName已设置有效的值。为此，导航到您的应用程序的主目标，选择信息标签页，添加一个新的行，将键设置为捆绑包显示名称

iOS 8位置服务

TapPoint® SDK使用位置服务来获取用户的当前位置信息。从iOS 8开始，使用位置服务时，您需要在应用程序的.plist文件中添加NSLocationAlwaysUsageDescription的字符串值。iOS使用此字符串在询问用户是否使用他们的位置信息时显示消息。

安装SDK

TapPoint® SDK使用CocoaPods。为了使用TapPoint® SDK，请将其添加到您的podfile中

pod 'TapPointSDK', '~> 3.7.0'

由于TapPoint® SDK使用类别，安装的最后一步需要您将链接器标志添加到应用程序的主目标中。这可以通过导航到构建设置标签页、然后在Other Linker Flags中找到并添加-ObjC作为链接器标志（如果尚未添加）来实现。

使用SDK

TapPoint® SDK提供一系列API，您可以用来

1. 通过TapPoint进行应用程序验证
2. 下载触发器（活动数据和活动有效负载）
3. 开始监测信标

这些API中的许多提供了相关且有用的反馈。在API提供失败回调的情况下，您可以检查一个NSError对象，了解失败原因的更多信息。如果API没有提供失败回调，Xcode开发环境中的调试控制台或将使用Console.app的日志消息。

您可以将<TapPointSDK/TapPointSDK.h>头文件导入以使用任何TapPoint SDK API。

通过TapPoint进行认证

通过将应用程序名称（由Proxama提供）作为参数传递给authenticateWithAppName:success:failure:方法来与TapPoint进行认证。

在AppDelegate的application:didFinishLaunchingWithOptions:方法中调用此API非常重要。

[[PRXAuthentication sharedAuthenticationManager] authenticateWithAppName:@"sdk_reference_app" success:^{
    // The application successfully authenticated with TapPoint
} failure:^(NSError *error) {
    // The application failed to authenticate with TapPoint
}];

每次应用程序启动时都应调用此API，以确保其他API被调用。

同步触发器

使用TapPoint® SDK的一个优点是即使在无网络连接的区域（地下、体育场）也能提供活动数据。触发器，其中封装了活动数据，在活动开始之前需要同步到SDK中。

为了测试目的，我们已经发送了3个物理信标以帮助您完成集成（或者如果您有iOS设备，您可以使用我们的虚拟信标应用程序来模拟信标）。要向这些触发器添加活动数据，请使用TapPoint信标有效负载编辑器工具。一旦保存，执行同步

[[PRXSynchronisation sharedSynchronisationManager] synchroniseWithSuccess:^(PRXSyncResult *result) {
    // The application synchronised successfully with TapPoint
} failure:^(NSError *error) {
    // The application failed to synchronise with TapPoint
}];

在与TapPoint成功同步后，成功块提供了一个包含添加和移除触发器的数组PRXSyncResult对象。这仅仅是为了您了解信息，TapPoint® SDK将会自动存储触发器。如果同步失败，您可以通过查看NSError对象来找到失败的原因，该对象提供了错误代码和错误描述。

同步策略

一旦触发器成功同步到设备上，您不需要再次同步，除非TapPoint上的触发器数据已更改（例如，已创建新的活动）。您有权决定何时以及何时进行同步。

简单的同步策略就是每次应用程序启动时都进行一次与TapPoint的同步。

触发器监控

触发器事件的提醒由默认的NSNotificationCenter发出，并且为了监听这些事件，您需要将自己添加为NSNotificationCenter通知事件的观察者，事件名为PRXTriggersDetectedNotification，并提供一个回调消息（例如，triggerDetected:），在触发器事件被触发时将发送该消息。

[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(triggerDetected:) name:PRXTriggersDetectedNotification object:nil];

调用startMonitoring开始扫描触发器。随后，将根据触发器事件生成通知。

[[PRXTriggers sharedTriggersManager] startMonitoring];

注意：如果您正在监控触发器事件，任何随后添加的新触发器将会自动被监控。

注意：只有当用户启用了蓝牙/位置服务时，才可检测触发器事件并发送通知，但如果用户禁用了蓝牙/位置服务，一旦再次开启它们，将自动开始检测并发送通知。无需再次调用startMonitoring。

如果您想停止监控触发器事件，请调用stopMonitoring方法来停止通知。

[[PRXTriggers sharedTriggersManager] stopMonitoring];

接收触发器事件

收到触发事件（例如，进入你正在监听的信标范围内）时，你之前定义的回调消息将被发送，你将获得封装你的活动数据的 PRXTrigger 对象。

在 NSNotification 的 userInfo 字典中可以使用 PRXDetectedTriggerNotificationKeyForTrigger 键获取 PRXTrigger 对象。这包括触发器的唯一标识符以及你之前定义的触发器数据负载。

- (void)triggerDetected:(NSNotification *)notification
{
    PRXTrigger *trigger = [notification.userInfo objectForKey:PRXDetectedTriggerNotificationKeyForTrigger];

    NSLog(@"Trigger ID: %@", trigger.identifier);
    NSLog(@"Trigger Payload: %@", trigger.payload);
}

注意： iOS 不会在设备离开信标范围的问题上报告，直到其信号长时间未被发现，足以排除蓝牙低功耗无线电信号中的临时物理干扰。这可能需要长达1分钟。

下一步

• 通过 实施反垃圾规则 来防止用户接收通知的次数。
• 增加 报告钩子 以获得对活动有效性的进一步洞察。