escaKit 2.0.0

escaKit 2.0.0

×

测试已测试✗
语言语言 SwiftSwift
许可证 MIT
发布最后一个版本2016年5月
SPM支持 SPM✗

由Tanner Nelson 维护。

escaKit 2.0.0

escaKit

esca Beacons

用法

要运行示例项目，请克隆仓库，然后首先从 Example 目录运行 pod install。

安装

escaKit 通过 CocoaPods 提供。要安装它，只需将以下行添加到您的 Podfile 中：

pod "escaKit"

用法

开始使用 escaKit 很简单。

import escaKit

权限

如果您的应用程序尚未请求位置服务，您必须在此操作之前这样做才能使 escaKit 在真实世界中工作。escaKit 提供了一个帮助函数来请求位置服务。

escaKit.requestLocation(.Always) //or .WhenInUse

请确保在 Info.plist 中包含适当的用途描述。

NSLocationWhenInUseUsageDescription
NSLocationAlwaysUsageDescription

如果您希望当应用处于后台时从 escaKit 发送通知，您需要请求通知。

escaKit.requestNotificationsForApplication(UIApplication.sharedApplication())

启动

请求适当的权限后，您可以启动 escaKit。

escaKit.start(delegate: self, appKey: "escakit-demo-key")

从 esca Dashboard 获取 appKey，它应该看起来像这样：`asTyjGFHcDmgr23ICZuKGS4wTKDwnmIHx0B3RFga`。

创建体验

当您在 escaKit 中创建一个体验时，它将自动显示在 esca Dashboard 上。从那里，您可以分配要发送给应用程序的内容。

要创建一个体验，创建一个 escaKit.Experience 的新子类。在您的体验中，添加 escaKit.Payload 的子类，并在体验中创建属性以持有这些有效负载。

您可以在一个体验中拥有任意数量的有效负载，并且可以拥有具有相同有效负载类型的多个属性。

import Foundation
import escaKit

class InStoreExperience: escaKit.Experience {
    var currentSale = PromotionPayload()

    class PromotionPayload: escaKit.Payload {
        var imageUrl: String = ""
        var about: String = ""
        var name: String = ""
    }
}

重要：您必须确保任何有效负载属性（如 currentSale）分配了所需的类型的空有效负载。

注册体验

创建完您的体验后，您需要通知 escaKit。在 escaKit.start(...) 调用之后任何地方，您都可以注册您的体验。

escaKit.registerExperience(InStoreExperience)

这将上传体验结构和有效载荷到esca Dashboard。下次您登录时，您将能够开始将内容分配到体验。

发现代理

escaKit的代理，通常是ViewController或您的AppDelegate，需要符合escaKit.DiscoveryDelegate

protocol escaKit.DiscoveryDelegate {
    func escaKitDidDiscoverExperience(experience: Experience)
    func escaKitDidDiscoverObject(object: Object)
}

使用Experience回调，在您的应用程序进入iBeacon区域或其他上下文时显示相关体验。

func escaKitDidDiscoverExperience(experience: Experience) {
    if let experience = experience as? InStoreExperience {
        print("Loading In Store Experience with Sale: \(experience.currentSale.name)")
        self.modalWindow.experience = experience
        self.modelWindow.open(animated: true)
    }
}

您可以使用Object回调开始跟踪哪个对象在范围内，并设置对象的代理。

func escaKitDidDiscoverObject(object: Object) {
    print("\(object) discovered")

    object.delegate = self
    self.objects.append(object)
}

对象

在特定时间，每个iBeacon都有一个对象与之关联。对象具有标识符和距离等信息。

标识符

标识符是一个32位整数，它将与写入iBeacon箱子的相同数字相同。

距离

距离是一个浮点数，随着iBeacon接近扫描设备，它将接近0。您可以使用这个数字来找出哪个对象最近，或者为对象触发某些操作设置边界。

代理

当对象发生某些事件时，如更新距离或消失，将调用代理。请参阅ObjectDelegate协议。

对象代理

escaKit.ObjectDelegate

protocol escaKit.ObjectDelegate {
    func escaKitObjectDidDisappear(object: Object)
    func escaKitObjectDidChange(object: Object)
}

消失

当扫描设备不再看到对象时将调用此操作。如果与该对象关联的iBeacon超出了范围，就会发生这种情况。您可以使用这个回调作为从您要跟踪的对象数组中删除对象的机会。

func escaKitObjectDidDisappear(object: Object) {
    print("\(object) did disappear")

    self.objects = self.objects.filter { currentObject in
        currentObject != object
    }
}

更改

当对象的属性发生变化时（如distance），将调用此操作。您可以使用此回调更改对象项目的列表顺序，或者检查是否达到了距离阈值。

func escaKitObjectDidChange(object: Object) {
    print("\(object) changed.")

    if object.distance < 100.0 {
        print("\(object) is close.")
    }

    //sort the objects by closest at
    //the beginning of the list
    let objectsByDistance = self.objects.sort { object1, object2 in
        //put 0s at the end of the list
        if object1.distance == 0 {
            return false
        }
        if object2.distance == 0 {
            return true
        }

        return object1.distance < object2.distance
    }

    if let closestObject = objectsByDistance.first {
        print("\(object) is closest.")
    }
}

模拟

如果您没有用于测试的esca iBeacon，您可以模拟对象以测试您的代码。

escaKit.simulateObject(after: 2, lastingFor: 10, withId: 10130482)
escaKit.simulateObject(after: 2, lastingFor: 10) //defaults to id 10000000

辅助函数

escaKit包括一些辅助函数，例如用于发送通知的这个函数

escaKit.sendNotificationForApplication(UIApplication.sharedApplication(), title: "Test Alert", message: test, sound: true)

后台

iOS限制后台可跟踪的最大iBeacon数量为20。因此，您必须明确告诉escaKit在后台时您想发现哪些beacon标识符。

escaKit.enableBackgroundDiscoveryForObject(identifier: 10130482)

当对象在后台被看到时，将像往常一样调用DiscoveryDelegate。与sendNotification辅助函数结合使用，当应用程序未打开时，在用户靠近iBeacon时提醒用户。

注意：您还必须请求.Always位置使用，以在后台检测iBeacon。

平滑处理

escaKit 内置了平滑算法，用于防止因蓝牙干扰导致的不一致性引起的 distance 测量值的波动。尽管这种平滑可以提高测量精度，但它会降低您的应用对附近信标位置变化的响应速度。

默认的平滑值为 20。要阻止平滑，请使用 1。

//faster, but more erratic beacon distances
escaKit.Beacon.smoothing = 10

调试

通过启用日志记录，可以访问 escaKit 的有用信息。

escaKit.logging = true

停止

要停止 escaKit 扫描信标，请随时调用 escaKit.stop()。

作者

Tanner Nelson, [email protected]

许可证

escaKit 在 MIT 许可证下提供。有关更多信息，请参阅 LICENSE 文件。