测试测试 | ✗ |
语言语言 | Obj-CObjective C |
许可证 | 自定义 |
发布上次发布 | 2022年11月 |
由 Marek Serafin,Lukasz Hlebowicz,Jacek Kurbiel 维护。
要配置 Kontakt.io 设备,请使用我们新的 iOS 管理应用。
您可以在 示例文件夹 中找到我们的演示和示例代码。
本文档向您展示了快速开始在位置感知应用中使用 Kontakt.io SDK 的方法。您将找到核心功能和最佳实践的代码示例,我们建议开发人员遵循。
您可以在 Appledocs 中找到更多详细信息。
要使用 Kontakt.io SDK 在项目中,最低部署目标必须是 iOS 8.0 或 macOS 10.9 或 tvOS 9.0。
CocoaPods 是 Cocoa 项目的依赖管理器。您可以使用以下命令安装它
$ gem install cocoapods
要使用 CocoaPods 将 Kontakt.io iOS/tvOS/macOS SDK 集成到 Xcode 项目中,请将其在您的 Podfile
中指定
platform :ios, '8.0'
use_frameworks!
pod 'KontaktSDK', '~> 1.4'
然后,运行以下命令
$ pod install
Carthage 是一个分发的依赖管理器,它构建您的依赖关系并提供二进制框架。
您可以使用以下命令使用 Homebrew 安装 Carthage
$ brew update
$ brew install carthage
要使用 Carthage 将 Kontakt.io SDK 集成到您的 Xcode 项目中,请将其在您的 Cartfile
中指定
github "kontaktio/kontakt-ios-sdk" ~> 1.4
运行 carthage update
来构建框架。
General
设置选项卡中,在 Linked Frameworks and Libraries
部分中,将 KontaktSDK.framework
从磁盘上的 Carthage/Build/(iOS/tvOS/Mac)
文件夹中拖动。在您的应用程序目标的 Build Phases
设置选项卡中,单击 +
图标并选择 New Run Script Phase
。创建一个包含以下内容的 Run Script
/usr/local/bin/carthage copy-frameworks
并将您要使用的框架路径添加到 Input Files
下,例如
$(SRCROOT)/Carthage/Build/iOS/KontaktSDK.framework
或
$(SRCROOT)/Carthage/Build/tvOS/KontaktSDK.framework
或
$(SRCROOT)/Carthage/Build/Mac/KontaktSDK.framework
此脚本绕过了由通用二进制模块引起的 App Store 提交错误,确保在存档时复制必要的位码相关文件和 dSYMs。
将调试信息复制到构建产品目录后,Xcode 将能够对停止在断点处的堆栈跟踪进行符号化。这还将使您能够在调试器中单步执行第三方代码。
当您将应用程序存档以提交到 App Store 或 TestFlight 时,Xcode 还会将这些文件复制到您的应用程序 .xcarchive
包的 dSYMs 子目录中。
cd
到您的顶级项目目录,并运行以下命令 如果 您的项目尚未初始化为 git 仓库$ git init
$ git submodule add https://github.com/kontaktio/kontakt-ios-sdk.git
打开新的 kontakt-ios-sdk
文件夹,并将 KontaktSDK.framework
拖动到您应用程序 Xcode 项目的项目导航器中。
添加到目标
部分选中。接下来,在项目导航器中(蓝色项目图标)选择您的应用程序项目,导航到目标配置窗口,并在侧面的“目标”标题下选择应用程序目标。
在“内嵌二进制”部分下单击 +
按钮。
选择 KontaktSDK.framework
,然后单击 添加
按钮。
在“构建阶段”选项卡中,单击顶部的 + 按钮,并选择“新运行脚本阶段”。将以下代码输入到脚本文本字段中
bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/KontaktSDK.framework/strip-frameworks.sh"
(最后一步,来自 Realm,是绕过存档通用二进制时 iOS App Store 扁错误的必要步骤。)
我们的 SDK 使用了在 Xcode 7 中添加的可空性和泛型注解,这意味着 Kontakt.io iOS SDK 非常容易与 swift 2.0 一起使用。
从 文件 菜单创建一个新的头文件,并将其命名为您的项目名称-Bridging-Header.h。
将以下导入添加到您的您的项目名称-Bridging-Header.h中
#import <KontaktSDK/KontaktSDK.h>
为了确保您的应用正常运行,您必须在项目“Info.plist”文件中添加一个新密钥。
<key>NSLocationAlwaysUsageDescription</key>
<string>Required for ios 8 compatibilty</string>
该字符串可以为空,内容并不重要。
新的 SDK 需要指定 API 密钥。您可以在https://panel.kontakt.io注册免费账户获取它。
Objective-C
#import <KontaktSDK/KontaktSDK.h>
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// Set API Key
[Kontakt setAPIKey:@"Your API Key"];
return YES;
}
Swift
import KontaktSDK
func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
// Set API Key
Kontakt.setAPIKey("Your API Key")
return true
}
在以下示例中,我们将向您展示如何使用 Kontakt.io SDK 创建一个简单的应用程序来监控特定区域的信标。
为了简化示例,我们使用 AppDelegate.m 类。在实际应用中,您可能需要创建自己的类。
首先,我们导入 Kontakt.io SDK。
#import <KontaktSDK/KontaktSDK.h>
我们将添加 KTKBeaconManager 对象作为属性。
当设备进入或离开一个区域,或当信标距离发生变化时,KTKBeaconManager 会通知其代理。
@property KTKBeaconManager *beaconManager;
请确保 AppDelegate
实现了 KTKBeaconManagerDelegate
协议。
@interface AppDelegate () <KTKBeaconManagerDelegate>
我们将使用 application:didFinishLaunchingWithOptions:
来初始化信标管理器并开始监控区域。
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// Set API Key
[Kontakt setAPIKey:@"Your API Key"];
// Initiate Beacon Manager
self.beaconManager = [[KTKBeaconManager alloc] initWithDelegate:self];
// Request Location Authorization
[self.beaconManager requestLocationAlwaysAuthorization];
...
return YES;
}
您可以通过以下方式测试当前设备是否可以监控信标:
if ([KTKBeaconManager isMonitoringAvailable]) {
}
或者,使用以下方法检查授权状态:
if ([KTKBeaconManager locationAuthorizationStatus] == kCLAuthorizationStatusAuthorizedAlways) {
}
现在,我们将开始监控一个特定区域。
关于 KTKBeaconRegion 的更多信息,请参阅 Appledoc。
区域定义了一组应用所了解的信标,因此信标管理器只与这些信标交互。
// Kontakt.io proximity UUID
NSUUID *proximityUUID = [[NSUUID alloc] initWithUUIDString:@"f7826da6-4fa2-4e98-8024-bc5b71e0893e"];
// Create region instance
KTKBeaconRegion *region = [[KTKBeaconRegion alloc] initWithProximityUUID: proximityUUID identifier:@"identifier"];
// Start Monitoring
[self.beaconManager startMonitoringForRegion: region];
// You can also start ranging ...
[self.beaconManager startRangingBeaconsInRegion: region];
安全信标区域与标准信标区域非常相似。关于 KTKSecureBeaconRegion 的更多信息,请参阅 Appledoc。
关于安全和打乱顺序的更多信息,请参阅我们的 支持页面。
您可以在 Kontakt.io 网络面板(在安全部分)中找到您的信标的 Secure Proximity UUID。
// Your secure proximity UUID
NSUUID *secureProximityUUID = [[NSUUID alloc] initWithUUIDString:@"00000000-0000-0000-0000-00000000"];
// Create secure region instance
KTKSecureBeaconRegion *region = [[KTKSecureBeaconRegion alloc] initWithSecureProximityUUID:secureProximityUUID identifier:@"identifier_secure"];
您还可以使用非安全近程 UUID,并且它将在后台通过调用云 API 转换为安全近程。
// Kontakt.io proximity UUID
NSUUID *proximityUUID = [[NSUUID alloc] initWithUUIDString:@"f7826da6-4fa2-4e98-8024-bc5b71e0893e"];
// Create secure region instance with your non secure proximity
KTKSecureBeaconRegion *region = [[KTKSecureBeaconRegion alloc] initWithProximityUUID: proximityUUID identifier:@"identifier"];
现在,我们将添加信标管理器的代理方法,并让他们记录一些输出。所有代理方法都可以在 KTKBeaconManagerDelegate 文档中找到。
- (void)beaconManager:(KTKBeaconManager*)manager didChangeLocationAuthorizationStatus:(CLAuthorizationStatus)status;
{
// ...
}
- (void)beaconManager:(KTKBeaconManager*)manager didEnterRegion:(__kindof KTKBeaconRegion*)region
{
NSLog(@"Enter region %@", region);
}
- (void)beaconManager:(KTKBeaconManager*)manager didExitRegion:(__kindof KTKBeaconRegion*)region
{
NSLog(@"Exit region %@", region);
}
- (void)beaconManager:(KTKBeaconManager*)manager didRangeBeacons:(NSArray <CLBeacon *>*)beacons inRegion:(__kindof KTKBeaconRegion*)region
{
NSLog(@"Ranged beacons count: %lu", [beacons count]);
}
当使用 Swift 时,最终类应该如下所示
import UIKit
import KontaktSDK
@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
var window: UIWindow?
var beaconManager: KTKBeaconManager!
func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
// Set API Key
Kontakt.setAPIKey("API Key")
// Initiate Beacon Manager
beaconManager = KTKBeaconManager(delegate: self)
beaconManager.requestLocationAlwaysAuthorization()
// Region
let proximityUUID = NSUUID(UUIDString: "f7826da6-4fa2-4e98-8024-bc5b71e0893e")
let region = KTKBeaconRegion(proximityUUID: proximityUUID!, identifier: "region")
// Start Monitoring and Ranging
beaconManager.startMonitoringForRegion(region)
beaconManager.startRangingBeaconsInRegion(region)
return true
}
}
extension AppDelegate: KTKBeaconManagerDelegate {
func beaconManager(manager: KTKBeaconManager, didChangeLocationAuthorizationStatus status: CLAuthorizationStatus) {
}
func beaconManager(manager: KTKBeaconManager, didEnterRegion region: KTKBeaconRegion) {
print("Enter region \(region)")
}
func beaconManager(manager: KTKBeaconManager, didExitRegion region: KTKBeaconRegion) {
print("Exit region \(region)")
}
func beaconManager(manager: KTKBeaconManager, didRangeBeacons beacons: [CLBeacon], inRegion region: KTKBeaconRegion) {
print("Ranged beacons count: \(beacons.count)")
}
}
您无法在仿真器上运行使用 Apple Core Location 服务(包括我们的 SDK)的应用程序,因此,首先,您需要连接一个物理 iOS 设备来运行您的应用程序。
有关如何将应用程序部署到设备的详细信息,请参阅 Apple 的指南 在设备上启动应用程序。
KTKEddystoneManager 是检索 Eddystone 格式信标信息的关键技术。通过区域/过滤器来细化结果,KTKEddystoneManager
可以发现附近的 Eddystone 格式设备。
@interface ViewController () <KTKEddystoneManagerDelegate>
@property KTKEddystoneManager *eddystoneManager;
@property KTKEddystoneRegion *namespaceRegion;
@property KTKEddystoneRegion *domainRegion;
@property KTKSecureEddystoneRegion *secureNamespaceRegion;
@end
@implementation ViewController
- (void)viewDidLoad {
[super viewDidLoad];
// Eddystone Manager
self.eddystoneManager = [[KTKEddystoneManager alloc] initWithDelegate:self];
}
在这个示例中,我们将在 viewWillAppear:
方法中开始发现 Eddystone 设备,并在 viewWillDisappear:
方法中停止。
- (void)viewWillAppear:(BOOL)animated
{
[super viewWillAppear:animated];
// If should scan for all nearby Eddystones
// Passing nil will look for all regions
[self.eddystoneManager startEddystoneDiscoveryInRegion:nil];
// Scan for Eddystones with specific namespace ID
self.namespaceRegion = [[KTKEddystoneRegion alloc] initWithNamespaceID:@"namespaceID"];
[self.eddystoneManager startEddystoneDiscoveryInRegion: self.namespaceRegion];
// Scan for Eddystone with specific domain in url
self.domainRegion = [[KTKEddystoneRegion alloc] initWithURLDomain:@"github.com"];
[self.eddystoneManager startEddystoneDiscoveryInRegion: self.domainRegion];
// Scan for Secure Namespace Region
self.secureNamespaceRegion = [[KTKSecureEddystoneRegion alloc] initWithSecureNamespaceID:@"secure_namespace_id"];
[self.eddystoneManager startEddystoneDiscoveryInRegion: self.secureNamespaceRegion];
}
- (void)viewWillDisappear:(BOOL)animated
{
[super viewWillDisappear:animated];
// Stop
[self.eddystoneManager stopEddystoneDiscoveryInAllRegions];
// ... or you can just stop for one specific region by using
[self.eddystoneManager stopEddystoneDiscoveryInRegion: self.domainRegion];
}
关于安全和打乱顺序的更多信息,请参阅我们的 支持页面。
所有代理方法都可以在 KTKEddystoneManagerDelegate 文档中找到。
- (void)eddystoneManager:(KTKEddystoneManager *)manager didDiscoverEddystones:(NSSet <KTKEddystone*>*)eddystones inRegion:(__kindof KTKEddystoneRegion* _Nullable)region
{
if ([region isEqual:self.domainRegion]) {
// Eddystone discovered with URL in `github.com` domain ...
}
}
Kontakt.io Rest API 提供了一系列资源来查询/更新我们的云平台,并允许您管理您的场所和信标,并检索信标操作。
负责与 API 进行通信的类是 KTKCloudClient。
您可以通过调用 ... 来初始化它
KTKCloudClient *client = [KTKCloudClient new];
或者使用 SDK API 调用的共享实例(单例)...
KTKCloudClient *client = [KTKCloudClient sharedInstance];
如果需要特定的 NSURLSessionConfiguration
配置,您可以使用
KTKCloudClient *client = [[KTKCloudClient alloc] initWithSessionConfiguration: ...];
在使用 KTKCloudClient
的任何方法之前,必须提供 API 密钥。
[Kontakt setAPIKey:@"Your API Key"];
初始化后;KTKCloudClient
对象作为您的应用与 Kontakt.io 服务的门面。您可以使用它来获取分配给您的公司(以及更多)的操作、信标和场所。
获取设备列表就像 ...
Objective-C
[[KTKCloudClient sharedInstance] getObjects:[KTKDevice class] completion:^(KTKKontaktResponse * _Nullable response, NSError * _Nullable error) {
NSLog(@"%@". [response objects]);
}];
或者在 Swift
KTKCloudClient.sharedInstance().getObjects(KTKDevice.self) { response, error in
print(response?.objects)
}
// Get Venues
KTKCloudClient.sharedInstance().getObjects(KTKVenue.self) { response, error in
print(response?.objects)
}
要创建、更新或删除对象,您可以使用提供的其中一种方法
代表 API 中的对象的 所有类都符合协议 KTKCloudModel
。
所有云客户端响应都包装在 KTKKontaktResponse 中。KTKKontaktResponse
提供更多关于结果的信息。例如,您可以使用 nextResultsURL
属性获取下一组结果,就像这样:
// Get Device by unique ID ...
NSDictionary *parameters = @{ @"uniqueId": @"K0nT" };
[[KTKCloudClient sharedInstance] getObjects:[KTKDevice class] parameters:parameters completion:^(KTKKontaktResponse * _Nullable response, NSError * _Nullable error) {
// Check for errors etc ...
// Call next result set ..
[[KTKCloudClient sharedInstance] GET:response.nextResultsURL completion:^(KTKKontaktResponse * _Nullable response, NSError * _Nullable error) {
// ... more results ?
}];
}];
如果您要对 API 进行自定义调用,您可以使用
两种方法都接受端点名称参数和 HTTP 参数字典。
更多详细信息请参阅 Appledocs 中 KTKCloudClient 类参考。
Kontakt.io iOS SDK 包含类和方法,可以轻松连接到 Kontakt.io 设备,读取其参数,并修改其中一些参数。但是,首先您需要扫描附近的设备。
@property KTKDevicesManager *devicesManager;
...
self.devicesManager = [[KTKDevicesManager alloc] initWithDelegate: self];
// Calling `startDevicesDiscoveryWithInterval:` will report devices every `interval` value you specify.
[self.devicesManager startDevicesDiscoveryWithInterval:2.0];
// Calling `startDevicesDiscovery` will report devices in real time.
[self.devicesManager startDevicesDiscovery];
KTKDevicesManager 会将当前范围内的设备通知其代理。
所有代理方法都可以在 KTKDevicesManagerDelegate 文档中找到。
#pragma mark - KTKDevicesManagerDelegate method
- (void)devicesManager:(KTKDevicesManager*)manager didDiscoverDevices:(NSArray <KTKNearbyDevice*>* _Nullable)devices;
// Do something with devices.
}
由 KTKDevicesManager 发现的附近设备属于 KTKNearbyDevice 类。
更改 KTKNearbyDevice 配置需要 KTKDeviceConnection,并且非常简单,就像这样:
Objective-C
// Create Configuration
KTKDeviceConfiguration *configuration = [KTKDeviceConfiguration new];
configuration.name = @"Disco Beacon";
configuration.advertisingInterval = @350;
configuration.major = @123;
// Connection
KTKDeviceConnection *connection = [[KTKDeviceConnection alloc] initWithNearbyDevice: nearbyDevice];
// Write Cofiguration
[connection writeConfiguration:configuration completion:^(BOOL synchronized, KTKDeviceConfiguration * _Nullable configuration, NSError * _Nullable error) {
// Process response
}];
Swift
// Create Configuration
let configuration = KTKDeviceConfiguration()
configuration.name = "Disco Beacon"
configuration.advertisingInterval = 350
configuration.major = 123
// Connection
let deviceConnection = KTKDeviceConnection(nearbyDevice: device)
// Write Cofiguration
deviceConnection.writeConfiguration(configuration) { synchronized, configuration, error in
// Process response
}
更多代码示例和应用场景将在我们的GitHub示例项目中介绍,请参见:github。
Kontakt.io iOS SDK大量使用两个本机iOS框架:[Core Location]和[Core Bluetooth]。理解这一点很重要,尽管它们都使用蓝牙低功耗,但它们是两种不同的技术,并没有太多共同之处。