iOS-SDK
简介
Beaconstac 扩展 iOS SDK 仅适用于特定用例。在决定集成此 SDK 之前,请与支持团队联系。
文档
- 请参阅API 参考。
示例应用程序
在iTunes App Store上尝试 Beaconstac 示例应用程序。
安装
使用 Cocoapods(推荐)
将以下内容添加到您的项目 Podfile 中,我们支持 iOS 10.0+,请确保您的 pod 已正确设置平台。
platform :ios, '10.0'
target '<My-App-Target>''
pod 'Beaconstac', '~> 3.2.9'
end
在项目目录下运行 pod install
。
手动
- 在您的系统中下载或克隆此存储库。
- 将 Beaconstac.framework 文件拖放到您的 Xcode 项目中。确保选中“复制到目标文件夹”。
-
将
Beaconstac.framework
和EddystoneScanner.framework
添加到目标应用的目标的嵌入式二进制中。 -
在目标应用目标的构建阶段下,将以下框架添加到“链接二进制与库”部分
- CoreData.framework
- SystemConfiguration.framework
- CoreBluetooth.framework
- CoreLocation.framework
- EddystoneScanner.framework
配置您的项目
- 在 Info.plist 中,添加新的字段
NSLocationAlwaysUsageDescription
、NSLocationAlwaysAndWhenInUsageDescription
、NSBluetoothPeripheralUsageDescription
,提供您希望向用户显示的相关值。这对于 iOS 10 及更高版本是必需的。
先决条件
位置
应用程序应负责处理所需的权限。
- 要接收后台通知,您必须首先在应用程序目标的“功能”选项卡中启用“位置更新”和“使用蓝牙LE配件”后台模式。
var locationManager = CLLocationManager()
locationManager.delegate = self
locationManager.requestAlwaysAuthorization()
func locationManager(_ manager: CLLocationManager, didChangeAuthorization status: CLAuthorizationStatus) {
if status == .authorizedAlways {
if beaconstac != nil {
beaconstac?.startScanningBeacons()
} else {
// Initialise Beaconstac SDK
}
} else {
beaconstac?.stopScanningBeacons()
// Show Alert to enable alwyas permission
}
}
// Make sure you retain the CLLocationManager for the callbacks
// You need to handle the case where user doesn't provide `Always` permission
CLLocationManager *locationmanager = [[CLLocationManager alloc] init];
locationManager.delegate = self;
[locationManager requestAlwaysAuthorization];
- (void)locationManager:(CLLocationManager *)manager
didChangeAuthorizationStatus:(CLAuthorizationStatus)status {
if (status == kCLAuthorizationStatusAuthorizedAlways) {
if beaconstac != nil {
[beaconstac startScanningBeacons];
} else {
// Initialise Beaconstac SDK
}
} else {
[beaconstac stopScanningBeacons];
// Show Alert to enable always permission
}
}
// Make sure you retain the CLLocationManager for the callbacks
// You need to handle the case where user doesn't provide `Always` permission
- 仅在前景中接收通知
var locationManager = CLLocationManager()
locationManager.delegate = self
locationManager.requestWhenInUseAuthorization()
func locationManager(_ manager: CLLocationManager, didChangeAuthorization status: CLAuthorizationStatus) {
if status == authorizedWhenInUse || status == .authorizedAlways {
if beaconstac != nil {
beaconstac?.startScanningBeacons()
} else {
// Initialise Beaconstac SDK
}
} else {
beaconstac?.stopScanningBeacons()
// Show Alert to enable permission
}
}
// Make sure you retain the CLLocationManager for the callbacks
// You need to handle the case where user doesn't provide permission
CLLocationManager *locationmanager = [[CLLocationManager alloc] init];
locationManager.delegate = self;
[locationManager requestWhenInUseAuthorization];
- (void)locationManager:(CLLocationManager *)manager
didChangeAuthorizationStatus:(CLAuthorizationStatus)status {
if (status == kCLAuthorizationStatusAuthorizedWhenInUse || status == kCLAuthorizationStatusAuthorizedAlways) {
if beaconstac != nil {
[beaconstac startScanningBeacons];
} else {
// Initialise Beaconstac SDK
}
} else {
[beaconstac stopScanningBeacons];
// Show Alert to enable alwyas permission
}
}
// Make sure you retain the CLLocationManager for the callbacks
// You need to handle the case where user doesn't provide permission
蓝牙
应用程序应负责启用蓝牙以定位信标。
var bluetoothManager = CBCentralManager(delegate: self, queue: nil, options: nil)
func centralManagerDidUpdateState(_ central: CBCentralManager) {
if central.state == .poweredOn {
beaconstac?.startScanningBeacons()
} else {
beaconstac?.stopScanningBeacons()
}
}
// Make sure you retain the CBCentralManager for the callbacks
// You need to handle the case where user doesn't provide permission
CBCentralManager *bluetoothManager = [[CBCentralManager alloc] initWithDelegate:self queue:nil options:nil];
- (void)centralManagerDidUpdateState:(CBCentralManager *)central {
if (central.state == CBManagerStatePoweredOn) {
[beaconstac startScanningBeacons];
} else {
[beaconstac stopScanningBeacons];
}
}
// Make sure you retain the CBCentralManager for the callbacks
// You need to handle the case where user doesn't provide permission
MY_DEVELOPER_TOKEN
在初始化SDK时,应用程序应提供开发者令牌。可以从Beaconstac仪表板账户页面获取。
监控区域
如果您使用高级位置管理器的区域监控API,请确保它不会影响Beaconstac SDK。
设置
- 在类中导入框架头文件
import Beaconstac
import <Beaconstac/Beaconstac.h>
- 使用单行初始化启动
Beaconstac
,初始化后立即开始扫描信标。
do {
Beaconstac.sharedInstance("MY_DEVELOPER_TOKEN", completion: : { (beaconstac, error) in
if let beaconstacInstance = beaconstac {
// Successful...
} else if let e = error {
print(e)
}
}))
} catch let error {
print(error)
}
[Beaconstac sharedInstance:"" ibeaconOption:iBeaconOptionWhenInUseRange organization:123 delegate:self completion:^(Beaconstac * _Nullable beaconstacInstance, NSError * _Nullable error){
if (!error) {
//Successfull
} else {
NSLog("%@", error);
}
}];
- 如果您想使用
advacnced integration
,请使用以下定义的iBeaconOption
|
位置授权 | 监控 | 测距 | 描述 |
---|---|---|---|---|
当使用时 | 使用时授权 | CoreLocation API不支持 | CoreLocation API支持 | SDK仅在前景中工作 |
BackgroundRangeOnDisplayWakeUp | 始终授权 | CoreLocation API支持 | CoreLocation API支持 | SDK同时在后台工作 |
do {
Beaconstac.sharedInstance("My_DEVELOPER_TOKEN", ibeaconOption: .BackgroundRangeOnDisplayWakeUp, delegate: self, completion: : { (beaconstac, error) in
if let beaconstacInstance = beaconstac {
beaconstac?.startScanningBeacons()
// Initialization successful, it just works...
} else if let e = error {
print(e)
}
})
} catch let error {
print(error)
}
[Beaconstac sharedInstance:"" ibeaconOption:iBeaconOptionWhenInUseRange organization:123 delegate:self completion:^(Beaconstac * _Nullable beaconstacInstance, NSError * _Nullable error){
if (!error) {
//Successfull
[beaconstacInstance startScanningBeacons];
} else {
NSLog("%@", error);
}
}];
- 如果您希望获取Beaconstac SDK的 sharedInstance(),在单个应用程序生命周期中的任何点初始化Beaconstac SDK后
do {
beaconstacInstance = try Beaconstac.sharedInstance()
} catch let error {
print(error)
}
NSError *error = nil;
[Beaconstac sharedInstanceAndReturnError:&error];
- 如果您希望控制信标扫描的开始和停止
beaconstac.startScanningBeacons() // Starts scanning for beacons...
beaconstac.stopScanningBeacons() // Stops scanning for beacons...
[beaconstacInstance startScanningBeacons];
[beaconstacInstance stopScanningBeacons];
- 实现
BeaconDelegate
协议方法以在扫描到信标时接收回调
// In the class where you want to listen to the beacon scanning events...
beaconstacInstance = try! Beaconstac.sharedInstance()
beaconstacInstance.delegate = self
// required
func didFail(_ beaconstac: Beaconstac, error: Error) {
print(error)
}
//Optional
func didEnterRegion(_ beaconstac: Beaconstac, region: String) {
print(region)
}
func didRangeBeacons(_ beaconstac: Beaconstac, beacons: [MBeacon]) {
print(beacons)
}
func didEnterBeacon(_ beaconstac: Beaconstac, beacon: MBeacon) {
print(beacon)
}
func didExitBeacon(_ beaconstac: Beaconstac, beacon: MBeacon) {
print(beacon)
}
func didExitRegion(_ beaconstac: Beaconstac, region: String) {
print(region)
}
// In the class where you want to listen to the beacon scanning events...
NSError *error = nil;
Beconstac *beaconstacInstance = [Beaconstac sharedInstanceAndReturnError:&error];
beaconstacInstance.delegate = self;
// required
- (void)didFail:(Beaconstac * _Nonnull)beaconstac error:(NSError * _Nonnull)error {
NSLog("%@", error);
}
//Optional
- (void)didEnterRegion:(Beaconstac * _Nonnull)beaconstac region:(NSString * _Nonnull)region {
NSLog("%@", region);
}
- (void)didRangeBeacons:(Beaconstac * _Nonnull)beaconstac beacons:(NSArray<MBeacon *> * _Nonnull)beacons {
NSLog("%@", beacons);
}
- (void)campOnBeacon:(Beaconstac * _Nonnull)beaconstac beacon:(MBeacon * _Nonnull)beacon {
NSLog("%@", beacon);
}
- (void)exitBeacon:(Beaconstac *)beaconstac beacon:(MBeacon *)beacon {
NSLog("%@", beacon);
}
- (void)didExitRegion:(Beaconstac * _Nonnull)beaconstac region:(NSString * _Nonnull)region {
NSLog("%@", region);
}
- 实现
RuleProcessorDelegate
协议方法以在规则触发时接收回调
// In the class where you want to listen to the rule triggering events...
beaconstacInstance = try! Beaconstac.sharedInstance()
beaconstacInstance.ruleDelegate = self
func willTriggerRule(_ beaconstac: Beaconstac, rule: MRule) {
// read which rule is about to trigger and the actions, filters set by the marketers...
}
func didTriggerRule(_ beaconstac: Beaconstac, rule: MRule) {
// read which rule is triggered and the actions, filters set by the marketers...
}
// In the class where you want to listen to the rule triggering events...
NSError *error = nil;
Beconstac *beaconstacInstance = [Beaconstac sharedInstanceAndReturnError:&error];
beaconstacInstance.ruleDelegate = self;
- (void)willTriggerRule:(Beaconstac * _Nonnull)beaconstac rule:(MRule * _Nonnull)rule {
// read which rule is about to trigger and the actions, filters set by the marketers...
}
- (void)didTriggerRule:(Beaconstac * _Nonnull)beaconstac rule:(MRule * _Nonnull)rule {
// read which rule is triggered and the actions, filters set by the marketers...
}
- 实现
NotificationDelegate
协议方法以重写本地通知的显示
// In the class where you want to listen to notification events...
beaconstacInstance = try! Beaconstac.sharedInstance()
beaconstacInstance.notificationDelegate = self
func overrideNotification(_ beaconstac: Beaconstac, notification: MNotification) {
// If you override, you should handle everything from configuring, triggering and displaying of the notification.
}
// In the class where you want to listen to notification events...
NSError *error = nil;
Beconstac *beaconstacInstance = [Beaconstac sharedInstanceAndReturnError:&error];
beaconstacInstance.notificationDelegate = self;
- (void)overrideNotification:(Beaconstac * _Nonnull)beaconstac notification:(MNotification * _Nonnull)notification {
// If you override, you should handle everything from configuring, triggering and displaying of the notification.
}
- 实现
WebhookDelegate
协议方法以将额外参数发送到webhook
// In the class where you want to listen to webhook events...
beaconstacInstance = try! Beaconstac.sharedInstance()
beaconstacInstance.webhookDelegate = self
func addParameters(_ beaconstac: Beaconstac, webhook: MWebhook) -> Dictionary<String, Any> {
// If you override, make sure the keys of the previously added ones
}
// In the class where you want to listen to notification events...
NSError *error = nil;
Beconstac *beaconstacInstance = [Beaconstac sharedInstanceAndReturnError:&error];
beaconstacInstance.webhookDelegate = self;
- (NSDictionary<NSString *, id> * _Nonnull)addParameters:(Beaconstac * _Nonnull)beaconstac webhook:(MWebhook * _Nonnull)webhook {
// If you override, make sure the keys of the previously added ones
}
Latch_Latency
定义了SDK找到信标时调整campOn/campOff行为的方式。假设SDK停留在某个信标上,另一个信标的最新RSSI小于停留在信标上的信标的最新RSSI加上latch latency,那么SDK将离开当前信标,并停留在这个信标上。
beaconstacInstance = try! Beaconstac.sharedInstance()
beaconstacInstance.latchLatency = HIGH
NSError *error = nil;
Beconstac *beaconstacInstance = [Beaconstac sharedInstanceAndReturnError:&error];
beaconstacInstance.latchLatency = LatchLatencyHIGH;
- 如果您没有监听
NotificationDelegate
协议,SDK会配置并触发UNNotification。但是为了显示通知,请执行以下操作。
// Check if the notification is from SDK and provide UNNotificationPresentationOptions or nil by invoking the below method.
public func notificationOptionsForBeaconstacNotification(_ notification: UNNotification) -> UNNotificationPresentationOptions?
// EXAMPLE:
func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
var notificationPresentationOptions: UNNotificationPresentationOptions
if let notificationOption = try! beaconstac.sharedInstance().notificationOptionsForBeaconstacNotification(notification) {
notificationPresentationOptions = notificationOption
} else {
// My Presenation options...
}
completionHandler(notificationPresentationOptions)
}
// Check if SDK can handle the notification by invoking the below method.
public func showCardViewerForLocalNotification(_ notification: UNNotification) -> Bool
// EXAMPLE:
func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
let notification = response.notification
if beaconstac.showCardViewerForLocalNotification(notification) {
// We will handle the notification...
} else {
// Handle it...
}
completionHandler()
}
// Check if the notification is from SDK and provide UNNotificationPresentationOptions or nil by invoking the below method.
- (UNNotificationPresentationOptions)notificationOptionsForBeaconstacNotification:(UNNotification *)notification;
// EXAMPLE:
- (void)userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler {
UNNotificationPresentationOptions notificationPresentationOptions;
NSError *error;
Beaconstac *i = [Beaconstac sharedInstanceAndReturnError:&error];
int option = [i notificationOptionsForBeaconstacNotification:notification];
if (option != 0) {
notificationPresentationOptions = (UNNotificationPresentationOptions)option;
} else {
// My Presenation options...
}
completionHandler(notificationPresentationOptions);
}
// Check if SDK can handle the notification by invoking the below method.
- (BOOL)showCardViewerForLocalNotification:(UNNotification * _Nonnull)notification;
// EXAMPLE:
- (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void (^)(void))completionHandler {
UNNotification *notification = response.notification;
if ([i showCardViewerForLocalNotification:notification]) {
// We will handle the notification...
} else {
// Handle it...
}
completionHandler();
}
- 您需要添加关于应用程序用户的
filters
,如果营销人员提供了filters。为此
// Provide the filters to the SDK as Key-Value pairs using dictionary. Note keys are case insensitive.
func addFilters(_ filters: Dictionary<String, Any>)
// Provide the filters to the SDK as Key-Value pairs using dictionary. Note keys are case insensitive.
- (void)addFilters:(NSDictionary<NSString *, id> * _Nonnull)filters;
注意:如果规则包含filters且应用程序没有提供,该规则将视为过滤器验证失败,我们不会触发该规则。
- SDK收集有关如何收集与
iBeacon
相关的信息并将其与应用程序用户(MVisitor)关联的analytics
。如果您了解有关您的应用程序用户的信息,请创建一个MVisitor对象并将其提供给我们。
// If you know the your app visitor, create a Visitor object and call this on the Beaconstac instance.
func setVisitor(_ visitor: MVisitor)
// If you know the your app visitor, create a Visitor object and call this on the Beaconstac instance.
- (void)setVisitor:(MVisitor * _Nonnull)visitor;