Mobile SDK - IOs Native

The Cloud4Wi iOS Mobile SDK offers a simple yet efficient Objective-C API that you can use to add rich WiFi capabilities to your iOS Apps.

Requirements:

  • SDK library: download the password-protected zip package below. The password will be communicated by Cloud4Wi during delivery
    Download library
  • JWT Token, shared by Cloud4Wi during delivery
  • SSID name: note that the SSID name has to be set in the App code, so make sure to know in advance the name of WiFi network you want to enable

Resources:

  • We prepared a getting started project that you can clone and import in your environment to get started. Contact our team to get access to the GIT.

1. Integration

You access the WiFi features of Mobile SDK through the main entity HotSpot2_0SDKFramework.

  • HotSpot2_0SDKFramework represents service that contains methods for creating WPA2-Enterprise and Hotspot 2.0 profiles to join to secure WiFi network and create users in the Cloud4Wi platform.

Installation

Download and unzip the SDK library to any folder on your hard drive. You’ll see the following folder structure:

image

Link to the SDK

Open your project on the top (with the blue icon) and select the General tab.
Click Embedded Binaries and then click on the plus button

image

In the window that appears, click on the Add Other… button and locate the HotSpot2_0SDKFramework.framework folder in the subdirectory where you saved the SDK on your hard drive:

image

Check tick on "Copy items if needed" option, it will copy your .framework file in other required sections.

image

This is how the Build Phase of your project should look like when you’re all done:

image

Update Framework Search Paths

Open your project on the top (with the blue icon) and select the Build Settings tab, and locate the Framework Search Paths setting in the list.
You can type “Framework search” in the search box to filter the big list of settings if necessary.

image

Double click on the Framework Search Paths item, and a popover will appear. Click the + button, and enter the path to the folder where you unzipped the SDK

image

The -ObjC linker flag

Make sure that the -ObjC flag is set. See documentation by click on the link

Required Capabilities

IMPORTANT: To use the HotSpot2.0 SDK, you must enable the Hotspot Configuration capability and Access WiFi Information in Xcode. See screenshot bellow.
image

2. Configuration

Configure Info.plist

In Xcode, right-click your project’s Info.plist file and select Open As -> Source Code.
Insert the following XML snippet into the body of your file just before the final  element.

In properties you can also set required SSID, key: ‘cloud4wi_hs2api_ssid’.


 cloud4wi_hs2api_jwt_token
    {jwt-token}
  cloud4wi_hs2api_ssid
     {SSID-value}  
     

Replace {jwt-token} with your Mobile’s App’s ID found on the Volare Dashboard.

NOTE: This two properties may be specified in Runtime. See API overview and examples for more info.

3. Framework API overview


 * @method createHotSpot20ProfileWithUsernameAndPassword:
 * @discussion This function adds or updates a Wi-Fi Hotspot 2.0 network configuration.
 * @param username - authorization user name
 * @param password - authorization password
 * @param reject  will be nil if the configuration is successfully stored, non-nil otherwise.
 *   If the configuration is found invalid or API encounters some other error then reject object return
 *   with instance of NSError containing appropriate error code. This API attempts to join the HotSpot 2.0 Wi-Fi network
 *   if the configuration is successfully added or updated and the network is found nearby.
 *
 */
- (void) createHotSpot20ProfileWithUsernameAndPassword:(NSString*) username
                                              password:(NSString*) password
                                                reject:(NSError **)reject;

/*!
 * @method createWPA2EnterpriseProfile:
 * @discussion This function adds or updates a WPA2-Enterprise network configuration.
 * @param username - authorization user name.
 * @param password - authorization password.
 * @param reject  will be nil if the configuration is successfully stored, non-nil otherwise.
 *   If the configuration is found invalid or API encounters some other error then reject object return
 *   with instance of NSError containing appropriate error code. This API attempts to join the WPA2-Enterprise Wi-Fi network with configured SSID
 *   if the configuration is successfully added or updated and the network is found nearby.
 */
- (void) createWPA2EnterpriseProfile:(NSString*) username
                            password:(NSString*) password
                              reject:(NSError **) reject;

/*!
 * @method checkCredentials:
 * @discussion This function validates customer username/password credentials over API.
 * @param username - customer username
 * @param password - customer password
 * @param error will be nil if the customer's credentials were validated. Non-nil error will be set if exception occured during credentials validation.
 * @return 1 if credentials are valid and 0 if invalid.
 */
- (NSNumber*) checkCredentials:(NSString*) username
                      password: (NSString*) password
                         error: (NSError**) error;

/*!
 * @method createCustomer - Create customer in the Volare platform (Guest User)
 * @discussion This function creates a customer in Volare platform.
 * @param customer - user (Guest User) you want to create.
 * @param error will be nill if the user has created successfully, non-nil otherwise.
 * @return return CustomerCreateResponse object which represents saved customer.
 */
- (CustomerCreateResponse*) createCustomer:(Customer*) customer
                       error: (NSError**) error;

