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
  • 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

Installation

Download SDK framework and then add it to 'Frameworks' folder inside your iOS project.

image

Embed SDK in your App

Make sure Cloud4WiSDKWiFi framework is added to your project and option 'Embed & Sign' is selected.

image

2. Configuration

In order to connect SDK to Cloud4Wi API you have to specify 'clientKey' and 'clientSecret'.

You can set them in your App Info.plist file by adding two following keys:

com_cloud4wi_sdk_wifi_api_client_key
{CLIENT-KEY-VALUE}
com_cloud4wi_sdk_wifi_api_client_secret
{CLIENT-SECRET-VALUE}

Alternatively you can configure client API credentials at runtime (Objective-C code example):

Cloud4WiSDKWiFi* cloud4WiSDKWiFi = [[Cloud4WiSDKWiFi alloc] init];

NSError *e = nil;
[cloud4WiSDKWiFi setAPIAuthParams:@"CLIENT-KEY-VALUE" clientSecret:@"CLIENT-SECRET-VALUE" error:&e];

3. Framework API overview


/**
 * Add or update WPA2-Enterprise Wi-Fi profile
 *
 * @param username - authorization user name
 * @param password - authorization password
 * @param onSuccess -  invoked if profile successfully installed
 * @param onError -  invoked if profile installation fails
 *
 */
- (void) createWPA2EnterpriseProfile: (NSString*) username
                           password: (NSString*) password
                          onSuccess: (void (^)(void)) onSuccess
                            onError: (void (^)(NSError *error)) onError;

/**
 * Add or update HotSpot 2.0 Wi-Fi profile
 *
 * @param username - authorization user name
 * @param password - authorization password
 * @param onSuccess -  invoked if profile successfully installed
 * @param onError -  invoked if profile installation fails
 *
 */
- (void) createHotSpot20Profile: (NSString*) username
                      password: (NSString*) password
                     onSuccess: (void (^)(void)) onSuccess
                       onError: (void (^)(NSError *error)) onError;

/**
 * Create customer in the Volare platform (Guest User)
 *
 * @param customer - user (Guest User) you want to create
 * @param onSuccess - invoked if customer successfully created
 * @param onError - invoked if exception occurred
 *
 */
- (void) createCustomer: (Customer*) customer
              onSuccess: (void (^)(CustomerCreateResponse *resp)) onSuccess
                onError: (void (^)(NSError *error)) onError;

/**
 * Get customer info from API by providing login/password credentials
 *
 * @param username - customer login
 * @param password - customer password
 * @param onSuccess - invoked if customer with provided credentials was not found
 * @param onError - invoked if exception occurred
 *
 */
- (void) getCustomerInfo: (NSString*) username
                password: (NSString*) password
               onSuccess: (void (^)(CustomerInfo *resp)) onSuccess
                 onError: (void (^)(NSError *error)) onError;

/**
 * Update API with customer metadata
 *
 * @param onSuccess - invoked if customer info update was proceeded without exceptions
 * @param onError - invoked if exception occurred
 *
 */
- (void) updateCustomerInfo: (void (^)(void)) onSuccess
                    onError: (void (^)(NSError *error)) onError;

/**
 * Check if customer with provided via CustomerQuery properties already exists
 *
 * @param query -  object with at least one field initialized
 * @param onSuccess - invoked if `customer exists` call was proceeded without exceptions
 * @param onError - invoked if exception occurred
 */
- (void) checkIfCustomerExists: (CustomerQuery *) query
                     onSuccess: (void (^)(BOOL)) onSuccess
                       onError: (void (^)(NSError *error)) onError;

/**
 * Get list of configured policies over API
 *
 * @param onSuccess - invoked if policies list was successfully obtained
 * @param onError - invoked if exception occurred
 *
 */
- (void) getListOfPolicies: (void (^)(NSArray *policies)) onSuccess
                   onError: (void (^)(NSError *error)) onError;

/**
 * Set client API authentication parameters
 *
 * @param _clientKey - API client key
 * @param _clientSecret - API client secret
 * @param error -  set to non-nil if failed
 */
- (void) setAPIAuthParams: (NSString*) _clientKey
             clientSecret: (NSString*) _clientSecret
                    error: (NSError**) error;

/**
 * Returns list of created WPA2EnterpriseProfiles
 */
