1 Introduction

Jabra iOS SDK V2 is a framework, which provides interfaces to the following functionalities in Jabra devices:

  • Device settings: To view and change settings
  • Device info: To get serial number, firmware version, battery status and name
  • Factory reset: To set all settings to default values

1.1 Abbreviations and acronyms

Acronym Description
API Application Programming Interface
SDK Software Development Kit
IDE Integrated Development Environment
HTTP Hypertext Transfer Protocol
JSON JavaScript Object Notation

1.2 SDK installation

SDK iOS release package consists of the following directories and files: * demo - source code for demo application * doc - installation guide and release notes * framework - iOS framework project * readme text file

The directories contain the following assets:

Assets Description
readme.txt Information for getting started
Jabra SDK V2 User Guide for iOS.pdf API documentation for iOS and user guide
ReleaseNotes.txt Release information
framework Jabra iOS SDK framework project
demo Demo application source code (iOS Project)

1.2.1 Supported Jabra devices

This SDK supports MFI certified Jabra devices. The following devices are supported in the current release:

  • Jabra Elite Sport, Jabra Sport Pulse, Jabra Sport Coach
  • Jabra Eclipse, Jabra Motion, Jabra Stealth, Jabra Steel, Jabra Supreme

1.2.2 Supported iPhones and iOS version

  • iPhone 5s and later
  • iOS 9 and later

1.3 Developing an application using the SDK System prerequisites

The prerequisites for the SDK are:

  • Xcode 8.3.2 and later

1.3.2 Framework symbols

1.3.2.1 Protocols

  • JabraDevice
  • JabraSetting

1.3.2.2 Delegates

Delegate Delegate Methods Description
JabraDeviceDelegate func deviceDidConnect(device: JabraDevice) Sent when a device has been connected.
- Parameter device: JabraDevice of the connected device
func deviceDidDisconnect(ID: UInt16) Sent when a device has been disconnected.
- Parameter ID: ID of the disconnected device

1.3.2.3 Classes

  • BatteryStatus
  • DependentSetting
  • SettingValues
  • Validations

1.3.2.4 Enums

  • ButtonID
  • DeviceStatus
  • ErrorStatus
  • ControlType
  • DataType

1.3.2.5 Structures

  • InitializationKey

1.3.2.6 Functions

Function Description
func Initialize(withParams params: [String : Any]) Sets the delegate for receiving device events - Parameter: Dictionary of AppIDKey, Delegate etc.
func lock() -> Bool Locks device. A lock must have been obtained prior to calling any of the Set or Get methods (getSettings, setSettings). - Returns: Unlocks device. Only the client owning the lock can unlock a device. ** See also: ** IsLocked
func unLock() -> Bool Unlocks device. Only the client owning the lock can unlock a device. - Returns: true if lock was released, otherwise false
func getSettings() -> [Setting] Gets the settings for the device - Returns: list of settings
func setSettings(settingList: [Setting]) -> DeviceStatus Sets the settings for the device - Parameter settingList: list of settings - Returns: DeviceStatus
func reconnectDevices() Reconnects the device when the app comes from the background
func doFactoryReset() -> DeviceStatus Performs the factory reset on the device - Returns: refers to the DeviceStatus enum values
func unInitialize() -> Bool Should be called to do clean up - Returns: true if successful else false

1.3.2.7 Variables

Class/Protocol Variable Name Description
JabraDeviceDelegate sdkVersion Gets the SDK version
JabraDevice deviceID Gets Device ID
variantType Gets Variant Type
electronicSerialNumber Gets Electronic Serial Number
productID Gets USB product ID
name Gets device name
isLocked Indicates whether device is currently locked
isSecondaryPaired Indicates whether device is paired via secondary device such as USB adapter
firmwareVersion Gets firmware version
serialNumber Gets serial number
isBatteryStatusSupported Indicates whether the device can report battery status
isFactoryResetSupported Checks whether factory reset is supported
batteryStatus Gets current battery status
imagePath Device image path
thumbnailImagePath Device Image ThumbnailPath
errorStatus Returns Error Status for all device related errors

1.3.3 Steps to initialize the library