/*!
 * @method getListOfPolicies
 * @discussion Returns list of policies for target organization.
 * @param error will be non-nil if if policies cannot be obtained.
 * @return return list of policies
 */
- (NSArray*) getListOfPolicies: (NSError**) error;

/*!
* @method setJwtToken sets JWT token value
* @discussion Set JWT token to use for web API.
* @param newJwtToken - valid JWT token value to use for web API.
* @param error will be non-nil if provided JWT is invalid.
*/
- (void) setJwtToken: (NSString*) newJwtToken error: (NSError**) error;

/*!
* @method setSSID sets SSID value
* @discussion Specifies SSID value for WPA2-Enterprise profiles
* @param newSSID - new SSID value
*/
- (void) setSSID: (NSString*) newSSID;

/*!
* @method getSSID gets configured SSID value.
* @discussion Get SSID value configured for new WPA2-Enterprise Wi-Fi profiles.
* @return return configured SSID value
*/
- (NSString*) getSSID;

4. Code examples:

In following code example we will create new customer in the API and then install WPA2-Enterprise
Wi-Fi profile on Android phone. After that when customer will be in range of Wi-Fi network with specified SSID -
his device will connect automatically.

This example represents following use-case.

  1. MobileSDK configuration. Setting of JWT and Wi-Fi SSID values.
  2. Read list of organization policies from API.
  3. Creating new customer in API.
  4. Verifing customer credentials in API.
  5. Creation of WPA2-Enterprise Wi-Fi profile on Android device for test user to connect to test SSID.

 NSError* e = nil;
    HotSpot2_0SDKFramework* mobileSDK = [[HotSpot2_0SDKFramework alloc] init];

    [mobileSDK setJwtToken:@"" error:&e];

    if (e) {
        NSLog(@"ERROR. Cannot set JWT.");
        return;
    }
    
    NSLog(@"JWT successfully set.");
    
     /*
      * Setting SSID for Wi-Fi profiles
      * Created WPA2-Enterprise profiles will connect to specified SSID automatically when in range
      */
    NSString* ssid = @"Mobile_SDK_Test";
    [mobileSDK setSSID: ssid];
    NSLog(@"SSID parameter configured.");
            
    /*
     * To register new customer we need to obtain required polices from API Server
     */
    
    NSArray* policies = [mobileSDK getListOfPolicies: &e];
    if (e) {
        NSLog(@"ERROR. Cannot get list of policies.");
        return;
    }
    
    NSLog([NSString stringWithFormat: @"Got policies. Num = %lu", [policies count]]);
    
    Customer* customer = [[Customer alloc] init];
    [customer setUsername:@"[email protected]om"];
    [customer setFirstname:@"Test"];
    [customer setLastname:@"Customer"];
    [customer setPassword:@"secure_password"];
    [customer setEmail:[customer username]];
    
    /*
     * In order to register new customer all polices requested by API Server should be accepted
     */
    NSMutableArray *approvedPolicies = [[NSMutableArray alloc] init];
    
    for (id policy in policies) {
        ApprovedPolicy* approvedPolicy = [ApprovedPolicy alloc];
        [approvedPolicy setId:[policy valueForKey:@"id"]];
        [approvedPolicy setValue: [NSNumber numberWithInt:1]];
        [approvedPolicies addObject:approvedPolicy];
    }
    
    NSLog([NSString stringWithFormat: @"Created approved policies array.Num = %lu", [approvedPolicies count]]);    
    
    [customer setPolicies:approvedPolicies];
    
    /*
     * Call Server API to create new customer
     */
    [mobileSDK createCustomer:customer error:&e];

    if (e) {
        NSLog([NSString stringWithFormat: [NSString stringWithFormat: @"ERROR. Cannot create customer: %@", [e localizedDescription]]);        
        return;
    }
    
    /*
     * Assure new customer has been successfully created via Server API by checking newly created customer's credentials
     * This step is OPTIONAL
     */
    NSNumber* resp = [mobileSDK checkCredentials:[customer username] password:[customer password] error:&e];
    if (e) {
        NSLog([NSString stringWithFormat: @"ERROR. Cannot check credentials: %@", [e localizedDescription]]);
        return;
    } else {
        if ([resp isEqualToNumber:[NSNumber numberWithInt:1]]) {
            NSLog(@"INFO: Credentials approved.");
        } else {
            NSLog(@"ERROR. Customer credentials invalid.");
            return;
        }
    }

    /*
     * Here we are calling iOS API to create WPA2-Enterprise Wi-Fi Profile for recently created new customer
     */
    [mobileSDK createWPA2EnterpriseProfile:[customer username] password:[customer password] reject:&e];
    
    if (e) {
        NSLog([NSString stringWithFormat: @"ERROR. Failed to create Wi-Fi profile: %@", [e localizedDescription]]);
    } else {
        NSLog(@"INFO: Wi-Fi profile successfully created.");
    }