Skip to main content Link Menu Expand (external link) Document Search Copy Copied

Getting started with Amazon Sidewalk Mobile iOS SDK

Use this document to get started with Amazon Sidewalk Mobile iOS SDK. This document walks you through how to integrate Amazon Sidewalk Mobile iOS SDK into your iOS apps.

Topics

Related

Prerequisites

The Amazon Sidewalk Mobile iOS SDK has a dependency on OpenSSL. Before starting the set up flow, confirm that you have added an OpenSSL library into your app. This is also required when running the Sample App. To complete this getting started tutorial, you first need the following:

  • A deployment target iOS 12.1 or later.
  • Amazon Sidewalk MCU SDK version 1.14.
  • OpenSSL

Set up your app

The Amazon Sidewalk Mobile iOS SDK provides APIs for iOS apps. Using the SDK, you can build iOS apps that interact with the Amazon Sidewalk network. This document shows you how to set up the dependency of Amazon Sidewalk Mobile iOS SDK in your app. After you set up your app, you can write your own code with the Amazon Sidewalk Mobile iOS SDK to scan and register devices on the Amazon Sidewalk network.

Complete the following steps to set up your app.

Step 1: Integrate Login with Amazon into your app

Amazon Sidewalk devices can be attached to an Amazon account.

In order to protect user data integrity and to provide a consistent user experience, interactions with the Amazon Sidewalk network requires a user access token from Login with Amazon (LWA).

Before you begin adding Amazon Sidewalk Mobile iOS SDK to your app, follow these steps to integrate LWA into your app.

Obtain your iOS API Key

Follow the instructions here to set up a security profile and get your iOS API key. The Consent Privacy Notice URL field you set in the security profile will be shown at the bottom of the consent screen on your mobile app, with the link being “[Security Profile Name] Privacy”. The Consent Logo Image is optional. If provided, it will be shown at the top of the consent screen. You will also be able to see these in https://www.amazon.com/ap/adam?ref_=ya_d_l_iba

Integrate LWA into your app

  1. Follow the instructions here to download the LWA SDK for iOS.
  2. Follow the instructions here to set up LWA for your app. You can skip the “Create a New Project in Xcode” section if you already have a project.

Use LWA to login and logout a user

Follow the instructions here to implement user login and logout. You can skip the “Fetch User Profile Data” section.

When calling AMZNAuthorizationManager.authorize(), you need to use the sidewalk::manage_endpoint scope and make sure you are calling from the main queue.

let request: AMZNAuthorizeRequest = AMZNAuthorizeRequest()
request.scopes = [AMZNScopeFactory.scope(withName: "sidewalk::manage_endpoint")]
 
DispatchQueue.main.async {
    // This should run in the main queue.
    AMZNAuthorizationManager.shared().authorize(request) { (result, _, error) in
        if let accessToken = result?.token {
            // Authentication was successful.
        } else {
            // Handle errors.
        }
    }
}

Remember to call Sidewalk.clearAccountCache() when the user logs out. The following tutorials document will help how to integrate Amazon Sidewalk Mobile iOS SDK into your app.

Note
Amazon Sidewalk only requires a LWA user access token and does not require you to integrate your existing account system with LWA. You can skip “Integrating with Your Account System” section in the LWA documentation.

Step 2: Add OpenSSL to your app

The Amazon Sidewalk Mobile iOS SDK has a dependency on OpenSSL. You must add an OpenSSL library into your app.

Step 3: Add Amazon Sidewalk Mobile iOS SDK to your app

Add Amazon Sidewalk Mobile iOS SDK dependency

Amazon Sidewalk Mobile iOS SDK is distributed through CocoaPods or binary zip files, chose the one that better fits your needs. You can find all released versions in Release Notes.

CocoaPods
  1. If you do not have a Podfile, run the following command in the root of your project directory.
    pod init
    
  2. Add Amazon Sidewalk pod in your Podfile.
    # Add the Amazon Sidewalk pod
    pod 'SidewalkSDK', '~> [Amazon Sidewalk Mobile SDK Version]'
    
  3. Install the pods.
    pod install --repo-update
    


Download Amazon Sidewalk Mobile iOS SDK Binary

Download the latest version SidewalkMobile iOS SDK from the Release Notes and extract the files to a directory on your hard drive.

You should see a SidewalkSDK.xcframework directory in the Sidewalk_iOS/Frameworks parent directory. This contains the Amazon Sidewalk Mobile SDK library.

Next, install Amazon Sidewalk Mobile iOS SDK framework to an iOS project with the following steps.

  1. If your project doesn’t have a Frameworks folder, right-select the project name in the Navigator pane in Xcode, then select New Group.
  2. Name the new group Frameworks.

  3. Select the Frameworks folder and select File from the Main menu.

  4. Select Add Files to Project.

  5. In the dialog box, select SidewalkSDK.xcframework and select Add.

  6. Select the name of your project in the Project Navigator. The Project Editor will appear in the editor area of the Xcode workspace.

  7. Select your project name under Targets, and select Build Phases. Expand Link Binary with Libraries and select the plus sign to add a library.

  8. Select Build Settings. select All to view all settings.

  9. Under Search Paths, ensure that the SidewalkSDK.xcframework directory is in the Framework Search Paths.
  10. From the Main menu, select Product and then select Build. The build should complete successfully.

Provide a purpose string for access to Bluetooth

Amazon Sidewalk Mobile iOS SDK uses Bluetooth to interact with devices. You must provide a purpose string by setting a string value for the NSBluetoothAlwaysUsageDescription key in your apps Info.plist file. If your app has a deployment target earlier than iOS 13, you also need to add the NSBluetoothPeripheralUsageDescription key. For more information, see Requesting access to protected resources.

