associateUser Method (Webview based)

The associateUser method should be called to associate a user identity to the mobile device. It is mandatory to associate a user identity before calling other SDK methods (except registerSDK). This is a polymorphic method. The form documented here refers to Option 2 - Webview based.

In this method, the user is authenticated by one of the identity providers supported by the Cisco Spaces Backend Service (Google, Apple, etc) in order to be associated. The associateUser method is responsible for the authentication. The method must receive a string indicating which service to be used in the authentication (parameter serviceName). For example, Google or Apple. It must also receive a webview to be used to render the authentication URL (parameter signingView).

Note: In this case, everything is done internally by the SDK method and the application will not have access to the credentials. It is handled directly by the Cisco Spaces Backend Service.

The associateUser method also receives the lambda expression signingHandler as a parameter, which allows the application to specify a code to be executed at the end of the method.

Particularly, in the iOS case, if an error occurs during associateUser method execution, this information is returned via a parameter in signingHandler handler. It is a good practice to always provide a lambda expression to handle a possible error.

iOS (Swift)

void OpenRoaming.associateUser(signingView: <SigningView>, serviceName: <String>, signingHandler: { error in <code> })

Android (Kotlin)

void OpenRoaming.associateUser(<SigningView>, <String>) { <code> }

Method Parameters

Attribute	Type	Description	Platform
signingView	SigningView	Webview component that will redirect to an authentication page based on the received serviceName. For example, if the service name is "google", then this component will redirect to the Google Authentication page.	iOS Android
serviceName	String	Which OpenRoaming identity providers should be used to identify the user. Supported values are: "google" or "apple".	iOS Android
signingHandler	Lambda expression	Lambda expression to be executed at the end of the method.	iOS Android

Lambda parameters for signingHandler

Attribute	Description	Platform
error	OpenRoamingError (ENUM) with the error message if the method execution is not successful. If the method executes successfully, this parameter receives nil value.	iOS

Code example

iOS (Swift)

OpenRoaming.associateUser(signingView: WebView, serviceName: "google", signingHandler: { error in
      if error == nil {
          print("User associated.")
      } else {
          print("There was a problem while associating the user: " + error)
      }
  })

Dependencies

Import OpenRoaming_framework.
registerSdk method must have been called at some earlier time.
A user identity cannot be currently associated.

Possible exceptions

Swift does not throw any exception, but provides error messages on lambda expressions instead. For more information on existing error messages, see OpenRoamingError.

Android (Kotlin)

OpenRoaming.associateUser(
      WebView,
      "google",
      signingHandler = {
          System.out.println("User associated.")
      }
  )

Dependencies

Import com.cisco.or.sdk.OpenRoaming.
registerSdk method must have been called at some earlier time.
A user identity cannot be currently associated.
Allowed permissions: "android.permission.INTERNET".

Possible exceptions

NotInitializedException
TokenEmptyException
LoginFailedException
ServiceBadResponseException
Hotspot2NotSupportedException

For more information on possible exceptions, see Exceptions.