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;

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.

Returns list of created WPA2EnterpriseProfiles

 /**
 * Returns list of created PasspointProfiles
 */
- (NSArray<PasspointProfile *> *) getCreatedPasspointProfiles;

Examples

How to get the list of Passpoint profiles installed by the app, get the first one and print its ssid value.

let cloud4WiSDKWiFi = Cloud4WiSDKWiFi.init()
var profiles: Array<PasspointProfile>
profiles = cloud4WiSDKWiFi.getCreatedPasspointProfiles()
var profile : PasspointProfile
profile = profiles[0]
print(profile.ssid);

Cloud4WiSDKWiFi *cloud4WiSDKWiFi = [[Cloud4WiSDKWiFi alloc] init];
NSArray* profiles = [cloud4WiSDKWiFi getCreatedPasspointProfiles];
PasspointProfile* profile = [profiles firstObject];
NSLog(profile.ssid);

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) {

Update the customer's attributes

/**
 * Update existing customer.
 *
 * @param customer - Customer with all fields that needs to be updated. All customer fields except 'username', 'password' and 'lock' can be updated with this method.
 * @param onSuccess - invoked if customer successfully updated
 * @param onError - invoked if exception occurred
 *
 */
- (void) updateCustomer: (Customer*) customer
              onSuccess: (void (^)(BOOL)) onSuccess
                onError: (void (^)(NSError *error)) onError NS_SWIFT_NAME( updateCustomer(_:onSuccess:onError:) );

The attributes:

username, password, lock

are not available in customer update.

The function updates the customer created with functions createCustomer, setupCustomer and getCustomerInfo.

Examples

var customer = Customer();
customer?.firstName = "Michele-edit"
customer?.lastName = "Rossi-edit"
customer?.email = email+"edit"
customer?.language = "en"
customer?.extId="extId-12345677810-edit"
customer?.extProp1="extP1-1234567789-edit"
customer?.extProp2="extIdP2 -1234567789-edit"
customer?.ppd = false
customer?.profiling = false

let document = CustomerDocument()
document.passportNumber="PN-123456-edit"
document.personalId="personalId-123-edit"
document.memberId="memberId-123-edit"
customer?.document = document

customer?.emailVerified=false

customer?.country = "US"
customer?.birthDate = "2018-12-01"
customer?.gender = "M"
customer?.phoneNumber = "+391111111110000"
customer?.phoneVerified=false

let customFields = ["doYouLikeBeer":"yes","doYouLikeWine":"yes"]
customer?.custom = customFields

for policy in policies {
    approvedPolicies[policy] = "false"
}
customer?.policies = approvedPolicies

cloud4WiSDKWiFi.updateCustomer(customer) {_ in
    print("INFO: Update customer success")
} onError: { (error) in
    print(error)
}

Cloud4WiSDKWiFi *cloud4WiSDKWiFi = [[Cloud4WiSDKWiFi alloc] init];
	
	Customer* customer;
	[customer setFirstName:@"Michele-edit"];
	[customer setLastName:@"Rossi-edit"];
	[customer setEmail: @"email-edit"];
	[customer setLanguage:@"en"];
	[customer setExtId: @"extId-12345677810-edit"];
	[customer setExtProp1:@"extP1-1234567789-edit"];
	[customer setExtProp2:@"extIdP2 -1234567789-edit"];
	[customer setPpd: [NSNumber numberWithBool:false]];
	[customer setProfiling:[NSNumber numberWithBool:false]];
	
	CustomerDocument* document;
	[document setPassportNumber:@""];
	[document setPersonalId:@""];
	[document setMemberId:@""];
	
	[customer setDocument:document];

	[customer setEmailVerified:false];
	
	[customer setCountry:@"US"];
	[customer setBirthDate:@"2018-12-01"];
	[customer setGender:@"M"];
	[customer setPhoneNumber:@"+391111111110000"];
	[customer setPhoneVerified:false];
	
	NSDictionary *customFields = @{@"doYouLikeBeer": @"yes", @"doYouLikeWine" : @"yes"};
	
	[customer setCustom:customFields];
	
	[cloud4WiSDKWiFi getListOfPolicies:^(NSArray<NSString *> *policies) {
		NSMutableDictionary *approvedPolicies = [[NSMutableDictionary alloc] init];
		for (NSString* policy in policies) {
			[approvedPolicies setObject:@"true" forKey:policy];
		}
		[customer setPolicies:approvedPolicies];
		
		[cloud4WiSDKWiFi updateCustomer:customer onSuccess:^(BOOL) {
			NSLog(@"INFO: Update customer success");
		} onError:^(NSError *error) {
			NSLog(@"error");
		}];
	} onError:^(NSError *error) {
		NSLog(@"error");
	}];

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:

1. Read the list of organization policies (the term "policies" is used to refer to consents and agreements that are configured on the Cloud4Wi account)

2. Creating new customer

3. Verifying customer credentials in API by retrieving customer info (optional)

4. 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"];
}

