KontaktSDK 3.0.26

KontaktSDK 3.0.26

测试测试
语言语言 Obj-CObjective C
许可证 自定义
发布上次发布2022年11月

Marek SerafinLukasz HlebowiczJacek Kurbiel 维护。



KontaktSDK 3.0.26

  • 作者
  • Kontakt.io

iOS/tvOS/macOS SDK 快速入门

管理应用

要配置 Kontakt.io 设备,请使用我们新的 iOS 管理应用

screen

示例代码

您可以在 示例文件夹 中找到我们的演示和示例代码。

概览

本文档向您展示了快速开始在位置感知应用中使用 Kontakt.io SDK 的方法。您将找到核心功能和最佳实践的代码示例,我们建议开发人员遵循。

您可以在 Appledocs 中找到更多详细信息。

安装 iOS/tvOS/macOS SDK

要使用 Kontakt.io SDK 在项目中,最低部署目标必须是 iOS 8.0 或 macOS 10.9 或 tvOS 9.0。

CocoaPods

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

Carthage 是一个分发的依赖管理器,它构建您的依赖关系并提供二进制框架。

您可以使用以下命令使用 Homebrew 安装 Carthage

$ brew update
$ brew install carthage
  1. 要使用 Carthage 将 Kontakt.io SDK 集成到您的 Xcode 项目中,请将其在您的 Cartfile 中指定

    github "kontaktio/kontakt-ios-sdk" ~> 1.4
  2. 运行 carthage update 来构建框架。

  3. 在您应用程序的 General 设置选项卡中,在 Linked Frameworks and Libraries 部分中,将 KontaktSDK.framework 从磁盘上的 Carthage/Build/(iOS/tvOS/Mac) 文件夹中拖动。
  4. 在您的应用程序目标的 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
  • 通过运行以下命令将 Kontakt.io SDK 添加为 git 子模块
$ 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 扁错误的必要步骤。)


Swift

泛型和可空性

我们的 SDK 使用了在 Xcode 7 中添加的可空性和泛型注解,这意味着 Kontakt.io iOS SDK 非常容易与 swift 2.0 一起使用。

桥接头文件

文件 菜单创建一个新的头文件,并将其命名为您的项目名称-Bridging-Header.h

将以下导入添加到您的您的项目名称-Bridging-Header.h

    #import <KontaktSDK/KontaktSDK.h>

更多信息

为了确保您的应用正常运行,您必须在项目“Info.plist”文件中添加一个新密钥。

  1. 在项目导航器中选择您的项目。
  2. 选择项目的 Info.plist 文件
  3. 向文件添加以下密钥字符串对。
<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 设备来运行您的应用程序。

  1. 将 iOS 设备连接到您的 Mac。
  2. 在项目导航器中,从方案弹出菜单中选择您的设备。Xcode 假设您打算使用所选择的设备进行开发,并会自动为您注册。
  3. 单击“运行”按钮。

有关如何将应用程序部署到设备的详细信息,请参阅 Apple 的指南 在设备上启动应用程序

Eddystone 支持

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];
}

发现 Eddystone 设备

在这个示例中,我们将在 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

所有代理方法都可以在 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 通信

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"];

获取您的 API 密钥

使用 KTKCloudClient

初始化后;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

KTKCloudClient 的响应

所有云客户端响应都包装在 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 的自定义调用

如果您要对 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]。理解这一点很重要,尽管它们都使用蓝牙低功耗,但它们是两种不同的技术,并没有太多共同之处。