The following steps are mandatory for initializing the SDK:

  • Valid App ID/Client ID must be set in SDK using Initialize API with InitializationKey.AppID. If app ID is not set, SDK initialization will fail. Kindly note, App ID/Client ID must be obtained by application developers by registering with the Jabra portal - https://developer.jabra.com/
  • With Initialize API, users can also register for JabraDeviceDelegate.
  • App should register for the following protocols in the info.plist file to get the information for connected Jabra devices.

Figure 1: Jabra protocols

Figure 1: Jabra protocols

Important: As callbacks are executed in SDK context, the application must perform only small/lightweight activity.

1.3.4 Bitcode support

The SDK framework is bitcode enabled. So developers can build bitcode enabled apps.

1.3.5 Simulator support

This version of SDK does not support simulator

1.3.6 Points to remember

  • As multiple applications can simultaneously access the same device, the device must be locked by the application before performing operations such as view settings, apply settings. Setting operations cannot be performed unless the device is locked. The application must unlock the device after usage.
  • Network needs to be available for device detection, there is no offline support. If user connects a device to iPhone when network is not available, SDK will not be able to validate and get settings for the device. If network becomes available when a device is already connected then user has to disconnect and connect back the device to iPhone.
  • Dependent settings are settings that are dependent on other settings. For example, based on the value of one setting, other setting(s) may be enabled or disabled.
    • The application needs to handle dependency settings, based on the flag isDepedentSettingSupported, in the exposed Setting protocol.
    • settingValues in each setting (mainly for drop down control settings) will contain a list of possible values. In addition, dependencySettingList inside settingValues will also have details of dependent settings.
    • And for each value in the dependencySettingList,
      • dependentCount will have the information for how many settings are dependent on this value. It will be zero if no settings are dependent.
      • IfdependentCountisnotzero,thenDependentSettingwillhavethedetailsof the settings that are dependent.
      • DependentSetting will have the setting GUID and a flag to say whether to enable or disable.
      • For some settings that are disabled because of dependency, the value needs to be changed to the default value. dependentSettingDefaultValue in Setting structure will have the default value.

1.4 Demo application

1.4.1 Setup

Source code of the demo app is packed along with this SDK. The demo application is an iOS Swift application which runs on Xcode 8.3.2 using JabraSDK 1.0.11.4.

Obtain App ID/Client ID from https://developer.jabra.com/ and replace token in AccessToken.plist file of the demo app to run.

(This feature is under development, hence user can use a dummy token string e.g. jabra)

1.4.2 Screenshots

Figure 2(a): Device selection view

Figure 2(a): Device selection view

Figure 2(b): Device information view

Figure 2(b): Device information view

Figure 2\(c): Device settings view

Figure 2(c): Device settings view

1.5 Development setup

  1. Open an iOS project on Xcode 8.3.2.
  2. Drag and drop LibJabraSwiftBindings.xcodeproj to your application.

Figure 3(a): Adding the JabraSDK.framework

Figure 3(a): Adding the JabraSDK.framework

  1. Select LibJabraSwiftBindings and build. (Product->Build For->Running)

Figure 3(b): Adding the JabraSDK.framework

Figure 3(b): Adding the JabraSDK.framework

  1. Add the JabraSDK.framwork to Targets-> Embedded Binaries.

Figure 3(c): Adding the JabraSDK.framework

Figure 3(c): Adding the JabraSDK.framework

  1. Goto to your application Build Settings, under framework search path add JabraSDK.framework path (JabraSDK.framework is located at framework_project_location/build/Release-iphoneos)

Figure 3(d): Adding the JabraSDK.framework

Figure 3(d): Adding the JabraSDK.framework

1.6 Sequence diagrams

This section contains sequence diagrams for the most common use cases. Using the same patterns as the one described here enables more advanced use cases.

1.6.1 Get device setting

The following diagram illustrates how to get settings from the device using this library.

Figure 4: Get device settings

Figure 4: Get device settings

1.6.2 Set device settings

The following diagram illustrates how to set settings from the application to the device, using this library.

Figure 5: Set device settings

Figure 5: Set device settings

2 Third party license notice

2.1 License notice for libjsoncpp

Copyright (c) 2007-2010 Baptiste Lepilleur Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Updated license information can be found here.

2.2 License notice for pugixml

This library is distributed under the MIT License: Copyright (c) 2006-2015 Arseny Kapoulkine Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Updated license information can be found here.

2.3 License notice for libcurl

The MIT License (MIT)

Copyright (c) 2015 Andreas Rumpf

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Updated license information can be found here.