ProxSee SDK for iOS

以下文档提供了有关ProxSee SDK的背景信息，并概述了设置和使用说明。

本文件的内容分为以下部分：

• 第一部分：介绍ProxSee SDK
  • 背景
  • ProxSee SDK是如何工作的？
  • 关键概念
    • 信标
    • 虚拟信标
    • 位置
    • 标签
    • 元数据
    • 签到/签出
• 第二部分：在iOS项目中实现ProxSee SDK
  • 先决条件
  • 生成移动API密钥
  • 将ProxSee SDK添加到您的iOS项目中
  • 启动ProxSee SDK
• 第三部分：使用ProxSee SDK
  • 处理标签变更集通知
    • 监听标签变更集通知
    • 接收标签变更集通知
    • 移除观察者
  • 启用/禁用ProxSee SDK
    • 启用ProxSee SDK
    • 禁用ProxSee SDK
  • 更新元数据
  • 获取检测到的信标
  • 获取设备ID
• 第四部分：常见问题解答

第一部分：介绍ProxSee SDK

背景

ProxSee SDK消除了信标交互的复杂性，并为您提供一个简化界面，快速将iBeacon™和虚拟信标（地理围栏）监控集成到您的移动应用程序中。

结合ProxSee管理员门户，ProxSee SDK允许您创建和管理标签；监听、接收和响应标签更改集通知；将用户元数据添加到签到中，并根据您的需求挖掘结果数据（例如，确定等待时间、旅行模式）。

ProxSee SDK是如何工作的？

初始化后，ProxSee SDK将为用户的移动设备分配一个唯一标识符，用于所有与中央平台的通信。ProxSee SDK开始监控信标/虚拟信标，并在检测到出入事件时将签到/签退信息发送到中央平台。

• 进入事件：用户接近信标或进入虚拟信标（地理围栏）圆形边界。当检测到进入事件时，ProxSee SDK将签到信息发送到中央平台。
• 退出事件：用户远离信标或退出虚拟信标（地理围栏）圆形边界。当检测到退出事件时，ProxSee SDK将签退信息发送到中央平台。

除了监控信标/虚拟信标外，ProxSee SDK还查询中央平台与信标/虚拟信标关联的标签信息，并自动加载和缓存附近信标/虚拟信标的信息。

ProxSee SDK允许您的应用

• 监听和接收标签更改集通知：您的应用可以监听并接收由ProxSee SDK发送的标签更改集通知。您可以通过ProxSee管理员门户更新与信标/虚拟信标关联的标签和位置信息，而无需更新ProxSee SDK或实际部署的信标。请参阅处理标签更改集通知。
• 启用/禁用ProxSee SDK：ProxSee SDK监控信标/虚拟信标，广播签到/签退，发送标签更改集通知，并更新元数据。在任何应用点，您都可以开启或关闭ProxSee SDK，以开启或关闭监控。请参阅启用/禁用ProxSee SDK。
• 更新元数据：您可以将关于用户的额外信息，如账户信息和用户ID发送到ProxSee SDK。当ProxSee SDK收到元数据时，它会将该元数据与用户的签到相关联，这有助于您在收集的数据中识别用户和设备。请参阅更新元数据。
• 获取检测到的信标：在初始化后的应用生命周期中的任何时间点，您都可以获取所有检测到的信标。请参阅获取检测到的信标。

关键概念

信标

也称为“物理信标”或“iBeacon™”，这是一个你部署并供用户的移动设备检测的物理设备。与移动设备上的基于位置的服务不同，信标测距相当精确（实质上类似于“室内GPS”），且功耗低，这使得它适用于室内及需要精准地理位置情境的地方。

一般来说，你离信标越近，报告的距离就越准确。由于上述因素，无法提供精确的准确性数值。平均而言，测量误差可能是实际距离的20-30%。你可以通过增加广播功率来提高信号可靠性。

虚拟信标

虚拟信标是一个地理围栏，它就像一个广泛范围的物理信标，但它基于用户在地图上穿越一个圆形边界，而不是靠近一个物理信标。因此，它可以作为在客户可能无法添加物理信标的位置的更不精确的信标。

地理围栏的准确性基于GPS/网络运营商。SDK的最高精度为100米。当移动设备大约移动100米时，SDK预期会收到位置更新。

位置

在ProxSee平台上，位置通过区域分组信标/虚拟信标并为区域内的每个信标/虚拟信标建立默认标签。位置还在缓存信标数据方面发挥作用。

要添加/删除位置，请参阅ProxSee管理门户中的“位置”部分。

标签

标签是用来标识和分类信标/虚拟信标的一种标签形式的简短描述。

默认情况下，每个信标/虚拟信标都有一个“#”标签（这里的“#”代表信标/虚拟信标的位置）。

你可以将相同的标签关联到多个信标/虚拟信标（例如，你可以在所有出口放置信标并将它们关联到“#Exit”标签）或者你可以选择不指定任何标签。

当信标/虚拟信标被看到（或最后被看到）时，会触发签到/签退操作，如果用户在具有相同标签的两个信标/虚拟信标之间移动，则不会在ProxSee SDK中产生新的通知。你的监听应用将在标签更改时才被通知（无论是移除标签还是添加标签）。

