List of methods

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

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:

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

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.

Cloud4Wi SDK provides two types of authentication methods:

• WPA2 Enterprise

• Passpoint

Methods

Android

iOS

WiFi SDK

Cloud4Wi WiFi SDK is a convenient Software Development Kit that helps you easily add seamless and secure WiFi connectivity to mobile apps and unlocks location services regardless of OS location permissions

Location SDK

Cloud4Wi Location SDK (referred to as "GeoUniq") helps you easily add location tracking to your app, overcoming native OS location tracking performances and capabilities.

Platform APIs

Platforms APIs allow managing Cloud4Wi resources programmatically, including places, contacts, moments and logs.

Webhooks

Webhooks allow integrating real-time events with your own data stack to unlock real-time and context-aware applications such as:

• trigger communications in real-time in your Marketing automation tool

• synch Contacts in real-time with your CRMS as soon as a person sign up

• feed Contact Profiles in real-time to clienteling interfaces when a person arrives in a location

Demo toolkit

Use Cloud4Wi demo apps for iOS and Android to test Cloud4Wi geofencing before integrating the SDK, or to test your implementation of Cloud4Wi side-by-side with a complete implementation

MyApps

Create and publish custom context-aware content during the WiFi onboarding or on the dashboard

Initialize the SDK

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

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.

Cloud4Wi WiFi SDK empowers mobile apps with instant, automatic, and fully encrypted WiFi connection upon arrival to enabled locations, allowing app users to get a stable and fast connection for a smooth on-site experience.

Thanks to the secure WiFi authentication, the Cloud4Wi platform detects deterministically users’ arrival on site enabling apps with reliable location-awareness regardless of the OS location permissions.

Quickstart

Want to get started quickly? Follow these four steps:

1. . Create an App project in your Cloud4Wi dashboard and retrieve the client key and client secret on your dashboard. These are the credentials you need to authenticate the SDK and connect it to your Cloud4Wi account.

2. Set up WiFi network. Set up the in your Cloud4Wi account and with WPA2-Enterprise and/or Passpoint configuration.

3. Integrate the Cloud4Wi SDK into your app. Integrate the . Or, before integrating, test WiFi connectivity with our for iOS and Android.

4. Enable integrations. Create a or enable server-side to send Cloud4Wi events and user context to other systems. Or, you can create a triggered message in .

WiFi connectivity

Cloud4Wi WiFi SDK empowers mobile apps with instant, automatic, and fully-encrypted WiFi connection upon arrival to enabled locations, empowering your app with a stable and fast connection to deliver a smooth on-site experience.

All your mobile users will be automatically connected and authenticated to the WiFi network as soon as they are in the range of the network.

Cloud4Wi SDK supports multiple WiFi authentication protocols to address different scenarios with the best solution: WPA2 Enterprise and Passpoint.

WPA2 Enterprise

WPA2 Enterprise is a standard protocol that allows devices to connect securely to a certain network identified by an SSID. These profiles are specific to the name of the SSID, which must be known before initializing and installing the profile. If the SSID on the network changes, the WiFi profile won't work anymore and a new profile needs to be installed.

This standard is supported by all mobile devices and WiFi hardware, making it a solid choice in case universal support is required - both on the end-user devices and network side. However, the dependency on the SSID name may pose some constraints in certain scenarios.

Passpoint

Passpoint is the next-generation hotspot technology based on the Hotspot 2.0 standard. the connection to a WiFi network using Passpoint does not depend on the name of the SSID. In fact, the same SSID can virtually broadcast multiple virtual operator networks. Passpoint also offers greater support for roaming across enterprise networks, as well as public and federated networks.

Passpoint is at the foundation of the OpenRaoming federation, which allows users to connect and authenticate to a vast number of networks managed by different service providers.

Location Moments

With Cloud4Wi WiFi SDK your app becomes aware when end users enter and visit any of your locations, and every on-site Moment becomes an opportunity to deliver powerful location-based experiences or drive monetization.

Location Events are deterministic, overcoming the accuracy limitations of geofencing in indoor and high-dense urban environments.

Privacy and Compliance

The WiFi SDK does not require Location permissions from the operative system to work. However, the SDK processes personal data for certain purposes so privacy regulations might require that you collect the proper consent from the customer.

For example, you can promote the new service to your mobile users (with a notification, banner, or button) and collect their acknowledgment and consent when they enroll.

For new users, you can rely on your existing Privacy Policy to collect the consent, and make sure it covers the personal data categories and purposes involved with this new service.

Network compatibility and requirements

You need to use a WiFi vendor and device models that are compatible with the service and certified by Cloud4Wi. Certified tested vendors for the WPA2 Enterprise mode so far:

• Aruba

• Juniper (Mist)

• Mikrotik

WPA2 Enterprise is a standard protocol, if the vendor is not listed among the tested ones, it is still very likely that is compatible with Cloud4Wi WiFi SDK. Please contact our team, we'll investigate the tech feasibility and develop the necessary integration if necessary.