List of methods

The SDKs provide a few basic methods that ultimately allow provisioning the user device with a WiFi profile. There are two main steps to provision a WiFi profile using the SDK:

1. Initialize a User

2. Install the WiFi Profile

Setup App project

To authenticate the SDK and connect it to your Cloud4Wi account, you need to generate an API key and API secret.

In the Cloud4Wi dashboard, go to Developers and select the WiFi SDK tab. Click the button New Mobile Add. The app Project dialog appears.

Enter a reference name for your app project. Enter the Android Package Name and iOS Bundle ID.

Enter the name of the SSID that must match the one used in the WiFi network. Leave Hidden SSID unchecked.

In the Passpoint section, enter your Domain Name, such as <company_name>.securewifi.io. In the Operator Friendly Name enter a value that identifies your company for the end users, such as "Secure WiFI by Company".

Check "Add the "Settlement-Free" RCOI to Passpoint profiles" if you want your mobile app users to be able to connect automatically to the WiFi of millions of settlement-free access points around the world from the OpenRoaming federation.

Click Save to return to the main table. Copy the API Key and API Secret in the SDK Credentials column of the app you just created.

Initializing a User

A User must be created on the Cloud4Wi systems before creating and installing a WiFi Profile.

User properties

Users can be initialized with attributes and identifiers that allow the reconciliation of the user data with external systems, including CRMs, CDPs, and marketing automation tools. This includes email address, phone number, or any external identifiers known to the mobile app (check the Customer object for iOS and Android for the full list of attributes).

The user can be initialized by passing a specific username and password generated by the mobile app. If not provided in the initialization, Cloud4Wi generates random network credentials associated with the user, which will then be used to generate either Passpoint or WPA2 Enterprise Wireless Profiles.

Consents

Cloud4Wi allows configuring specific data processing rules in the account configuration that process each individual user's data based on the consent fields set on its record. Coud4Wi allows to create any custom consent fields from the dashboard, but it comes with 3 pre-configured consents:

• Privacy Policy

• Terms of Service

• Marketing

The Marketing consent is an optional, pre-defined field that can be set to record consent to receive promotional marketing communications. The same purpose can be achieved using custom fields if necessary.

To retrieve the custom consents, if needed, you can use the dedicated methods (getListOfPolicies)

The SDK method to initialize the user also requires setting the profiling parameter that determines whether the customer could be "profiled' or not. The Profiling processing activity processes and stores the customer visit history and computes personalized behavioral attributes.

When to initialize the user

The user can be initialized at any time by the app, for example contextually with the app sign-up process (if any), or right before triggering the WiFi Profile installation.

Methods

Android

iOS

Install the WiFi Profile

WiFi Profiles are configuration files, specific to each operative system, that allow a device to connect and authenticate on a WiFi network. The method to install the WiFi Profile takes as input the network credentials generated in the previous step.

When the method to install the WiFi Profile is invoked, the Operative System prompts an alert to the user to ask for permission/confirmation (see user experience).

Cloud4Wi SDK provides two types of authentication methods:

• WPA2 Enterprise

• Passpoint

Read the Overview to learn more about the differences between WPA2 Enterprise and Passpoint.

Methods

Android

iOS

Add or update WPA2-Enterprise Wi-Fi profile

This method triggers the installation of a WPA2-Enterprise Wi-Fi profile in the device. The OS will trigger a dialog to ask the user the consent to allow such operations. See User Experience

