1 of 32

QuickStart

Sample app boilerplate

The following app demonstrates an example of using the WiFi SDK (and the Location SDK).

The app is ready to run but you have to set your own credentials by putting them into plist file. To test the WiFi section, based on Passpoint, you have to use a physical iOS device and have an access point configured in a Cloud4Wi account.

Installation

CocoaPods

Add pod 'c4w-wifi-sdk' to your Podfile and run pod install.

Swift Package Manager

https://github.com/Cloud4Wi-Create/iOS-WifiSDK-SwiftPackage

Configuration

In order to connect SDK to your Cloud4Wi account, you have to specify 'clientKey' and 'clientSecret'.

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

<key>com_cloud4wi_sdk_wifi_api_client_key</key>
<string>{CLIENT-KEY-VALUE}</string>
<key>com_cloud4wi_sdk_wifi_api_client_secret</key>
<string>{CLIENT-SECRET-VALUE}</string>

Required Capabilities

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

Usage example

This example represents the following use-case:

Read the list of organization policies (the term "policies" is used to refer to consents and agreements that are configured on the Cloud4Wi account)
Creating new customer
Verifying customer credentials in API by retrieving customer info (optional)
Create WPA2-Enterprise Wi-Fi profile on iOS device

let cloud4WiSDKWiFi = Cloud4WiSDKWiFi.init()
var error: NSError? = nil

// Policies
cloud4WiSDKWiFi.getListOfPolicies { (policies) in
	if let policies = policies {
		var approvedPolicies: Dictionary = [String: String]()
		for policy in policies {
			approvedPolicies[policy] = "true"
		}
		let customer = Customer()
		customer?.firstName = "John"
		customer?.lastName = "Red"
		customer?.email = "john@cloud4wi.com"
		customer?.policies = approvedPolicies
		
		cloud4WiSDKWiFi.createCustomer(customer, deduplicate: "email") { (customerResponse) in
			if let customerResponse = customerResponse {
				print("INFO: Customer successfully created")
				cloud4WiSDKWiFi.getCustomerInfo(customerResponse.username, password: customerResponse.password) { (info) in
					print("INFO: Customer with provided credentials exists")
					if let username = customerResponse.username, let password = customerResponse.password {
						self.createCertificateWithUser(username, andPassword: password, andMobileSDK: cloud4WiSDKWiFi, success: success)
					}
				} onError: { (error) in
					if let error = error {
						DispatchQueue.main.async {
							print("ERROR. Cannot check credentials:")
							success(false)
						}
						return
					}
				}
			} else {
				DispatchQueue.main.async {
					print("No customerResponse found")
					success(false)
				}
				return
			}
		} onError: { (error) in
			if let error = error as NSError? {
				DispatchQueue.main.async {
					print("ERROR. Cannot create customer")
					success(false)
				}
				return
			}
		}
	} else {
		DispatchQueue.main.async {
			print("No policies found")
			success(false)
		}
		return
	}
} onError: { (error) in
	DispatchQueue.main.async {
		if let error = error {
			print("ERROR. get list of policies")
			success(false)
		}
		return
	}
}