Certified vendors for the Passpoint mode are:

• Juniper (Mist)

Mobile devices compatibility

The SDK is currently available for iOS and Android, however, it can be easily integrated into any app developed with non-native dev languages such as Flutter or React Native (our team will provide guidance on the process). The SDK is compatible with an Android OS starting for version 4.3 and iOS devices starting from iOS 11.0

The WPA2 Enterprise mode is compatible with all Android and iOS devices mentioned above.

The Passpoint mode is compatible with all iOS devices and with a subset of Android devices:

• starting from Android 12, Passpoint support is mandatory in all OEM vendors

• almost all devices with Android 10 and 11 support Passpoint

• for the oldest version of Android, the support of Passpoint is fragmented and depends on the device manufacturer. For example, Samsung phones support Passpoint starting from Android 8.

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 .

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:

To create a customer without any deduplication check, set deduplicateAttribute to 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

Examples

Create customer

Create customer without deduplication

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

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

- (NSString *) getCustomerId;

Returns list of created WPA2EnterpriseProfiles

- (NSArray<WPA2EnterpriseProfile *> *) getCreatedWPA2EnterpriseProfiles;

Examples

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

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

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

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]);
}];

Get the list of configured policies

Update the customer's attributes

The attributes:

username, password, lock

are not available in customer update.

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

Examples

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.

Close customer session

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.

Get the of applications interlinked with the current one

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

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;

Configure the list of apps to be linked to current app

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

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];

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

Example

output

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

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

has been replaced by

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

To create a customer without deduplication:

cloud4WiSDKWiFi.createCustomer(customer, deduplicate: nil)

Get list policies

The signature of the method getListOfPolicies

- (void) getListOfPolicies: (void (^)(NSArray<Policy *> *policies)) onSuccess
                   onError: (void (^)(NSError *error)) onError;

has been replaced by

- (void) getListOfPolicies: (void (^)(NSArray<NSString *> *policies)) onSuccess
                   onError: (void (^)(NSError *error)) onError;

1.1.0

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

• WPA2-Enterprise profile creation support

• Integration with Location SDK

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:

repositories {

    ...
    
    maven {
        url = 'https://artifacts.cloud4wi.com/release'
    }
}

dependencies {

    ...

    implementation 'com.google.android.gms:play-services-ads-identifier:17.0.0'
    implementation 'com.google.code.gson:gson:2.8.6'
    implementation 'com.auth0.android:jwtdecode:2.0.0'    
    implementation 'com.cloud4wi:c4w-wifi-sdk:{lib-version}'
}

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:

<resources>
    ...
    <string name="com.cloud4wi.sdk.wifi.api_client_key">{client-key-value}</string>
    <string name="com.cloud4wi.sdk.wifi.api_client_secret">{client-secret-value}</string>
</resources>

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

<application>
 ...
 <provider
           android:authorities="${applicationId}"
           android:multiprocess="false"
           android:exported="false"
           android:name="com.cloud4wi.sdk.wifi.storage.C4WIMobileSDKContentProvider"/>
</application>

Required permissions

AndroidManifest of this library requires following permissions

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

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.

Cloud4WiSDKWiFi mobileSDK = new Cloud4WiSDKWiFi(getApplicationContext());

        try {
            mobileSDK.setAPIAuthParams("{client-key-value}", "{client-secret-value}");
        } catch (Exception e) {
            Log.e(TAG, "Cannot set API credentials: ", e);
        }

        mobileSDK.updateCustomerInfo(result -> {}, e -> {});
        /*
         * To register new customer we need to obtain required polices from API Server
         */
        mobileSDK.getListOfPolicies(
                policies -> {
                    Log.i(TAG, "Got policies. Num = " + policies.size());
                    logInfo("Got " + policies.size() + " policies: ");
                    for (String p : policies) {
                        logOutput("  " + p);
                    }

                    Customer customer = new Customer();
                    customer.setFirstName("Test");
                    customer.setLastName("Customer");
                    customer.setEmail(customer.getUsername());

                    /*
                     * In order to register new customer all polices requested by API Server should be accepted
                     */
                    for (String policy : policies) {
                        customer.addPolicy(policy, true);
                    }

                    /*
                     * Call Server API to create new customer
                     */
                    mobileSDK.createCustomer(customer, null,
                            customerCreateResponse -> {
                                Log.i(TAG, "Customer successfully created.");
                                logInfo("Customer successfully created.");

                                /*
                                 * Assure new customer has been successfully created via Server API by checking newly created customer's credentials
                                 * This step is OPTIONAL
                                 */
                                    mobileSDK.getCustomerInfo(customerCreateResponse.getUsername(), customerCreateResponse.getPassword(),
                                            customerInfo -> {
                                                Log.i(TAG, "Credentials approved.");
                                                logInfo("Credentials approved.");

                                                /*
                                                 * Here we are calling Android API to create WPA2-Enterprise Wi-Fi Profile for recently created new customer
                                                 */
                                                mobileSDK.createWPA2EnterpriseProfile(customerCreateResponse.getUsername(), customerCreateResponse.getPassword(),
                                                        wpa2EnterpriseProfile -> {
                                                            Log.i(TAG, "Wi-Fi profile successfully created.");
                                                            logInfo("Wi-Fi profile successfully created.");
                                                        },
                                                        e -> {
                                                            Log.e(TAG, "Failed to create Wi-Fi profile: ", e);
                                                            logError("Failed to create Wi-Fi profile: " + e.getMessage());
                                                        });
                                            },
                                            e -> {
                                                Log.e(TAG, "Cannot approve credentials: ", e);
                                                logError("Cannot approve credentials - " + e.getMessage());
                                            }
                                    );
                            },
                            e -> {
                                Log.e(TAG, "Cannot create customer: ", e);
                                logError("Cannot create customer - " + e.getMessage());
                            }
                    );
                },
                e -> {
                    Log.e(TAG, "Cannot get policies: " +  e.getMessage());
                    logError("Cannot get policies - " + e.getMessage());
                }
        );

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

