Sample App

You can use this sample app which implements the main functions of the Cisco Spaces SDK. Its purpose is to demonstrate how these methods work and provide examples that developers can use to create their own applications.

The sample app allows the creation of an OpenRoaming profile on the mobile devices, as well as other functions related to managing user identity, displaying usage, and handling push notification. This allows users to seamlessly and securely connect to Wi-Fi without manually selecting a specific SSID, as well as the app to manage user identity. Those capabilities are the basis for building the various use cases described in the introduction section of this documentation.

In particular, the user identity management capability, provided by the SDK, can be combined with other applications on Cisco Spaces to create targeted engagements. For this use case, an Engagement app needs to be configured on Cisco Spaces for push notifications. Although the implementation of all of these use cases is outside the scope of the provided sample app, you can learn how to set up the Engagement app at https://dnaspaces.cisco.com/setupguide/app-engagements/.

Feel free to use sample app's code to build your own application.

What is Included in the Sample App

These are the features implemented in the sample app:

  • Initialization: Initialization is done via the registerSDK method.
  • Initial screen: Allows associating the user's identity to the CIsco Spaces backend. For exemplification purpose, the App implements the three forms of the associateUser method (Server Auth Code based, Webview based and UserId based). In a real application, only one of these methods will be used.
  • Profile installation: Once the user is associated, the installProfile method is called to deploy the profile. From that moment, the device is able to automatically connect to a Wi-Fi network that is part of the OpenRoaming federation (a OpenRoaming network is available at the device Wi-Fi settings).
  • Usage statistics: Once the user has been associated and the profile installed, the sample App displays a screen with the user's usage statistics (getUsageStatistic method).
  • Other features: The Usage screen also features the Account button, which on clicking displays a screen with the following options:
    • Modify the options regarding privacy (getPrivacySettings and setPrivacySettings methods are implemented) and receive or not push notification (associatePushIdentifier and dissociatePushIdentifier methods are implemented).
    • Update his/her account data (getUserDetails and updateUserDetails methods are implemented).
    • Uninstall the profile, which will also disassociate the user identity (deleteUserAccount or deleteProfile method).
    • Display the last push notification received, if any.

Getting Started with the Sample App – iOS Version

You will need to customize the iOS sample app with your own credentials to work with it. In order to be able to run the sample app, please:

  • Define a new bundle identifier for your customized sample app. The bundle identifier is a string defined by you and a reverse domain name notation, like domain.your-company.app-name. This can be used to avoid conflict.
  • Register the iOS sample app for the SDK.

By the end of this process, make sure that you have received a Cisco Spaces API key.

A separate Cisco Spaces API key must be generated for each sample app version, i.e., a key for the iOS version and a key for the Android version if you decide to build both.

To run the sample app on the device, follow the steps given below:

  1. Install IDE for Swift language (Xcode version 12 or higher is required).
  2. Install CocoaPods (package manager).
  3. Go to the OpenRoaming folder in Terminal and execute the below cocoapod install command.
    $ pod install
  4. Open App.xcworkspace (white icon).
  5. Change the bundle identifier of the Sample App, specifying the one you have used to register the SDK.
  6. Configure your credentials in the sample app as below:
    • In the file Utils/Constants.swift
      • update the property dnaSpacesKey with the value of the Cisco Spaces API key received
      • update the property appId with value of bundle identifier you have used to register the SDK
  7. Build and Run the project.

We recommend that you run the iOS sample app on a device. You might encounter the following limitations with the sample app on the simulator:

  1. Hotspot configuration will not work on a simulator. After authentication, an error alert will appear indicating that the simulator is not supported.
  2. The server auth code-based method does not work on a simulator.

Getting Started with the Sample App – Android Version

You will need to customize the Android sample app with your own credentials to work with it. In order to be able to run the sample app, please:

  • Define a new package name for your customized sample app. The package name is a string defined by you and a reverse domain name notation, like domain.your-company.app-name, can be used to avoid conflict.
  • Register the Android sample app for the SDK.

By the end of this process, make sure that:

  • A client id was generated
  • You have received a Cisco Spaces API key

    A separate Cisco Spaces API key must be generated for each sample app version, i.e., a key for the iOS version and a key for the Android version if you decide to build both.

Follow the steps given below to download and run the sample app:

  1. Install IDE for Kotlin language (Android Studio is recommended).
  2. Download sample app code from https://github.com/CiscoDevNet/DNASpacesSDKSampleApp-Android.
  3. Open the project in Android Studio.
  4. Configure your package name and credentials in the sample app as below:
    • In the file app/build.gradle
      • configure the package name you have used to register the SDK in android -> defaultConfig -> applicationId
    • In the file utils/Constant.kt
      • configure the package name you have used to register the SDK in val ApplicationId
      • configure your client id in val SERVER_CLIENT_ID
      • configure your Cisco Spaces API key in val dnaSpacesKey
  5. Build and run the project.