/**
 * @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;

Username and password are the WiFi credentials of a Cloud4wi customer. When you create a customer using the method createCustomer the credentials are returned in onSuccessin the CustomerCreateResponse object.

Examples

let cloud4WiSDKWiFi = Cloud4WiSDKWiFi.init()
cloud4WiSDKWiFi.createWPA2EnterpriseProfile(user, password: password) {
	print("create WPA enterprise profile success")
	DispatchQueue.main.async {
		success(true)
	}
} onError: { (error) in
	DispatchQueue.main.async {
		success(false)
	}
}

Cloud4WiSDKWiFi *cloud4WiSDKWiFi = [[Cloud4WiSDKWiFi alloc] init];
[cloud4WiSDKWiFi createWPA2EnterpriseProfile:@"Username" password:@"password"] onSuccess:^{
     NSLog(@"INFO: Wi-Fi profile successfully created");
      } onError:^(NSError *error) {
             NSLog(@"ERROR. Cannot create Wi-Fi profile: %@", [error localizedDescription]);
}];

Add or update Passpoint Wi-Fi profile

This method triggers the installation of a Passpoint Wi-Fi profile in the device.

/**
 * Add or update Passpoint 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) createPasspointProfile: (NSString*) username
                       password: (NSString*) password
                      onSuccess: (void (^)(void)) onSuccess
                        onError: (void (^)(NSError *error)) onError;

Username and password are the WiFi credentials of a Cloud4wi customer. When you create a customer using the method createCustomer the credentials are returned in onSuccessin the CustomerCreateResponse object.

Examples

let cloud4WiSDKWiFi = Cloud4WiSDKWiFi.init()
cloud4WiSDKWiFi.createPasspointProfile(user, password: password) {
	print("create WPA enterprise profile success")
	DispatchQueue.main.async {
		success(true)
	}
} onError: { (error) in
	DispatchQueue.main.async {
		success(false)
	}
}

Cloud4WiSDKWiFi *cloud4WiSDKWiFi = [[Cloud4WiSDKWiFi alloc] init];
[cloud4WiSDKWiFi createPasspointProfile:@"Username" password:@"password"] onSuccess:^{
     NSLog(@"INFO: Wi-Fi profile successfully created");
      } onError:^(NSError *error) {
             NSLog(@"ERROR. Cannot create Wi-Fi profile: %@", [error localizedDescription]);
}];

Returns the identified of the customer created/logged with Cloud4wi Wifi SDK

Get the list of configured policies

Returns list of created WPA2EnterpriseProfiles

Examples

How to get the list of WPA2-Enterprise profiles installed by the app, get the first one and print its ssid value.

Search a Customer by customer properties

This method allows checking if a Customer with certain attributes (e.g. email or phone number) already exists in the Cloud4Wi account.

Update a Customer metadata

Retrieve a Customer by username/password

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.

Get the of applications interlinked with the current one

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

Close customer session

/**
 * Close customer session (it removes the customerId saved during the create customer)
 * Removes any reference to the customer
 */
- (void) logout;

The session is opened when one of this functionscreateCustomer, setupCustomer and getCustomerInfo return success.

It deletes passpoint internet profiles installed in the device using createPasspointProfile and createWPA2EnterpriseProfile.

Set SDK authentication parameters