public void initC4w();

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.

/**
     * Create a customer in the Cloud4Wi account
     *
     * @param customer - user you want to create
     * @param deduplicate - attribute that will be used for customer deduplication.
     * @param onSuccess - invoked if customer successfully created
     * @param onError - invoked if exception occurred
     *
     * @return future with CustomerCreateResponse object which represents saved customer
     */
    public Future<CustomerCreateResponse> createCustomer(
                   Customer customer,
                   String deduplicate, 
                   Callback<CustomerCreateResponse> 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.

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:

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

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

cloud4wiSDK.createCustomer(customer, 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

Customer customer = new Customer();
customer.setFirstName("Luigi");
customer.setEmail("luigi@cloud4wi.com");

customer.addPolicy("termsOfUse", true);
customer.addPolicy("privacy", true);

//deduplication on email attributes
cloud4wiSDK.createCustomer(customer, "email", ...)

Create customer without deduplication

cloud4wiSDK.createCustomer(customer, null, ...)

Initialize the SDK

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

    /**
     * This method assumed to be called every time the app is started.
     * This method will (if the customer is already registered/logged in the app)
     *  - update the `lastseen` of the customer
     *  - update the push token of the customer (Firebase token)
     *  - update the guId (GeoUniq device id) of the customer
     */
    @TargetApi(Build.VERSION_CODES.JELLY_BEAN_MR2)
    public void initC4w();

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 successfully
     * @param onError - invoked if exception occurred
     *
     */
    @TargetApi(Build.VERSION_CODES.JELLY_BEAN_MR2)
    public Future<CustomerCreateResponse> setupCustomer(Callback<CustomerCreateResponse> 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.

It deletes the WPA2 enterprise profile installed by the app.

Cloud4WiSDKWiFi mobileSDK;
mobileSDK.deleteWPA2EnterpriseProfile();

Add or update Passpoint Wi-Fi profile

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

/**
     * Add or update HotSpot 2.0 Wi-Fi profile
     *
     * @param username - authorization user name
     * @param password - authorization password
     *
     * @throws Exception - exception thrown if profile cannot be created or updated
     */
    @TargetApi(Build.VERSION_CODES.O)
    public Future<Boolean> createPasspointProfile(String username, String password,
                                                  Callback<Boolean> onSuccess,
                                                  Callback<MobileSDKException> onError) {
        return asyncExecutor.execute(() -> wiFiProfileService.createPasspointProfile(username, password), onSuccess, onError);
    }

if(cloud4wiSDK.isPasspointSupported()) {
    cloud4wiSDK.createPasspointProfile(username, password)
} else {
    // Android 10- and other devices that don't support Passpoint
    cloud4wiSDK.createWPA2EnterpriseProfile(username, password)
}

It deletes the Passpoint profile installed by the app.

Cloud4WiSDKWiFi mobileSDK;
mobileSDK.deletePasspointProfile();

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 User Experience

    /**
     * Add or update WPA2-Enterprise Wi-Fi profile
     *
     * @param username - authorization user name
     * @param password - authorization password
     *
     * @throws Exception - exception thrown if profile cannot be created or updated
     */
    @TargetApi(Build.VERSION_CODES.JELLY_BEAN_MR2)
    public Future<WPA2EnterpriseProfile> createWPA2EnterpriseProfile(String username, String password,
                                                             Callback<WPA2EnterpriseProfile> onSuccess,
                                                             Callback<MobileSDKException> onError);

List of methods

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

Update the customer's attributes

The attributes:

username, password, lock

are not available in customer update.

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

Return the customerId saved during the create customer

Check if Passpoint feature is supported on current device.

Retrieve customer profile by username/password

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.