NSError *e = nil;
Cloud4WiSDKWiFi *cloud4WiSDKWiFi = [[Cloud4WiSDKWiFi alloc] init];
   /*
    * OPTIONAL - Retrieve the list of policies configured in Cloud4Wi, including custom ones
    */
   [cloud4WiSDKWiFi getListOfPolicies: ^(NSArray<NSString *> *policies) {
       NSLog(@"INFO: Policies successfully obtained from API");
       
       /*
        * Init Customer object with all optional attributes
        */
       Customer* customer = [[Customer alloc] init];
       [customer setFirstName:@"John"];
       [customer setLastName:@"Red"];
       [customer setExtId:@"12345677810"];    
       [customer setEmail:"john@cloud4wi.com"];

       /*
        * In order to register new customer the policies in position 0 (termsOfUse) and 1 (privacy) 
        * returned by getListOfPolicies must be set to true
        */
       NSMutableDictionary *approvedPolicies = [[NSMutableDictionary alloc] init];
       for (NSString* policy in policies) {
           [approvedPolicies setObject:@"true" forKey:policy];
       }
       [customer setPolicies:approvedPolicies];
        
        
       /*
        * Create Customer in Cloud4Wi account. If not provided, WiFi username and password 
        * are assigned automatically and returned in the method response
        */
       [cloud4WiSDKWiFi createCustomer:customer deduplicate:nil onSuccess:^(CustomerCreateResponse *customerCreateResp) {
           NSLog(@"INFO: Customer successfully created");
            
            /*
             * OPTIONAL - Assure new customer has been successfully created by checking newly created customer's credentials
             */
           [cloud4WiSDKWiFi getCustomerInfo:[customerCreateResp username] password:[customerCreateResp password] onSuccess:^(CustomerInfo *resp) {
               NSLog(@"INFO: Customer with provided credentials exitsts");
                
                /*
                 * Create WPA2-Enterprise Wi-Fi Profile for recently created new customer
                 * using the username/password returned by the createCustomer method
                 */
               [cloud4WiSDKWiFi createWPA2EnterpriseProfile:[customerCreateResp username] password:[customerCreateResp 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]);
}];

Keep the customer update

To track the last seen date of the customer and to keep always updated the remote push notification token (if applicable) it is necessary to call the method every time the app starts

func initC4w(pushToken: String)

- (void) initC4w: (NSString*) pushToken;

you can put it into didFinishLaunchingWithOptions for example

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
    let cloud4WiSDKWiFi = Cloud4WiSDKWiFi.init()
    cloud4WiSDKWiFi.initC4w("remote_push_token")
}

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    Cloud4WiSDKWiFi *cloud4WiSDKWiFi = [[Cloud4WiSDKWiFi alloc] init];
    [cloud4WiSDKWiFi initC4w:@"remote_push_token"];
}

SDK methods

The terms Customer and User are sometimes used in this documentation interchangeably, and they both refer to the app user

List of methods

Method

Description

initC4w

Initialize the SDK

This method is assumed to be called every time the app starts

/**
 * This method is assumed to be called every time the app starts.
 * This method, among other things, will (if the customer is already registered/logged-in the app)
 *  - update the `lastseen` of the customer
 *  - update the push token of the customer
 *  @param pushToken - push token passed from mobile app
 */

- (void) initC4w: (NSString*) pushToken;

createCustomer

Create a Customer in the Cloud4Wi account

This method initializes the customer object in the Cloud4Wi account. This method must be invoked before installing the WiFi Profile.

The customer object is described here.

- (void) createCustomer: (Customer*) customer
            deduplicate: (NSString *) deduplicateAttribute
              onSuccess: (void (^)(CustomerCreateResponse *resp)) onSuccess
                onError: (void (^)(NSError *error)) onError

Calling this function It is equivalent to a make a login. The success of this function opens a session with the customer returned. To close the session use logout() method.

Customer deduplication

The deduplicateAttribute attribute is optional. If set, the system will check if an exisitng customer with a matching attribute already exists in the same Cloud4Wi account.

If a matching record exists, the createCustomer method will override the existing matching customer attributes with the one passed in the createCustomer (except for username, password, source )

Pssible values of deduplicateAttribute are:

"phoneNumber", "email", "extId", "extProp1", "extProp2"

To create a customer without any deduplication check, set deduplicateAttribute to nil.

cloud4WiSDKWiFi.createCustomer(customer, deduplicate: nil)

Customer username and password

Username and password are credentials for the user in the c4w environment and are used for Radius authN/Z.

If username and password are not set in the Customer object, they are generated randomly during the customer creation and returned to the app in the CustomerCreate Response object. This auto generation of the credentials is the best way to proceed.

Response

If the method executes with no errors, it returns the object CustomerCreateResponse

Examples

Create customer

let customer = Customer()
				
var approvedPolicies: Dictionary = [String: String]()
approvedPolicies["termsOfUse"] = "true"
approvedPolicies["privacy"] = "true"
			
customer?.policies = approvedPolicies
customer?.firstName = "Michele"
customer?.email = email
                
cloud4WiSDKWiFi.createCustomer(customer, deduplicate: "email")

Customer* customer = [[Customer alloc] init];

NSMutableDictionary *approvedPolicies = [[NSMutableDictionary alloc] init];
    for (NSString* policy in policies) {
        [approvedPolicies setObject:@"true" forKey:policy];
    }

[customer setPolicies:approvedPolicies];        
[customer setFirstName:@"John"];
[customer setEmail:@"john@cloud4wi.com"];

[cloud4WiSDKWiFi createCustomer:customer deduplicate:@"email" onSuccess:^(CustomerCreateResponse *customerCreateResp) {

Create customer without deduplication

cloud4WiSDKWiFi.createCustomer(customer, deduplicate: nil)[cloud4WiSDKWiFi createCustomer:customer deduplicate:nil onSuccess:^(CustomerCreateResponse *customerCreateResp) {

[cloud4WiSDKWiFi createCustomer:customer deduplicate:nil onSuccess:^(CustomerCreateResponse *customerCreateResp) {

setupCustomer

Create an empty Customer with default policies

To use this function when you are integration just the Location SDK

/**
 * Create empty customer with default policies.
 *
 * @param onSuccess - invoked if customer was created sucessfully
 * @param onError - invoked if exception occurred
 *
 */
- (void) setupCustomer: (void (^)(CustomerCreateResponse *resp)) onSuccess
               onError: (void (^)(NSError *error)) onError;

Calling this function It is equivalent to a make a login. The success of this function opens a session with the customer returned. To close the session use logout() method.

getCustomerInfo

Retrieve a Customer by username/password

/**
 * Retrieve customer profile by username/passowrd
 *
 * @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;

Calling this function It is equivalent to a make a login with the username/password passed. The success of this function opens a session with the customer returned. To close the session use logout() method.

createCustomer

Create a Customer in the Cloud4Wi account

This method initializes the customer object in the Cloud4Wi account. This method must be invoked before installing the WiFi Profile.

The customer object is described here.

- (void) createCustomer: (Customer*) customer
            deduplicate: (NSString *) deduplicateAttribute
              onSuccess: (void (^)(CustomerCreateResponse *resp)) onSuccess
                onError: (void (^)(NSError *error)) onError

Calling this function It is equivalent to a make a login. The success of this function opens a session with the customer returned. To close the session use logout() method.

Customer deduplication

The deduplicateAttribute attribute is optional. If set, the system will check if an exisitng customer with a matching attribute already exists in the same Cloud4Wi account.

If a matching record exists, the createCustomer method will override the existing matching customer attributes with the one passed in the createCustomer (except for username, password, source )

Pssible values of deduplicateAttribute are:

"phoneNumber", "email", "extId", "extProp1", "extProp2"

To create a customer without any deduplication check, set deduplicateAttribute to nil.

cloud4WiSDKWiFi.createCustomer(customer, deduplicate: nil)

Customer username and password

Username and password are credentials for the user in the c4w environment and are used for Radius authN/Z.

Response

If the method executes with no errors, it returns the object CustomerCreateResponse

Examples

Create customer

let customer = Customer()
				
var approvedPolicies: Dictionary = [String: String]()
approvedPolicies["termsOfUse"] = "true"
approvedPolicies["privacy"] = "true"
			
customer?.policies = approvedPolicies
customer?.firstName = "Michele"
customer?.email = email
                
cloud4WiSDKWiFi.createCustomer(customer, deduplicate: "email")

Customer* customer = [[Customer alloc] init];

NSMutableDictionary *approvedPolicies = [[NSMutableDictionary alloc] init];
    for (NSString* policy in policies) {
        [approvedPolicies setObject:@"true" forKey:policy];
    }

[customer setPolicies:approvedPolicies];        
[customer setFirstName:@"John"];
[customer setEmail:@"john@cloud4wi.com"];

[cloud4WiSDKWiFi createCustomer:customer deduplicate:@"email" onSuccess:^(CustomerCreateResponse *customerCreateResp) {

Create customer without deduplication

cloud4WiSDKWiFi.createCustomer(customer, deduplicate: nil)[cloud4WiSDKWiFi createCustomer:customer deduplicate:nil onSuccess:^(CustomerCreateResponse *customerCreateResp) {

[cloud4WiSDKWiFi createCustomer:customer deduplicate:nil onSuccess:^(CustomerCreateResponse *customerCreateResp) {

QuickStart

Sample app boilerplate

The following app demonstrates an example of using the WiFi SDK (and the Location SDK).

Installation

CocoaPods

Add pod 'c4w-wifi-sdk' to your Podfile and run pod install.

Swift Package Manager

https://github.com/Cloud4Wi-Create/iOS-WifiSDK-SwiftPackage

Configuration

In order to connect SDK to your Cloud4Wi account, you have to specify 'clientKey' and 'clientSecret'.

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

<key>com_cloud4wi_sdk_wifi_api_client_key</key>
<string>{CLIENT-KEY-VALUE}</string>
<key>com_cloud4wi_sdk_wifi_api_client_secret</key>
<string>{CLIENT-SECRET-VALUE}</string>

Required Capabilities

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

Usage example

This example represents the following use-case:

Read the list of organization policies (the term "policies" is used to refer to consents and agreements that are configured on the Cloud4Wi account)
Creating new customer
Verifying customer credentials in API by retrieving customer info (optional)
Create WPA2-Enterprise Wi-Fi profile on iOS device

let cloud4WiSDKWiFi = Cloud4WiSDKWiFi.init()
var error: NSError? = nil

// Policies
cloud4WiSDKWiFi.getListOfPolicies { (policies) in
	if let policies = policies {
		var approvedPolicies: Dictionary = [String: String]()
		for policy in policies {
			approvedPolicies[policy] = "true"
		}
		let customer = Customer()
		customer?.firstName = "John"
		customer?.lastName = "Red"
		customer?.email = "john@cloud4wi.com"
		customer?.policies = approvedPolicies
		
		cloud4WiSDKWiFi.createCustomer(customer, deduplicate: "email") { (customerResponse) in
			if let customerResponse = customerResponse {
				print("INFO: Customer successfully created")
				cloud4WiSDKWiFi.getCustomerInfo(customerResponse.username, password: customerResponse.password) { (info) in
					print("INFO: Customer with provided credentials exists")
					if let username = customerResponse.username, let password = customerResponse.password {
						self.createCertificateWithUser(username, andPassword: password, andMobileSDK: cloud4WiSDKWiFi, success: success)
					}
				} onError: { (error) in
					if let error = error {
						DispatchQueue.main.async {
							print("ERROR. Cannot check credentials:")
							success(false)
						}
						return
					}
				}
			} else {
				DispatchQueue.main.async {
					print("No customerResponse found")
					success(false)
				}
				return
			}
		} onError: { (error) in
			if let error = error as NSError? {
				DispatchQueue.main.async {
					print("ERROR. Cannot create customer")
					success(false)
				}
				return
			}
		}
	} else {
		DispatchQueue.main.async {
			print("No policies found")
			success(false)
		}
		return
	}
} onError: { (error) in
	DispatchQueue.main.async {
		if let error = error {
			print("ERROR. get list of policies")
			success(false)
		}
		return
	}
}

NSError *e = nil;
Cloud4WiSDKWiFi *cloud4WiSDKWiFi = [[Cloud4WiSDKWiFi alloc] init];
   /*
    * OPTIONAL - Retrieve the list of policies configured in Cloud4Wi, including custom ones
    */
   [cloud4WiSDKWiFi getListOfPolicies: ^(NSArray<NSString *> *policies) {
       NSLog(@"INFO: Policies successfully obtained from API");
       
       /*
        * Init Customer object with all optional attributes
        */
       Customer* customer = [[Customer alloc] init];
       [customer setFirstName:@"John"];
       [customer setLastName:@"Red"];
       [customer setExtId:@"12345677810"];    
       [customer setEmail:"john@cloud4wi.com"];

       /*
        * In order to register new customer the policies in position 0 (termsOfUse) and 1 (privacy) 
        * returned by getListOfPolicies must be set to true
        */
       NSMutableDictionary *approvedPolicies = [[NSMutableDictionary alloc] init];
       for (NSString* policy in policies) {
           [approvedPolicies setObject:@"true" forKey:policy];
       }
       [customer setPolicies:approvedPolicies];
        
        
       /*
        * Create Customer in Cloud4Wi account. If not provided, WiFi username and password 
        * are assigned automatically and returned in the method response
        */
       [cloud4WiSDKWiFi createCustomer:customer deduplicate:nil onSuccess:^(CustomerCreateResponse *customerCreateResp) {
           NSLog(@"INFO: Customer successfully created");
            
            /*
             * OPTIONAL - Assure new customer has been successfully created by checking newly created customer's credentials
             */
           [cloud4WiSDKWiFi getCustomerInfo:[customerCreateResp username] password:[customerCreateResp password] onSuccess:^(CustomerInfo *resp) {
               NSLog(@"INFO: Customer with provided credentials exitsts");
                
                /*
                 * Create WPA2-Enterprise Wi-Fi Profile for recently created new customer
                 * using the username/password returned by the createCustomer method
                 */
               [cloud4WiSDKWiFi createWPA2EnterpriseProfile:[customerCreateResp username] password:[customerCreateResp 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]);
}];

Keep the customer update

To track the last seen date of the customer and to keep always updated the remote push notification token (if applicable) it is necessary to call the method every time the app starts

func initC4w(pushToken: String)

- (void) initC4w: (NSString*) pushToken;

you can put it into didFinishLaunchingWithOptions for example

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
    let cloud4WiSDKWiFi = Cloud4WiSDKWiFi.init()
    cloud4WiSDKWiFi.initC4w("remote_push_token")
}

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    Cloud4WiSDKWiFi *cloud4WiSDKWiFi = [[Cloud4WiSDKWiFi alloc] init];
    [cloud4WiSDKWiFi initC4w:@"remote_push_token"];
}

QuickStart

Sample app boilerplate

Installation

CocoaPods

Swift Package Manager

Configuration

Required Capabilities

Usage example

Keep the customer update

SDK methods

List of methods

initC4w

Initialize the SDK

createCustomer

Create a Customer in the Cloud4Wi account

Customer deduplication

Customer username and password

Response

Examples

Create customer

Create customer without deduplication

setupCustomer

Create an empty Customer with default policies

getCustomerInfo

Retrieve a Customer by username/password

createCustomer

Create a Customer in the Cloud4Wi account

Customer deduplication

Customer username and password

Response

Examples

Create customer

Create customer without deduplication

initC4w

Initialize the SDK

setupCustomer

Create an empty Customer with default policies

getCustomerInfo

Retrieve a Customer by username/password

SDK methods

List of methods

QuickStart

Sample app boilerplate

Installation

CocoaPods

Swift Package Manager

Configuration

Required Capabilities

Usage example

Keep the customer update

createWPA2EnterpriseProfile

Add or update WPA2-Enterprise Wi-Fi profile

Examples