/**
 * Set the SDK 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;

NSString *username;
NSString *password;
NSString *firstName;
NSString *lastName;
NSString *phoneNumber;
NSString *email;
NSString *gender;
NSString *birthDate;
NSString *language;
NSString *country;
NSString *zipCode;
NSString *companyName;
NSString *civilStatus;
BOOL phoneVerified;
BOOL emailVerified;
NSNumber *ppd;
NSNumber *profiling;
NSDictionary *custom;
NSDictionary *policies;
CustomerDocument *document;
BOOL lock;
NSString *extId;
NSString *extProp1;
NSString *extProp2;

Note:

The attributes:

username, password, lock

are not available in the update customer function

- (void) updateCustomer: (Customer*) customer
              onSuccess: (void (^)(BOOL)) onSuccess
                onError: (void (^)(NSError *error)) onError;

Format

Policies

They represent the list of the policy to apply to the customer. You can retrieve them using the function

cloud4WiSDKWiFi.getListOfPolicies

It is mandatory that the policies returned by the function getListOfPolicies in position 0 and 1 (named "termsOfUse" and "privacy") are set to true.

Profiling and PPD

In order to be able to process and profiling the customer it is necessary that the attributes profiling and ppd are set to true.

Init example

let customer = Customer()
				
let approvedPolicies = ["termsOfUse":"true", "privacy":"true"]
customer?.policies = approvedPolicies

customer?.firstName = "Michele"
customer?.lastName = "Rossi"
customer?.email = email
customer?.language = "it"
customer?.extId="extId-12345677810"
customer?.extProp1="extP1-1234567789"
customer?.extProp2="extIdP2 -1234567789"
customer?.ppd = true
customer?.profiling = true

let document = CustomerDocument()
document.passportNumber="PN-123456"
document.personalId="personalId-123"
document.memberId="memberId-123"
customer?.document = document

customer?.emailVerified=true

customer?.country = "IT"
customer?.birthDate = "2000-12-01"
customer?.gender = "F"
customer?.phoneNumber = "+39111111122222"
customer?.phoneVerified=true

customer?.lock = false

let customFields = ["doYouLikeBeer":"no"]
customer?.custom = customFields

NSDictionary *termsAndPrivacy = @{@"termsOfUse": @"true", @"privacy" : @"true"};
Customer* customer;
[customer setPolicies:termsAndPrivacy];
	
[customer setFirstName:@"Michele"];
[customer setLastName:@"Rossi"];
[customer setEmail: @"email"];
[customer setLanguage:@"en"];
[customer setExtId: @"extId-12345677810"];
[customer setExtProp1:@"extP1-1234567789"];
[customer setExtProp2:@"extIdP2 -1234567789"];
[customer setPpd: [NSNumber numberWithBool:false]];
[customer setProfiling:[NSNumber numberWithBool:false]];	
CustomerDocument* document;
[document setPassportNumber:@""];
[document setPersonalId:@""];
[document setMemberId:@""];
	
[customer setDocument:document];

[customer setEmailVerified:true];
	
[customer setCountry:@"US"];
[customer setBirthDate:@"2018-12-01"];
[customer setGender:@"M"];
[customer setPhoneNumber:@"+391111111110000"];
[customer setPhoneVerified:false];
	
NSDictionary *customFields = @{@"doYouLikeBeer": @"yes", @"doYouLikeWine" : @"yes"};
	
[customer setCustom:customFields];

1.7.0

• Track customers profile status

1.6.0

• fix getCreatedWPA2EnterpriseProfiles and getCreatedPasspointProfiles

• introduced deleteWPA2EnterpriseProfile

1.5.0

• Added deletePasspointProfile method

• In the logout are removed the Passpoint profile installed

1.4.0

• Added method updateCustomer

• Added DEBUG_MODE

• Fix support iOs simulator for Apple Silicon architecture

1.3.1

• fix date format in 'lastSeen' field

1.3.0

• Passpoint support

1.2.0

• New create customer function with deduplication on specific parameter

• Extended support of custom policies

Note: this version has not fully compatible with version 1.1.0 (see following migration guide)

Migration guide

Customer Create

The signature of the method

has been replaced by

To create a customer without deduplication:

Get list policies

The signature of the method getListOfPolicies

has been replaced by

1.1.0

• Create customer now support the attributes of the CreateCustomer API v3

• WPA2-Enterprise profile creation support

• Integration with Location SDK

NSString * status;
NSString * generated;
NSString * id;
NSString * organizationId;
NSString * locationId;
NSString * hotspotId;
NSString * username;
NSString * password;
NSNumber * mailSent;

Example

cloud4WiSDKWiFi.createCustomer(customer, deduplicate: nil) { (customerResponse) in
    if let customerResponse = customerResponse {
        print(customerResponse.status)
        print(customerResponse.generated)
        print(customerResponse.id)
        print(customerResponse.organizationId)
        print(customerResponse.locationId)
        print(customerResponse.username)
        print(customerResponse.password)
        print(customerResponse.mailSent)
    }
}

[cloud4WiSDKWiFi createCustomer:customer deduplicate:nil onSuccess:^(CustomerCreateResponse *customerCreateResp) {
	NSLog(@"%@", customerCreateResp.status);
	NSLog(@"%@", customerCreateResp.generated);
	NSLog(@"%@", customerCreateResp.id);
	NSLog(@"%@", customerCreateResp.organizationId);
	NSLog(@"%@", customerCreateResp.locationId);
	NSLog(@"%@", customerCreateResp.username);
	NSLog(@"%@", customerCreateResp.password);
	NSLog(@"%@", customerCreateResp.mailSent);	
	}  onError:^(NSError *error) {
	NSLog(@"ERROR. Cannot create customer: %@", [error localizedDescription]);
}];

output

Optional("OK") <- status
Optional("2022-07-08T13:15:43.885Z") <- generated
Optional("986a372347aac5e4a94516db835d58aa") <- id
Optional("3a8ccd060216452e09b2b32e750cb5eb") <- organizationId
Optional("ff80808170f5232b01754653699e109e") <- locationId
Optional("YDSDFDKJEAS") <- username
Optional("XXXXX") <- password
nil <- mailSent

Debug Mode

The debug mode allows you to have useful information on the console for debugging the application and the SDK. When enabled - SDK will print configuration parameter on startup and additional information on every API request that may help you during application development.

To enable the debug mode you have to configure this key into plist file of the app.

Push notification token

If you need to get the remote push notification token and associate it to a customer you have to init the SDK with the token using the method cloud4WiSDKWiFi.initC4w(token).

Example

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:

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

Example

output

Configure the list of apps to be linked to current app

Create a customer in the Cloud4Wi account

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

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 deduplicate string is optional. If set, the system will check if an existing 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, and source )

Pssible values of deduplicate string are:

To create a customer without any deduplicaiton check, set deduplicate string to null.

Customer username and password

If username and password are not set in the Customer object, they are assigned randomly during the customer creation and returned to the app in the CustomerCreate Response object.

Examples

Create customer

Create customer without deduplication

Create an empty Customer with default policies

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

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.

It deletes the WPA2 enterprise profile installed by the app.

It deletes the Passpoint profile installed by the app.

Add or update Passpoint Wi-Fi profile

This method triggers the installation of a Passpoint Wi-Fi profile in the device.

Add or update WPA2-Enterprise Wi-Fi profile

This method triggers the installation of a WPA2-Enterprise Wi-Fi profile in the device or update an existing one for the same network. The OS will trigger a dialog to ask the user the consent to allow such operations. See

List of methods

Integration

To integrate SDK library into your Android project you need to add Cloud4Wi repository. After that add the following dependency to your project's build.gradle along with 3 dependencies required by Cloud4Wi SDK as described below:

Configuration

In order to connect your application with your Cloud4Wi account, you need to provide SDK with clientKey and clientSecret credentials.

Credentials may be provided to SDK either via configuration property or at runtime. Add two records into your application's string.xml as in examples below:

Add the following in 'application' section of your AndroidManifest.xml file:

Required permissions

AndroidManifest of this library requires following permissions

Usage Example

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 API client credentials.

2. Read list of organization policies from API.

3. Creating new customer in API.

4. Verifying customer credentials in API.

5. Creation of WPA2-Enterprise Wi-Fi profile on Android device for test user to connect to test SSID.

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

Update a Customer metadata

    /**
     * Update API with customer metadata
     *
     * @param onSuccess - invoked if customer info update was proceeded without exceptions
     * @param onError - invoked if exception occurred
     * @return future with CustomerMetadata result
     *
     */
    @TargetApi(Build.VERSION_CODES.JELLY_BEAN_MR2)
    public Future<CustomerMetadata> updateCustomerInfo(Callback<CustomerMetadata> onSuccess, Callback<MobileSDKException> onError);