<key>NSBluetoothAlwaysUsageDescription</key>
<string>Your purpose string.</string>

Step 4: Write your Amazon Sidewalk project

Write your code using Amazon Sidewalk Mobile iOS SDK. In this document, we show you how to use Amazon Sidewalk Mobile iOS SDK to register a device after user login.

Implement the SidewalkAuthProviding

Implement the SidewalkAuthProviding to provide a LWA user access token to the Amazon Sidewalk Mobile iOS SDK. When calling AMZNAuthorizationManager.authorize(), make sure you are calling from the main queue.

final class MySidewalkAuthProviding: SidewalkAuthProviding {
 
    struct AuthError: Error {}
     
    func getToken(completion: @escaping (Result<String, Error>) -> Void) {
        let request: AMZNAuthorizeRequest = AMZNAuthorizeRequest()
        request.interactiveStrategy = .never
 
        DispatchQueue.main.async {
            // This should run in the main queue.
            AMZNAuthorizationManager.shared().authorize(request) { (result, _, error) in
                if let accessToken = result?.token {
                    // Success
                    completion(.success(accessToken))
                } else {
                    // Error
                    completion(.failure(error ?? AuthError()))
                }
            }
        }
    }
}

Amazon Sidewalk Mobile iOS SDK API will internally call SidewalkAuthProviding.getToken() anytime when needed.

Create a Sidewalk

Create a Sidewalk with a SidewalkAuthProviding instance.

let authProviding = MySidewalkAuthProviding()
let sidewalk = Sidewalk(authProvider: authProviding)

Note
Use the same Sidewalk instance during the lifecycle of your app. You can use dependency injection (DI) to reuse the same Sidewalk instance across your app.

Scan and get a SidewalkDevice

Call Sidewalk.scan() to scan for nearby devices. The method returns a SidewalkCancellable.

final class MyViewModel {
     
    private var devices: [SidewalkDevice] = []
    private var operation: SidewalkCancellable? = nil
     
    func scan () {
        devices = []
        operation?.cancel()
         
        operation = sidewalk.scan(onDeviceFound: didDetectDeviceDuringScan, completion: { (result) in
            DispatchQueue.main.async {
                switch result {
                case .success:
                    // Scan completed.
                case .failure(let error):
                    // Scan failed.
                }
            }
        })
    }
     
    private func didDetectDeviceDuringScan(device: SidewalkDevice) {
        DispatchQueue.main.async {
            // A `SidewalkDevice` is discovered.
            self.devices.append(device)
        }
    }
 }

Register Amazon Sidewalk Device

Call Sidewalk.registerDevice() with a Sidewalk Manufacturing Serial Number(SMSN) string to register a device to the user. Sidewalk.registerDevice() internally calls SidewalkAuthProviding.getToken() to get the user access token.

final class MyViewModel {
 
    private var operation: SidewalkCancellable? = nil
 
    func registerDevice(smsn: String) {
        operation?.cancel()
 
        operation = sidewalk.registerDevice(smsn: smsn) { result in
            DispatchQueue.main.async {
                switch result {
                case .success(let detail):
                    // Device registered!
                case .failure(let error):
                    // Error
                }
            }
        }
    }
}

Get logs from Amazon Sidewalk Mobile SDK

Define an object that implements SidewalkLogging with the log(type:, message:) function.

final class MyLogger: SidewalkLogging {

    func log(type: OSLogType, message: @autoclosure () -> String) {
        // Capture the logs from Amazon Sidewalk Mobile SDK here in message()
        os_log(type, "%@", message())
    }
}

Set Sidewalk.logger to the object that implements SidewalkLogging.

Sidewalk.logger = MyLogger()

Step 5: Build and run the app

Now you can build and run your app to login / logout a user, and scan and register devices. Before running the app, remember to turn on your phone’s Bluetooth. Do not forget to call Sidewalk.clearAccountCache() when the user logs out.


Congratulations! Now that you have the basics down, you can start your own journey or check out the sample app.

Please check the Amazon and Ring account linking limitation from here before you start registering device with Amazon Sidewalk Mobile SDK.
Make sure to inform your customer about the action required.

Run the sample app

Step 1: Download the sample app

Clone iOS sample app from GitHub https://github.com/amzn/amazon-sidewalk-ios-samples to a directory on your hard drive.

Step 2: Set up Amazon Sidewalk Mobile SDK

CocoaPods

Run the command below to install the pods for Amazon Sidewalk Mobile iOS SDK

pod install --repo-update

Local xcframework

Please refer to Install Amazon Sidewalk Mobile iOS SDK framework to an iOS project above to add your local Amazon Sidewalk Mobile SDK xcframework to your Sample App.

Step 3: Set up Login with Amazon

Follow the steps in Integrate Login with Amazon into your app to obtain your iOS API key and integrate LWA into the sample app.

Step 4: Add OpenSSL to the sample app

The Amazon Sidewalk Mobile iOS SDK has a dependency on OpenSSL. Add an OpenSSL library into the sample app.

Step 5: Run the sample app

You can now compile and run the sample app. The sample app demonstrates the following features:

  • Login and logout users with LWA SDK.
  • Scan nearby Amazon Sidewalk devices.
  • Register and unregister Amazon Sidewalk devices.
  • Establish a secure connection with a device.


Troubleshooting

Errors were encountered while preparing your device for development.

Rebooting your iPhone.

XCode shows that the device is locked when the iPhone is unlocked.

Add your computer as a trusted device. See Apple Support article for more information.

Profile has not been trusted.

Establish trust for your app developer in your iPhone under Settings → General → Device Management. See Apple Support article for more information.


Back to top

©2023 Amazon.com, Inc. or its affiliates (collectively, “Amazon”). All Rights Reserved.