要添加和分配/移除标签，请参阅ProxSee管理门户中的“标签”部分。

元数据

元数据可以用来提供关于用户及其设备的信息，例如用户ID和用户偏好。发送到ProxSee SDK的元数据将被用户设备关联到每个签到。

有关添加元数据的说明，请参阅本文档中的更新元数据部分。

签到/检票

签到/检票构成一个设备事件的对，有助于跟踪进出事件。
在跟踪进出（签到/检票）事件时，请注意，您可能有一个没有相应检票的签到。

检票和检票时都会存储数据。

• 签到：大部分信息在签到时存储，包括
  • 时间
  • 设备的唯一ID（UUID）
  • 其他系统信息，包括使用的ProxSee SDK版本
• 检票：只更新并存储检票时间

第2部分：在iOS项目中实现ProxSee SDK

将ProxSee SDK集成到iOS项目中是一个简单的三步过程

1. 生成移动API密钥
2. 将ProxSee SDK添加到您的iOS项目中
3. 启动ProxSee SDK

先决条件

ProxSee SDK需要

• iOS 7+
• 一个活动蓝牙服务，以便与信标/虚拟信标一起使用
• 活动位置，以便与虚拟信标一起使用
• 首次运行时需要一个互联网连接，以便注册设备。请注意，一旦设备已注册，即可完全支持离线操作。当离线时
  • 签到/检票将被保存，并在互联网连接恢复时发送
  • 标签将不可用，除非标签可缓存在缓存中。注意：缓存的标签可能已过时

生成移动API密钥

为了使用ProxSee SDK，您需要生成一个移动API密钥。

1. 导航到ProxSee管理门户https://app.proxsee.io/#/login。
2. 在登录页面，输入您的用户名和密码，然后点击登录。
3. 在屏幕左侧的导航栏中，点击应用。
4. 点击创建应用。
5. 在API类型部分，选择移动。
6. 复制生成的GUID。这是您的移动API密钥。

注意：如果您有多个应用，您可能希望为每个应用生成一个唯一的移动API密钥。

将ProxSee SDK添加到您的iOS项目中

一旦您生成了移动API密钥，您就可以开始将ProxSee SDK添加到您的iOS项目中的过程。

注意：ProxSee SDK还可在CocoaPods上获取，网址为https://cocoapods.org.cn/pods/ProxSeeSDK

1. 将LXProxSeeSDK.framework文件添加到您的项目中。
2. 打开您的项目设置并点击构建相位标签。
3. 在链接二进制与库部分，点击+按钮并添加CoreLocation.framework。
4. 点击构建设置标签。
5. 在其他链接器标志部分，添加-ObjC。
6. 将以下键/值添加到您的Info.plist文件中。这些键/值代表在用户被提示允许位置访问时显示的文本。

至此，ProxSee SDK已准备好使用，并且您的项目可以成功编译。

启动ProxSee SDK

一旦您将ProxSee SDK添加到您的iOS项目的依赖项中，您可以使用先前步骤中生成的移动API密钥初始化ProxSee SDK。

在首次启动时，ProxSee SDK默认为开启状态，并自动启动。在首次启动后，在应用重启并调用launchProxSeeWithApiKey之后，将尝试根据SDK模式启动ProxSee SDK。多次调用launchProxSeeWithApiKey没有效果。

注意：在以下代码中，将“YourApiKey”替换为先前步骤中生成的移动API密钥。

#import <LXProxSeeSDK/LXProxSeeSDK.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
[LXProxSeeSDKManager initializeWithApiKey:@"YourApiKey"];
return YES;
}

第三章：使用ProxSee SDK

在ProxSee SDK中可以进行以下操作

• 处理标签变更集通知
• 启用/禁用ProxSee SDK
• 更新元数据
• 获取检测到的信标

处理标签更改集通知

任何对象都可以接收标签更改集通知。只有当标签改变（在信标/虚拟信标中添加或删除标签）时才会发送通知。ProxSee SDK会发送一个LXProxSeeNotificationObject，它包含更改集的新标签和旧标签，以及每个更改集的捕获日期。

处理标签更改集通知有三个步骤

1. 监听标签变更集通知
2. 接收标签变更集通知
3. 移除观察者

监听标签更改集通知

要开始监听标签更改集通知，执行以下操作

