installProfile Method

Provision an OpenRoaming user profile on the device based on the associated user account.

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

For iOS devices, if an error occurs during the installProfile method execution, this information is returned via a parameter in provisionProfileHandler. It is a good practice to always provide a lambda expression to handle a possible error.

For Android devices, the profile installation flow and user experience varies depending on the following factors:

• Operating system version running on the device (Android OS v10 - v13)

• Method of profile installation

  • Default method: In this method, a pop-up window is displayed on devices running Android OS v11 and higher. If the user clicks Allow in the pop-up window, the profile is installed successfully on the device and the device can connect to the Wi-Fi network whenever it is in the vicinity of the network. But, if the user clicks Cancel, the profile is not installed. In both cases, a callback is not sent and so the user action in the pop-up window cannot be detected.

    After clicking Cancel, if the user decides to install the profile, they can enable the pop-up by navigating to the following setting on their device: Settings > Apps > Special app access > Wi-Fi control > OpenRoaming > Allow app to control Wi-Fi

    This pop-up window is not displayed in devices running Android OS v10. Also, once the app is uninstalled, the device cannot connect to the Wi-Fi network.

  • Activity-based method: Just like in the default method, here too, a pop-up window is displayed on devices running Android OS v11 and higher and the profile is installed successfully on the device if the user clicks Allow in the pop-up window. This allows the device to connect to the Wi-Fi network whenever it is in range. However, if the user clicks Cancel, the profile is not installed. Unlike the default method above, in the activity-based method, a callback is sent identifying the user action in the pop-up window.

    The pop-up window is not displayed in devices running Android OS v10. In this method, though, once the app is uninstalled, the profile is not deleted from the device and hence the device can continue connecting to the Wi-Fi network.

iOS (Swift)

void OpenRoaming.installProfile(provisionProfileHandler: { error in <code> })

Android (Kotlin) (Method 1)

void OpenRoaming.installProfile { <code> }

Method Parameters

Note: Starting from SDK version 1.0.18 and later, the installProfile method gets a call back for the user selection on the profile install pop-up that is displayed.

• The call back works on Android devices running Android OS version 12 or later. On these devices, the installProfile method returns ACCEPTED or REJECTED.
• Call back is not supported on Android devices running Android OS version 11 or earlier. On these devices, the installProfile method returns UNKNOWN.

Android (Kotlin) (Method 2)

void OpenRoaming.installProfile(activity, exceptionHandler) { UserSelection(ACCEPTED/REJECTED)  -> <code> }

Method Parameters

Lambda parameters for provisionProfileHandler

Code example

iOS (Swift)

OpenRoaming.installProfile(signingHandler: { error in
      if error == nil {
          print("Profile was successfully installed.")
      } else {
          print("There was a problem while installing the profile.")
      }
  })

Dependencies

• Import OpenRoaming_framework.
• registerSdk method must have been called at some earlier time.
• A user identity must have been already associated via associateUser method.

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) Method 1 (Default profile installation)

try {
  OpenRoaming.installProfile{
  System.out.println("Profile was successfully installed.")
}
} catch (e:exception) {
  System.out.println("There was a problem while installing the profile.")
}

Dependencies

• Import com.cisco.or.sdk.utils.Utils.
• registerSdk method must have been called at some earlier time.
• A user identity must have been already associated via associateUser method.

Android (Kotlin) Method 2 (Activity-based profile installation)

try {
  OpenRoaming.installProfile(activity, exceptionHandler){
  System.out.println("Profile was successfully installed." + UserSelection.ACCEPTED/ UserSelection.REJECTED)
}
} catch (e:exception) {
  System.out.println("There was a problem while installing the profile.")
}

Dependencies

• Import OpenRoaming_framework.
• registerSdk method must have been called at some earlier time.
• A user identity must have been already associated via associateUser method.

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)

try {
  OpenRoaming.installProfile{
  System.out.println("Profile was successfully installed.")
}
} catch (e:exception) {
  System.out.println("There was a problem while installing the profile.")
}

Dependencies

• Import com.cisco.or.sdk.utils.Utils.
• registerSdk method must have been called at some earlier time.
• A user identity must have been already associated via associateUser method.

Possible exceptions

• EmptyProfileException
• Hotspot2NotSupportedException

For more information on possible exceptions, see Exceptions.