Update the customer's attributes

/**
     * Update existing customer.
     *
     * @param customer - Customer with all fields that needs to be updated.
     *                 All customer fields except 'lock', 'username' and 'password' can be updated with this method.
     *
     * @param onSuccess - invoked if customer successfully updated
     * @param onError - invoked if exception occurred
     *
     * @return future with Boolean which represents if customer was successfully updated
     */
    @TargetApi(Build.VERSION_CODES.JELLY_BEAN_MR2)
    public Future<Boolean> updateCustomer(Customer customer, Callback<Boolean> onSuccess, Callback<MobileSDKException> onError) {
        return asyncExecutor.execute(() -> apiService.updateCustomer(customer), onSuccess, onError);
    }

The attributes:

username, password, lock

are not available in customer update.

The function updates the customer created with functions createCustomer, setupCustomer and getCustomerInfo.

Returns list of created WPA2EnterpriseProfiles

    /**
     * Returns list of created WPA2EnterpriseProfiles
     * For Android versions 4.3 - 9  returns comprehensive list of configured WiFi profiles
     * For Android versions 10+ returns list of WiFi Suggestions installed by MobileSDK
     *
     * @return List of WPA2EnterpriseProfile objects which could be either of type:
     * `WPA2EnterpriseProfileWifiConfiguration` for Android versions 4.3 - 9
     * `WPA2EnterpriseProfileWifiNetworkSuggestion` for Android versions 10+
     * @throws Exception
     */
    public List<WPA2EnterpriseProfile> getCreatedWPA2EnterpriseProfiles() throws Exception;