#import <LXProxSeeSDK/LXProxSeeSDK.h>
...
@interface YourObject : NSObject<LXTagsReceiver> {
...

[[[LXProxSeeSDKManager sharedInstance] tagsManager] registerReceiver:self];

接收标签更改集通知

要接收标签更改集通知，实现以下操作

- (void) didChangeTagsSet:(LXTags *)tags {
//execute your code
}

移除观察者

确保在对象释放之前或您的应用可能会崩溃之前移除观察者

[[[LXProxSeeSDKManager sharedInstance] tagsManager] unregisterReceiver:self];

启用/禁用ProxSee SDK

在任何应用的生命周期阶段，您都可以启用或禁用ProxSee SDK。禁用ProxSee SDK后，您将停止以下功能：

• 监控信标/虚拟信标
• 广播签到/签退
• 通知应用有关标签改变集
• 更新元数据

显式调用启用/禁用将相应更改SDK模式并在此应用重启之间保持不变。

启用ProxSee SDK

要启用ProxSee SDK以及相应的信标/虚拟信标监控、签到/签退广播、标签改变集通知和元数据更新，请执行以下操作

[[LXProxSeeSDKManager sharedInstance] enable];

禁用ProxSee SDK

要禁用ProxSee SDK，相应地禁用信标监控以及停止签到/签退广播、标签改变集通知和元数据更新，请执行以下操作

[[LXProxSeeSDKManager sharedInstance] disable];

更新元数据

注意：虽然函数名为updateMetadata，但每次更新都存储为其自己的记录并完整版本化。因此，建议仅在元数据有变化时发送。如果ProxSee SDK检测到元数据与之前请求没有变化，它将不会发送元数据；然而，它将对CompletionHandler返回成功结果。

以下示例展示如何添加元数据（例如用户ID、用户偏好），这将与用户每次签到相关联。

注意：键值对以JSON对象的形式存储在中央平台中。您可能希望设计您表示的方式，以便它可以轻松地用于报告目的。

[[[LXProxSeeSDKManager sharedInstance] tagsManager] updateMetadata:@{ @"key" : @"value" } completionHandler:^(BOOL success, NSError *error) {
if (!success)
{
NSLog(@"Failed to update metadata %@",error);
}
else
{
NSLog(@"Successfully updated metadata");
}
}];

获取检测到的信标

在初始化应用生命周期后的任何时间，您可以执行以下代码以获取所有检测到的信标。

[[[LXProxSeeSDKManager sharedInstance] beaconsManager] getDetectedBeaconsWithCompletionHandler:^(NSSet<LXProxSeeBeacon *> *beacons) {
       
}];

获取设备ID

在任何初始化后的应用程序生命周期阶段，您都可以执行以下代码以获取在ProxSee系统中识别您应用的唯一设备ID。

[[[LXProxSeeSDKManager sharedInstance] dataManager] getIdentifierWithCompletionHandler:^(NSUUID *deviceId) {

}];

第4节：常见问题解答

ProxSee SDK会影响我的移动设备的电池吗？

是的。ProxSee SDK将占用移动设备电池的1-2%电量。

ProxSee SDK检测到的信标需要多长时间？

• 信标：0至几秒钟。
• 虚拟信标：虚拟信标的检测基于移动和位置变化。ProxSee SDK预计在移动设备被移动大约100米时检测到虚拟信标。

作为一个使用ProxSee SDK的第三方开发者，如果我的应用程序重新启动，我需要做什么？

有关详细信息，请参阅启动ProxSee SDK部分。

当蓝牙被禁用时会发生什么？

物理信标的扫描将暂停，而虚拟信标的扫描将继续。一旦蓝牙重新启用，物理信标的扫描将恢复。请注意，ProxSee SDK必须启用监控才能接收事件。

当位置被禁用时会发生什么？

物理信标和虚拟信标的扫描都将暂停。一旦位置被重新启用，物理信标和虚拟信标的扫描将恢复。请注意，ProxSee SDK必须启用监控才能接收事件。

ProxSee SDK确认信标退出的时间有多长？

• 物理信标：ProxSee SDK确认物理信标退出的时间取决于应用程序是否处于后台或前台。
  • 后台：至少20-25秒
  • 前台：60-65秒
• 虚拟信标：通常情况下，ProxSee SDK在设备移动约100米时获取移动设备的地理位置。每次移动设备的位置更新时，ProxSee SDK都会检查更新后的位置是否位于虚拟信标的边界内。如果位置之前位于虚拟信标的边界内但现在不再，则会直接发送退出。有关更多详细信息，请参阅虚拟信标部分。

新安装的信标需要多长时间才能被ProxSee SDK接收？

从SDK版本3.0.1开始，虚拟信标和物理信标将更新如下：

• 假设SDK已启用，每次应用程序启动。
• 每次应用程序进入前台。
• 每次SDK在禁用后又启用。
• 对于任何信标检测，无论是虚拟的还是物理的，列表将在上次成功调用后24小时刷新。

对于早期版本，以下适用

• 物理信标：一旦安装了信标，如果检测到ProxSee SDK而移动设备不在附近，ProxSee SDK应直接检测到它。注意，如果在你安装ProxSee SDK的同时安装一个信标在你旁边，可能会错过标签和/或登记，具体取决于ProxSee SDK的安装或信标的检测哪一个先完成。
• 虚拟信标：一旦安装了虚拟信标，只要你不在其边界内，任何位置事件（例如，将移动设备移动100米）都会更新数据，并允许ProxSee SDK在移动设备进入虚拟信标的边界时检测它。注意，如果你在安装虚拟信标的同时在安装ProxSee SDK的信标边界内，可能会错过标签和/或登记，具体取决于ProxSee SDK的安装或虚拟信标的检测哪一个先完成。

proxsee sdk监视多少个区域？

iOS允许你监视最多20个区域，包括圆形和信标区域。Proxsee sdk最多使用13个区域。