总结
Proximity SDK 简化了将信标、地理围栏和接近服务集成到您的移动应用中的过程。Proximity DMP 应用程序令牌是必要的，免费注册。
目录
示例应用
您可以在 Swift 和 Objective-C 的目录中找到 examples 中的工作 XCode 示例。
获取 SDK
从我们的 GitHub 发布页面 下载最新版本。还可以查看 更改日志 以获取概述。
使用 CocoaPod
CocoaPod 是一个易于使用的 iOS 依赖管理器。如果您是 CocoaPod 新手，请阅读 入门指南。
在您的 Podfile 中添加以下行。
pod 'BeaconService', '~> 2.12.3'您也可以使用本地 pod。
pod 'BeaconService', :git => 'https://github.com/squaremetrics/ios_sdk.git', :tag => '~> 2.13.0'通过以下方式安装 SDK
cmd$ pod update就是这么简单。请继续阅读 集成说明。
使用静态框架
将 BeaconService/BeaconService.framework 文件拖放到 XCode 项目文件夹中。确保在添加文件选项菜单中选择 如果需要则复制项 和 创建组。
集成 SDK
将 SDK 添加到 XCode 项目后，需要导入 BeaconService/BIBeaconService.h 头文件并初始化 SDK。将 YOUR_APP_TOKEN 替换为从 Proximity DMP 账户（在“账户”->“应用程序”）申请的应用程序令牌。请参阅 账户设置。
您必须在 Info.plist 中添加 NSLocationAlwaysAndWhenInUseUsageDescription，NSLocationAlwaysUsageDescription 和 NSLocationWhenInUseUsageDescription 键，并给出一个简短的友好描述，说明您为何使用位置服务。由于 iOS 10，您还必须添加 NSBluetoothPeripheralUsageDescription，因为将检测信标。它仅适用于应用程序提交，不会显示给用户。
为了使靠近活动authenticateations 和位置触发器可靠地工作，您必须在项目的“功能”->“后台模式”中启用 后台获取，以确保信标和地理围栏数据每天最多同步一次。还需要一个通知处理程序。
查看权限部分了解请求用户位置服务和通知权限的方法。
使用Objective-C
在您的AppDelegate.h文件中，您需要添加头文件并引用UserNotifications框架。
#import <BeaconService/BIBeaconService.h>
#import <UserNotifications/UserNotifications.h>
@interface AppDelegate : UIResponder <UIApplicationDelegate, UNUserNotificationCenterDelegate>在您的AppDelegate.m文件中，您现在可以初始化库并添加所需的回调方法。
#import <BeaconService/BIBeaconService.h>
- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
[BIBeaconService requestAuthorization]; // optional
[BIBeaconService initWithToken:@"YOUR_APP_TOKEN"];
if (@available(iOS 10, *)) {
UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
center.delegate = self;
}
return YES;
}
-(void) userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler
{
return completionHandler(UNNotificationPresentationOptionAlert);
}
- (void)application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification {
[BIBeaconService handleNotification:notification];
}
- (void)application:(UIApplication *)application performFetchWithCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
[BIBeaconService performFetchWithCompletionHandler:completionHandler];
}使用Swift
对于Swift项目，需要一个Objective-C桥接头，并将其添加到构建设置中，包含以下行。
#import "BeaconService/BIBeaconService.h"
#import "BeaconService/BIBeaconServiceConfig.h"在您的AppDelegate中，您现在可以初始化SDK并添加所需的回调方法。
import UserNotifications
class AppDelegate: UIResponder, UIApplicationDelegate, UNUserNotificationCenterDelegate {
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
BIBeaconService.requestAuthorization() // optional
BIBeaconService.initWithToken("YOUR_APP_TOKEN")
if #available(iOS 10.0, *) {
let center = UNUserNotificationCenter.current()
center.delegate = self
}
return true
}
@available(iOS 10.0, *)
func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
BIBeaconService.handle(response.notification)
}
@available(iOS 10.0, *)
func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
return completionHandler(UNNotificationPresentationOptions.alert)
}
func application(_ application: UIApplication, performFetchWithCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
BIBeaconService.performFetch(completionHandler: completionHandler)
}
}权限
为了使位置服务和邻近性宣传活动正常工作，需要展示权限对话框。这可以通过应用上下文完全自定义和控制，即添加预权限对话框或在用户发生特定事件时延迟权限对话框的弹出。
作为一个快捷方式，您可以通过调用BeaconService.requestAuthorization()来触发弹出。
位置权限
请确保您已在Info.plist中添加了NSLocationAlwaysAndWhenInUseUsageDescription、NSLocationAlwaysUsageDescription和NSLocationWhenInUseUsageDescription键，并附上简短友好的描述，说明您为何使用位置服务。
自iOS 8以来，要求您请求用户的“始终”或“在使用时”授权。请参阅iOS 8中的核心位置。这是信标和地理围栏检测工作的要求。
locationManager.requestAlwaysAuthorization()
首先请求“在使用时”权限，然后请求“始终”权限是可以接受的。
不必要也不推荐在项目设置中启用后台模式中的位置更新。这也会使AppStore的审批过程复杂化。
通知
从iOS 8开始，接收本地通知需要权限。请参阅UserNotifications框架。
构建和测试您的应用
构建并运行项目，检查日志以确认是否接收到数据。
[BeaconService] Version 2.8.0
[BeaconService] 10 Services, 1000 Beacons, 2 Regions, 1000 Geofences
您还可以检查（1小时后）实时分析仪表板，以确认是否识别了用户活动。
在XCode中，您可以通过选择“XCode > 调试 > 模拟位置”来模拟位置更新和触发地理围栏。
设置账户
-
注册Proximity DMP账户以访问Web和移动仪表板，管理所有信标、地理围栏和接近服务。
-
在“管理”中添加附近的信标和/或地理围栏进行初始测试。对于信标，您应选择正确的供应商和UUID、主值和次值。
-
创建一个选中“所有信标”组并包含通知文本的活动。确保调度标准有效，状态为“已发布”。
-
在“账户 -> 应用程序”下获取您的
应用程序令牌。它应保密，因为它唯一标识您的移动应用程序。
常见问题解答和指南
使用指南
如何停止SDK?
要优雅地停止区域监控，您应始终使用BeaconService.terminate()，例如，当用户决定退出近距离服务时。
提交应用至AppStore时需要考虑哪些问题？
最好主动说明为什么在应用中使用定位功能。您应提及在github.com/squaremetrics/sdks上使用的Proximity SDK用于检测附近的信标。
确保您已为iOS 10或更高版本设置了NSBluetoothPeripheralUsageDescription。
什么是蓝牙信标？
信标设备是易于设置的低功耗蓝牙发射器，在建筑物内提供高精度的定位。尽管使用方便，但仍需注意以下事项。
- 权限您的应用是否请求正确的“始终定位授权”？
- 蓝牙您是否已告知移动用户启用蓝牙以从信标功能中受益？
- 信标放置是否有物体阻挡清晰的视线？
高级功能
SDK集成后，您可以使用以下功能并自定义SDK的行为。
自定义用户标识符
您可以向库传递2个自定义用户标识符，以确保与您的CRM、分析或营销系统之间的数据互操作性。所有的个人信息（PII）都应该进行散列。
您必须使用BIBeaconServiceConfig对象在初始化时设置自定义标识符。
let config = BIBeaconServiceConfig()
config.setCustomID1(ANONYMOUS_USER_ID)
config.setCustomID2(HASHED_EMAIL)
BIBeaconService.initWithToken(API_TOKEN, andConfig: config)默认情况下，如果将AdSupport.framework链接到您的应用，则会收集iOS上广告的标识符（IDFA）。此框架仅适用于显示广告或用于重新定位的应用，否则它可能是AppStore拒绝的原因之一。
带有元数据的回调
SDK默认通过NSNotificationCenter广播信标和地理围栏区域的进入、退出和更新事件。更新事件由即时、接近、远处以及大约距离变化±10m之间的距离变化定义。
只需添加具有这些通知名的观察者。
*BeaconServiceRegionEnter*
*BeaconServiceRegionUpdate*
*BeaconServiceRegionExit*
*GeofenceServiceRegionEnter*
*GeofenceServiceRegionExit*
通知的userInfo字典包含了对于信标信标ID，接近UUID，主ID，副ID，接近程度和源。对于地理围栏则是地理围栏ID，纬度，经度，半径和源。
可以在线面板中添加自定义元数据（例如，内部场地或区域ID），使用键=值对表示信标和地理围栏。
class ViewController: UIViewController {
let kEnterBeacon = Notification.Name("BeaconServiceRegionEnter")
let kUpdateBeacon = Notification.Name("BeaconServiceRegionUpdate")
let kExitBeacon = Notification.Name("BeaconServiceRegionExit")
let kEnterGeofence = Notification.Name("GeofenceServiceRegionEnter")
let kExitGeofence = Notification.Name("GeofenceServiceRegionExit")
override func viewDidLoad() {
super.viewDidLoad()
for name in [kEnterBeacon,kUpdateBeacon,kExitBeacon,kEnterGeofence,kExitGeofence] {
NotificationCenter.default.addObserver(self, selector: #selector(ViewController.didReceiveNotification(notification:)), name: name, object: nil)
}
}
@objc func didReceiveNotification(notification: NSNotification) {
print("userInfo: %@", notification.userInfo!)
}
}前台通知
要接收当应用开启时的通知，必须在AppDelegate中实现userNotificationCenter:willPresentNotification:withCompletionHandler:。
-(void) userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler
{
return completionHandler(UNNotificationPresentationOptionAlert);
}富通知
要接收带图片的通知，需要在您的活动设置中指定图片作为操作。我们建议使用以下尺寸
iOS
最大可能尺寸是1038像素 x 1038像素
Android
保持图片尺寸在最小800和最大1038像素之间
自定义通知
与邻近事件回调类似，活动事件会在没有任何强制通知的情况下广播。BeaconServiceCampaignNotification事件包含在网页门户活动详情页面上输入的所有自定义元数据，SDK将自动缓存您指定的活动图片，以便您可以直接将其作为UNNotificationAttachment对象使用，例如。
userInfo = {
source = "com.beaconinside";
title = "ACME Shop";
message = "Welcome at ACME.";
posID = 12345;
Key_23423 = "asdfa asdfasdf a dsfas\U00d6;ad -% @2";
imageURL = "file://";
notificationID = 5763263606292480;
triggeredAt = "2017-08-05T08:45:43+02:00";
}}事件在后台和前台状态下都会广播，因此请确保应用程序上下文已正确加载。
当用户单击通知、按钮或显示的横幅时，需要发送一个转换事件。这样您可以收到详细的营销和转换分析。所需的参数是userInfo字典的一部分。
+ (void)sendConversion:(NSString*)notificationID triggeredAt:(NSString*)at;if notification.name == Notification.Name("BeaconServiceCampaignNotification"),
let notificationID = userInfo["notificationID"] as? String,
let at = userInfo["triggeredAt"] as? String {
BIBeaconService.sendConversion(notificationID, triggeredAt: at)
}Webhooks
在网页面板中，您可以为其他几乎实时的服务器端用户交互事件设置webhooks。此功能默认启用。
访问API
所有数据都可以通过服务器端API访问。请查看开发者中心以了解公共Manager和Analytics API参考。
支持
如果有任何问题或疑问，请联系我们。
许可
版权（c）2014-2019 Square Metrics GmbH。保留所有权利。