BKClient

open class BKClient: NSObject, BKDeviceDiscoveryServiceDelegate, BKBackendResolverDelegate

Main Controller class for discovering BLE modules and resolving blukii concerned data from the blukii Info Manager.

BlukiiClient is a single point of contact for all data retieving actions as follows: - Discovering BLE modules, extracting BLE data and resolving data from blukii Info Manager (https://manager.blukiiinfo.com) - Resolving data for a single blukii module or tag from blukii Info Manager - Resolving news from blukii Info Manager

A. Discover BLE modules, extract their BLE data and resolve their data from blukii Info Manager

Use this feature to discover BLE modules in your environment and optionally retrieve corresponding data from blukii Info Manager.

To do this you have to do the following steps:

1. Initialize and start discovery

Call initDiscovery() and implement the BKClientDiscoveryDelegate delegates. After initialization is ready (delegate onDiscoveryInitialized()) you can start the discovery.

var mBlukiiClient: BKClient!

override func viewDidLoad() {
    ...
    mBlukiiClient = BKClient()
    mBlukiiClient.discoveryDelegate = self
    mBlukiiClient.initDiscovery()
    ...
}

func onInitialized() {
    if mBlukiiClient.startDiscovery() {
        // Discovery successfully started
    }
}

func onDiscoveryResult(discoveryResultList: [BlukiiInfo.BKOutputElement]) { }
func onDiscoveryError(errorCode: BlukiiInfo.BKClient.ErrorCode) { }
func onDiscoveryInfo(infoCode: BlukiiInfo.BKClient.InfoCode) { }

2. Configure discovery settings

Use the BKDiscoverySettings object for configuring discovery. Get BKClient.discoverySettings to retrieve the settings property set.

func onInitialized() {
      // Discovery successfully initialized

      let discoverySettings: BKDiscoverySettings = mBlukiiClient.discoverySettings
      discoverySettings.setRssiThreshold(-100)
      discoverySettings.scanDuration = 10000
      ...

      if mBlukiiClient.startDiscovery() {
          // Discovery successfully started
      }
 }

When BLE scanner is started the BLE discovery is acting according to the BKDiscoverySettings:

  • The scanner is searching for BLE modules inside the defined rssi range (BKDiscoverySettings.getRssiThreshold()).
  • After one scan duration (BKDiscoverySettings.scanDuration) the results are called back to (BKClientDiscoveryDelegate.onDiscoveryResult(_: ))
  • This is repeated until BLE Scanning is stopped by BKClient.stopDiscovery() or the app did enter the background.
  • if the scanner is paused according to the BKDiscoverySettings the info BKClient.InfoCode.INFO_DISCOVERY_PAUSED is called.
  • For background scanning it is necessary to be in the iBeacon Region 123456789AB-CDEF-01234-00000000002 or 123456789AB-CDEF-01234-00000000003. In background it is possible to scan for iBeacon, EddystoneBeacon and InfoBeacon.

3. Configure resolver settings

Use the BKResolveSettingsobject for configuring the resolving of the blukii Info Manager data.

Call BKClient.resolveSettingsto retrieve the settings property set.

Note: BKResolveSettings.resolveEnabled has to be set true to enable the resolver!

func onInitialized() {
      // Discovery successfully initialized

      let discoverySettings: BKDiscoverySettings = mBlukiiClient.discoverySettings
      discoverySettings.setRssiThreshold(-100)
      discoverySettings.scanDuration = 10000
      ...

      // change resolver settings
      let resolveSettings: BKResolveSettings = mBlukiiClient.resolveSettings
      resolveSettings.resolveEnabled = true
      resolveSettings.setLanguagePriority([BKResolveSettings.OutputLanguage.English, BKResolveSettings.OutputLanguage.German])
      ...

      if mBlukiiClient.startDiscovery() {
          // Discovery successfully started
      }
 }

4. Retrieve results

The callback BKClientDiscoveryDelegate.onDiscoveryResult(discoveryResultList: [BKOutputElement]) will be called after finishing every discovery phase. It retrieves the discovered list of BKOutputElements.

Note: If no BLE modules have been found discoveryResultList is empty (not nil).

func onDiscoveryResult(discoveryResultList: [BKOutputElement]) {
  // Discovery phase has finished: list of OutputElements are retrieved

  for outputElement in discoveryResultList {
     let id = outputElement.id
     let rssi = outputElement.discoveryData?.rssi
     ...
  }
}

5. Retrieve errors and infos

The callbacks BKClientDiscoveryDelegate.onDiscoveryError(BKClient.ErrorCode) and BKClientDiscoveryDelegate.onDiscoveryInfo(BKClient.InfoCode) will be called if there is important information about the discover process.

func onDiscoveryError(errorCode: BKClient.ErrorCode) {
    // An error has been sent from discover
}

func onDiscoveryInfo(infoCode: BKClient.InfoCode) {
    // An info has been sent from discovery
}

B. Resolve data for a single blukii module or tag from blukii Info Manager

Retrieve data for a module or tag from blukii Info Manager by calling resolveInputElement(InputElement)

You have to prepare an BKInputElement that stands for a blukii number, NFC tag or scan result. Please see BKInputElement for more Information.

If the resolving proccess is successfull the delegate BKClientResolveDelegate.onResolveInputElementResult(outputElement: BKOutputElement) is called. Otherwise the delegate BKClientResolveDelegate.onResolveInputElementError(inputElement: BKInputElement, errorCode: BKClient.ErrorCode) lets you know the error of the resolving proccess.

mBlukiiClient.resolveDelegate = self

func resolveSingleElement() {
    // call resolver
    let inputElement = BKInputElement(tagID: "", inputType: BKInputSourceType.NFC)
    mBlukiiClient.resolveInputElement(inputElement)
}

func onResolveInputElementResult(outputElement: BKOutputElement) {
    let id = outputElement.id
    let url = outputElement.resolveData?.url
}

func onResolveInputElementError(inputElement: BKInputElement, errorCode: BKClient.ErrorCode) {
    // An error has been sent from resolver
}

C. Resolving news from blukii Info Manager

Retrieve a translated news text from the blukii Info Manager.

If the resolving process is successfull the delegate BKClientNewsDelegate.onNewsResult(news: String) is called. Otherwise the delegate BKClientNewsDelegate.onNewsError(errorCode: BKClient.ErrorCode) lets you know the error of the resolving process.

mBlukiiClient.newsDelegate = self

func resolveNews() {
    mBlukiiClient.resolveServerNews("en-gb")
}

func onNewsResult(news: String) {
    // news retrieved
}

func onNewsError(errorCode: BlukiiInfo.BKClient.ErrorCode) {
    // An error has been sent from resolver
}
  • Error codes for discovery and resolver

    See more

    Declaration

    Swift

    public enum ErrorCode
  • Info codes for discovery

    See more

    Declaration

    Swift

    public enum InfoCode
  • The Helper Object to validate application and mobile device features.

    Declaration

    Swift

    fileprivate(set) open var featureValidator: BKFeatureValidator!
  • Constructor for initiating a blukii client.

    Declaration

    Swift

    public override init()
  • Gets the state if BLE scanner is actuallly running.

    Declaration

    Swift

    open func isDiscovering() -> Bool

    Return Value

    true, if BLE scanner is scanning

  • Initializes the discovery service.

    If successful, the delegate BKClientDiscoveryDelegate.onDiscoveryInitialized() is called. Otherwise the delegate `BKClientDiscoveryDelegate.onDiscoveryError(errorCode: BKClient.ErrorCode) is called with an error.

    Note: By calling this function the service instance BKDeviceDiscoveryService is started and binded by the BKClient object. This is required before calling startDiscovery() and stopDiscovery() for starting and stopping the discovery for BLE modules. Without startDiscovery()BKDeviceDiscoveryService is not do any action and therefore not using the battery.

    Note: Use this function only, if the view is loaded. For Example viewDidAppear.

    Declaration

    Swift

    open func initDiscovery()
  • Gets the state if the discovery service is initialized.

    Declaration

    Swift

    open func isDiscoveryInitialized() -> Bool

    Return Value

    true, if discovery service is initialized

  • Starts the BLE scanner.

    It only can be started if the discovery service has been initialized befor by calling initDiscovery()!

    Background mode: If the app change to the background, the scan will not stop. Conditions:

    • capabilities -> Background Modes -> Location Update -> enable
    • capabilities -> Background Modes -> Use Bluetooth LE accessoires -> enable
    • info.plist: Enter a value for NSLocationAlwaysUsageDescription
    • BKDiscoverySettings.scanInBackground -> true

    Note: Only when the BLE scanner is started successfully the BKClientDiscoveryDelegate delegates are called if there is any discovery result, error or info.

    You can stop scanning by calling stopDiscovery()

    Declaration

    Swift

    open func startDiscovery() -> Bool

    Return Value

    true, if start is successful.

  • Stops the BLE scanner.

    You can start scanning by calling startDiscovery()

    Declaration

    Swift

    open func stopDiscovery() -> Bool

    Return Value

    true, if stop is successful.

  • Starts the resolver to retrieve blukii Info Manager data of one single element.

    Results will be asynchronously returned with the callbacks of the BKClientResolveDelegate delegate.

    Note: BKResolveSettings.getLanguagePriority() is the only property that takes affect for resolving single elements. All other BKResolveSettings properties are affecting the discovery process only!

    Declaration

    Swift

    open func resolveInputElement(_ input: BKInputElement)

    Parameters

    input

    BKInputElement Data with specified format. therefore see BKInputElement

  • Starts the resolver to retrieve a translated blukii Info Manager news text.

    Results will be asynchronously returned by the delegates of the BKClientNewsDelegate

    Declaration

    Swift

    open func resolveServerNews(_ languageId: String)

    Parameters

    languageId

    language code for the translation, supported languages: BKResolveSettings.OutputLanguage