Return the customerId saved during the create customer

    /**
     * Returns Customer ID
     * @return String `customerId` of the user registered in the app
     * @nullable if no Customer logged in or not registered yet
     */
    @TargetApi(Build.VERSION_CODES.JELLY_BEAN_MR2)
    public String getCustomerId();

Get the list of configured policies over API

This method allows retrieving the list of consents (referred as "policies" in this context) configured in the Cloud4Wi account, including the default one and the custom-defined ones.

The first 3 consents returned by the method are always the ones referring to:

• terms of use ("termsOfUse")

• privacy policy ("privacy")

• marketing ("marketing")

As a reminder, to create a Customer is always mandatory to set the privacy policy and the terms of use to true.

    /**
     * Get list of configured policies over API
     *
     * @param onSuccess - invoked if policies list was successfully obtained
     * @param onError - invoked if exception occurred
     *
     * @return future with list of policies
     */
    @TargetApi(Build.VERSION_CODES.JELLY_BEAN_MR2)
    public Future<List<String>> getListOfPolicies(Callback<List<String>> onSuccess, Callback<MobileSDKException> onError);

Set SDK authentication parameters

You can get your API client key and secret following these instructions.

   /**
     * Set client API authentication parameters
     *
     * @param clientKey - API client key
     * @param clientSecret - API client secret
     * @throws Exception if params are invalid
     */
    @TargetApi(Build.VERSION_CODES.JELLY_BEAN_MR2)
    public void setAPIAuthParams(String clientKey, String clientSecret) throws Exception;

Retrieve customer profile by username/password

 o
    /**
     * Get Customer 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
     *
     * @return future with <CustomerInfo> result
     */
    @TargetApi(Build.VERSION_CODES.JELLY_BEAN_MR2)
    public Future<CustomerInfo> getCustomerInfo(String username, String password, Callback<CustomerInfo> onSuccess, Callback<MobileSDKException> 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.

Configure the list of apps to be linked to current app

    /**
     * For Android versions 10+ add interlinked applications
     * which incorporate C4WIMobileSDK to get installed WiFi network suggestions
     *
     * @param authorities in a form of List<String>
     */
    @TargetApi(Build.VERSION_CODES.Q)
    public void setInterlinkedC4WIMobileSDKApplications(List<String> authorities);

1.7.0

• Track customers profile status

1.6.1

• fix to handler deleted/locked customer

1.6.0

• fix bug with SDK-Version in API requests header.

• fix bug with NullPointer in token update service.

1.5.0

• Added deletePasspointProfile and deleteWPA2EnterpriseProfile methods

• In the logout are removed the internet profiles installed

1.4.0

• Added method updateCustomer

• Added DEBUG_MODE

1.3.0

• Passpoint support

1.2.0

• New create customer function with deduplication on specific parameter

• Extended support of custom policies

Note: this version has not fully compatible with version 1.1.0 (see following migration guide)

Migration guide

Customer Create

The signature of the method

public Future<CustomerCreateResponse> createCustomer(
                                Customer customer, 
                                Callback<CustomerCreateResponse> onSuccess, 
                                Callback<MobileSDKException> onError);

has been replaced by

public Future<CustomerCreateResponse> createCustomer(
                                Customer customer, 
                                String deduplicate, 
                                Callback<CustomerCreateResponse> onSuccess, 
                                Callback<MobileSDKException> onError)

To create a customer without deduplication:

cloud4wiSDK.createCustomer(customer,null 

Get list policies

The signature of the method getListOfPolicies

public Future<List<Policy>> getListOfPolicies(
                                Callback<List<Policy>> onSuccess, 
                                Callback<MobileSDKException> onError);

has been replaced by

public Future<List<String>> getListOfPolicies(
                                Callback<List<String>> onSuccess, 
                                Callback<MobileSDKException> onError)

1.1.0

• Create customer now support the attributes of the CreateCustomer API v3

• WPA2-Enterprise profile creation support

• Integration with Location SDK