- (NSArray *) getCreatedWPA2EnterpriseProfiles;

/**
 * Configure list of application to be interlinked with current
 *
 * @param identifiers - list of applications identifiers
 */
- (void) setInterlinkedC4WIMobileSDKApplications: (NSArray *) identifiers;

/**
 * Get list of application identifier current interlinked with
 */
- (NSArray *) getInterlinkedC4WIMobileSDKApplications;


3. Required Capabilities

In order to use the Cloud4WiSDKWiFi you have to add the 'Hotspot Configuration' capability to your application:

image

4. Code examples:

In the following code example we create new customer using Cloud4Wi API and then install WPA2-EnterpriseWi-Fi profile. After that when in range of configured Wi-Fi network iOS device will connect automatically.

Example represents the following use-case:

  1. SDK configuration.
  2. Read the list of organization policies from API.
  3. Creating new customer in API.
  4. Verifying customer credentials in API by retrieving customer info (optional).
  5. Create WPA2-Enterprise Wi-Fi profile on iOS device.

NSError *e = nil;
    Cloud4WiSDKWiFi *cloud4WiSDKWiFi = [[Cloud4WiSDKWiFi alloc] init];
    
    [cloud4WiSDKWiFi setAPIAuthParams:@"{CLIENT-KEY-VALUE}" clientSecret:@"{CLIENT-SECRET-VALUE}" error:&e];
    if (e) {
        NSLog(@"ERROR. Cannot set API credentials: %@", [e localizedDescription]);
        return;
    }

    [cloud4WiSDKWiFi getListOfPolicies: ^(NSArray *policies) {
        NSLog(@"INFO: Policies successfully obtained from API");
        
        Customer* customer = [[Customer alloc] init];
        [customer setUsername:@"test_cutomer@cloud4wi.com"];
        [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
         */
        NSMutableDictionary *approvedPolicies = [[NSMutableDictionary alloc] init];

        for (Policy* policy in policies) {
            [approvedPolicies setObject:@"true" forKey:policy.name];
        }

        [customer setPolicies:approvedPolicies];
        
        [cloud4WiSDKWiFi createCustomer:customer onSuccess:^(CustomerCreateResponse *customerCreateResp) {
            NSLog(@"INFO: Customer successfully created");
            
            /*
             * Assure new customer has been successfully created via Server API by checking newly created customer's credentials
             * This step is OPTIONAL
             */
            [cloud4WiSDKWiFi getCustomerInfo:[customer username] password:[customer password] onSuccess:^(CustomerInfo *resp) {
                NSLog(@"INFO: Customer with provided credentials exitsts");
                
                /*
                 * Here we are calling iOS API to create WPA2-Enterprise Wi-Fi Profile for recently created new customer
                 */
                [cloud4WiSDKWiFi createWPA2EnterpriseProfile:customer.username password:customer.password onSuccess:^{
                    NSLog(@"INFO: Wi-Fi profile successfully created");
                } onError:^(NSError *error) {
                    NSLog(@"ERROR. Cannot create Wi-Fi profile: %@", [error localizedDescription]);
                }];
                            
            } onError:^(NSError *error) {
                NSLog(@"ERROR. Cannot check credentials: %@", [error localizedDescription]);
            }];
        } onError:^(NSError *error) {
            NSLog(@"ERROR. Cannot create customer: %@", [error localizedDescription]);
        }];
    } onError: ^(NSError *error) {
        NSLog(@"ERROR. Cannot get list of policies: %@", [error localizedDescription]);
    }];

    


4. Additional features

Interlinking multiple applications on one device.

Cloud4WiSDKWiFi allows you to share information about installed Wi-Fi profiles among applications on same iOS device.This will help to avoid duplications of Wi-Fi profiles and make your application more flexible.

NOTE: this feature is optional, you may need it only if you integrate SDK in more than one application from your domain.

To enable interlinking you have to add 'App Group' capability in every application where SDK is integrated.Group name must be set to 'group.com.cloud4wi.sdk.wifi':

image

After adding required capability you have to supply SDK with the list of interlinked applications identifiers:

Cloud4WiSDKWiFi *sdk = [[Cloud4WiSDKWiFi alloc] init];
   [sdk setInterlinkedC4WIMobileSDKApplications:[NSArray arrayWithObjects: @"com.c4w.ApplicationTwo", nil]];