iOS

Getting Started

You should’ve received the following account details from us:

  • A base URL for your account, example: http://example.sensorberg.io
  • A client ID, required by the SDK in order to talk to the back-end
  • A user-name and password for your account
  • A download link for the iOS SDK
  • A private CocoaPods podspec URL for the iOS SDK
  • A private Carthage JSON URL for the iOS SDK

Integrating with Xcode

We support the following methods to integrate our SDK into your project:

  • Manual Xcode integration
  • Xcode integration using CocoaPods
  • Xcode integration using Carthage

Which one you choose, is up to you. If you are a beginner, CocoaPods integration is probably the easiest and fastest to get started.

You can use only one of the integration methods. They are not compatible with each other. If you want to switch from one integration method to another, please make sure to undo the previous integration steps first.

Manual Xcode Integration

  1. Download & unzip the SDK package where you’ll find the following contents:

    BlueIDSDKiOS.framework
    BlueIDSDKiOS.framework.dSYM
    LICENSE
    README
    SmartSpacesKit.framework
    SmartSpacesKit.framework.dSYM
    
  2. Open your project in Xcode, select your app target, got to the General tab and drag the frameworks SmartSpacesKit.framework & BlueIDSDKiOS.framework into the Embedded Binaries section.

  3. Go to the Build Phases tab and add a new Run Script Phase, name it “Strip Frameworks” (or something to your liking). Make sure it is below the Embed Frameworks phase. Paste the following line into the script text view:

    bash "$BUILT_PRODUCTS_DIR/$FRAMEWORKS_FOLDER_PATH/SmartSpacesKit.framework/StripFrameworks"
    
  4. Add the debug symbols SmartSpacesKit.framework.dSYM & BlueIDSDKiOS.framework.dSYM to your Xcode project, make sure to not add them to any targets. This step is optional but highly recommended.

  5. Make sure your app builds and runs in the iOS sumulator and on a device with no errors.

Xcode Integration Using CocoaPods

We support CocoaPods via private podspec URLs, which you should have received together with your account details from us. Use those to specify a specific version of the SDK to be used by your app. Your Podfile should look something like this:

use_frameworks!

target :YourApp do
  # ...
  pod 'SmartSpacesKit', podspec: 'https://sdk.sensorberg.com/smart-spaces/ios/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/cocoapods/SmartSpacesKit-iOS-0.2.0.podspec'
  # ...
end

Xcode Integration Using Carthage

We also support Carthage via a private URL, which you should have received together with your account details from us. Add that URL together with the desired version to your Cartfile. It should look something like this:

binary "https://sdk.sensorberg.com/smart-spaces/ios/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/carthage/SmartSpacesKit.json" ~> 0.2

You’ll have to add the SmartSpacesKit.framework and the BlueIDSDKiOS.framework to your target as a Carthage dependency, your Carthage build phase should look something like this:

Configuring Capabilities

The SmartSpacesKit requires Bluetooth support, which we’ll have to enable for your app as follows:

  1. Open your project in Xcode, select your app target and go to the Capabilities tab. Enable Background Modes and make sure Uses Bluetooth LE accessories as well as Acts as a Bluetooth LE accessory is checked.

  2. Add usage description for Bluetooth in your app’s Info.plist file (see Apple’s documentation for NSBluetoothPeripheralUsageDescription for more info)

  3. Make sure your app builds and runs in the iOS sumulator and on a device with no errors.

Configuring the SDK

Now we’ll have to configure the SDK by setting the following keys in your app’s Info.plist:

  • SmartSpacesClientID, type String, value: <YOUR_CLIENT_ID>
  • kSWPlatformBaseURL, type String, value: <YOUR_BASE_URL>

As mentioned in the beginning, you should’ve received your base URL and client ID together with your account details from us.

Again, make sure your app builds and runs in the iOS sumulator and on a device with no errors before proceeding to the next step.

Getting Locks to Unlock

We are now ready to write some code. Our SDK is written in Objective-C and supports Swift as well.

In order to be able to discover and unlock locks, you’ll have to:

  1. Import the SmartSpacesKit
  2. Login via the SWUserSessionManager
  3. Register user’s iOS device by synchronizing SWUserDeviceManager (needs to be done only once)
  4. Register a delegate for the shared SWSmartLockManager
  5. Begin discovery of locks by synchronizing the shared SWSmartLockManager
  6. Get notified about discovered SWLocks via the SWSmartLockManagerDelegate protocol
  7. Open an SWLock using the open() method of the shared SWSmartLockManager

Here is a minimal Swift example:

import UIKit
import SmartSpacesKit

@UIApplicationMain
class AppDelegate: UIResponder {
    var window: UIWindow?
    var locksOpened = false
}

extension AppDelegate: UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
        // TODO: insert your username password below:
        SWSmartLockManager.shared().delegate = self
        SWUserSessionManager.shared().login(
            withUsername: "<YOUR_USERNAME_HERE>",
            password: "<YOUR_PASSWORD_HERE>",
            additionalData: nil
        ) { userData, error in
            if let error = error { print("โค๏ธ [ERROR] Failed to log-in: \(error)"); return }
            print("๐Ÿ’š [DEBUG] Logged in, user data: \(userData.debugDescription)")

            SWUserDeviceManager.shared().synchronize { (success, error) in
                if let error = error { print("โค๏ธ [ERROR] Failed to synchronize user device manager: \(error)"); return }
                print("๐Ÿ’š [DEBUG] Synchronized user device, success: \(success)")

                SWSmartLockManager.shared().synchronize { error in
                    if let error = error { print("โค๏ธ [ERROR] Failed synchronizing smart lock manager: \(error)"); return }
                    print("๐Ÿ’š [DEBUG] Synchronizing smart lock manager finished")
                }
            }
        }

        return true
    }
}

extension AppDelegate: SWSmartLockManagerDelegate {
    func manager(_ manager: SWSmartLockManager, didDiscover locks: [SWLock]?) {
        guard let locks = locks else { print("๐Ÿงก [WARNING] Locks are nil, aborting."); return }
        guard !locksOpened else { return }

        for lock in locks {
            print("๐Ÿ’š [DEBUG] Discovered lock: '\(lock.name ?? "unknown")', actions: \(lock.actions ?? [])")
            manager.open(lock)
        }

        locksOpened = true
    }

    func manager(_ manager: SWSmartLockManager, didOpen lock: SWLock, error: Error?) {
        print("๐Ÿ’š [DEBUG] Did open lock: \(lock), error: \(String(describing: error))")
    }
}

Make sure to replace <YOUR_USERNAME_HERE> and <YOUR_PASSWORD_HERE> with your own credentials. Build & run the app on an iOS device, you should see your locks printed to the console and unlocked once. ๐ŸŽ‰

Conclusion

Your app is now properly configured with the SmartSpacesKit. You should now be able to build your UI on top of it, enabling your users to interact with various smart space devices. Happy coding!

Troubleshooting

We’ll add common issues to this section later on. If you have any trouble setting up the SDK in your app, please get in touch. We are always happy to help. โค๏ธ