Getting Started

Prerequisites

Required Credentials and Account

Before integrating Cisco Spaces SDK into your app, ensure that you fulfill the following requirements:

  • (Mandatory) Cisco Spaces Account: You will need an active Cisco Spaces account. You can register for a free trial of the Cisco Spaces license at https://spaces.cisco.com/.
  • (Mandatory) Cisco Spaces API key: A Cisco Spaces API key is required for each application. To obtain this ID, register for the SDK.
  • (Optional) Credentials to sign in with Apple or Google ID: If you decide to support Google or Apple native sign in as the user identity for your mobile app, you will need authorization credentials from Google or Apple to integrate its sign in into the app. To know how to create these credentials, see the About Authorization Credentials section.

Development Environment and Mobile Devices Requirement

  • Hotspot 2.0: Only mobile devices that support Hotspot 2.0 are supported by the SDK.
  • iOS-specific requirements:
    • iOS version 13.3 or higher
    • Xcode version 12 or higher
  • Android-specific requirements:
    • Android version 9 or higher

Registering for the SDK

To register for the Cisco Spaces SDK, follow the instructions provided in the Cisco Spaces Configuration Guide.

About Authorization Credentials (only for native sign in authentication method)

The following sections provide information about getting Google and Apple credentials required for integrating Google/Apple sign in option in your mobile app. This process will generate a secret_key and a client_ID (required information for registering your mobile app in Cisco Spaces when native sign in is chosen).

Google sign in

To create your Google credentials, go to Google API console. You will need to create two OAuth client ID credentials, one with Application type set to Web Application and another one with Application type set to Android.

  1. Creating OAuth client ID of type Web application

    1. Specify a name for the application. This name is only used to identify the client in the console and will not be shown to end users.
    2. Add an Authorized redirect URI and provide the following callback URL in the URI field: https://api.openroaming.net/api/profiles/callback/oauth2.
    3. Once the Web application client is created, a client ID and a client secret key will be shown. Save this client secret key to be used as part of your Google credentials.

      You can ignore the client ID field presented in this step. The client id needed for your Google credentials will be created in the next step.

  2. Creating OAuth client ID of type Android

    1. Specify a name for the application. This name is only used to identify the client in the console and will not be shown to end users.
    2. Specify a Package name. This is the same package name to be configured in the applicationId property in your app module's build.gradle file,as specified here.
    3. Follow the procedure in the console to get and configure a SHA-1 certificate fingerprint.
    4. Once the Android client is created, a client ID will be shown. Save this Client ID to be used as part of your Google credentials.

Once the web application OAuth client and the Android OAuth client are created, you can always return to Google API console to retrieve the client ID (from the Android client) and the client secret key (from the Web application client).

The above steps provide a summary of the procedure to be executed. For detailed information on creating your Google credentials, visit the Google documentation at the links given below:

Apple sign in

To create your Apple credentials, you need to do the following:

Note: For the latest instructions on creating your Apple credentials, visit the Apple documentation at the following links:

Create App ID
  1. Sign in to the Apple Developer website.
  2. Click on Certificates, Identifiers and Profiles.
  3. On the right pane, click Identifiers.
  4. On the Identifiers window, click + (the blue plus icon).
  5. On the Register a New Identifier window, select App IDs.
  6. On the Register an App ID window, enter the Description and Bundle ID for the app.
  7. Select the Sign in with Apple check box to enable it.
Create Services ID
  1. Sign in to the Apple Developer website.
  2. Click Certificates, IDs and Profiles, select Service ID, and click Continue.
  3. On the Register a New Identifier window, select Service ID.
  4. On the Register a Service ID window, enter the Description and Identifier.
  5. Select the Sign in with Apple check box to enable it.
Enter the application domain and return URL
  1. On the Identifiers page, select the Service ID that you created.
  2. Select Sign in with Apple, and click Configure.
  3. On the Web Authentication Configuration page, ensure that the correct Primary App ID is selected.
  4. In Domains and Subdomains, enter the api.openroaming.net or api.eu.openroaming.net name and domain.
  5. In the Return URLs field, specify the below callback URI:

    US :- https://api.openroaming.net/api/profiles/callback/oauth2

    EU :- https://api.eu.openroaming.net/api/profiles/callback/oauth2

    Ensure that the associated App ID is the Primary App ID.

Configure Private Key for Client Authentication
  1. Sign in to the Apple Developer website.
  2. On the right pane, click Keys.
  3. On the Keys window, click + (the blue plus icon).
  4. On the Register a New Key window, enter the Key Name and select the Sign in with Apple check box to enable it.
  5. Click Configure.
  6. On the Configure Key window, enter the Primary App ID and click Save.

    Remember to download your key. This file has a .p8 extension. Rename the downloaded file to key.txt.

  7. Click Done.

    Note down the Key ID displayed on the View Key Details page.

Generate Client Secret

Follow the instructions given in the Apple documentation to generate client_secret JWT token. Specify the renamed filename for key_file and the key ID as described in Step 6 and Step 7 above.

Adding the SDK to your Project

iOS Version

  1. In Xcode, go to File > Swift Packages > Add Package Dependency.
  2. In the Choose Project window, select the project where you would like to install the Cisco Spaces SDK package, and click Next.
  3. In the Choose Package Repository window, enter the HTTPS path of the repository where your Cisco Spaces SDK is located and click Next.

    Note: It might take a while for Xcode to verify the repository.

  4. After Xcode verifies the repository, on the Choose Package Options screen, enter the version 1.1.10. Click Next.

    Note: You must use the latest available release of Cisco Spaces SDK. Please check the changelog in order to determine which is the latest version. It might take a while for Xcode to verify the package, so you will not be able to add this information immediately.

  5. Xcode will open the Add Package to App screen and after a few minutes, the Cisco Spaces SDK package will be installed in your App.
  6. Under Build Phases > Link Binary with Libraries, add the Cisco Spaces SDK package.
  7. In Xcode, go to Project > Targets. Under the Signing & Capabilities tab, click Capability to add Hotspot Configuration.
Test whether the SDK was installed correctly on iOS
  1. Go to your project.
  2. Import OpenRoaming on your Swift file.
  3. Call the showVersion method and verify the returned value. If it is null, redo all the procedures above, otherwise it is working correctly.
let version = OpenRoaming.showVersion()

Android Version

Add Cisco Spaces SDK library as dependency in the app build.gradle file:

dependencies
{
   implementation ‘com.github.ciscodevnet:dna-spaces-sdk:1.0.24’
}

You will need to substitute the release number above (1.0.24) with the latest available release of Cisco Spaces SDK. To determine the latest version, please check the changelog.

Test whether the SDK was installed correctly on Android
  1. Go to your project.
  2. Import the com.cisco.or.sdk.OpenRoaming on your file.
  3. Call the validateSDKIsWorking method and verify the returned value. If it is null, redo all the procedures above.
val version = OpenRoaming.validateSDKIsWorking()

Preparing the Environment to Validate your App

Once your app is ready and Cisco Spaces SDK is integrated with it, a WiFi environment with OpenRoaming capabilities is required to validate it.

Refer to Cisco Spaces documentation to prepare this environment.