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

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:

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

Add or update WPA2-Enterprise Wi-Fi profile

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

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

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

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.

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

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

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;

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

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

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.

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

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.

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

Get the list of configured policies

/**
 * Get the list of policies configured in the Cloud4Wi account
 *
 * @param onSuccess - invoked if policies list was successfully obtained
 * @param onError - invoked if exception occurred
 *
 */
- (void) getListOfPolicies: (void (^)(NSArray<Policy *> *policies)) onSuccess
                   onError: (void (^)(NSError *error)) onError;

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

NSString * ssid;
NSString * outerIdentity;
NSString * username;
NSArray <NSString *> * trustedServerNames;
NSString * installedBy;
NSDate * installed;

Example

var profiles: Array<WPA2EnterpriseProfile>
profiles = cloud4WiSDKWiFi.getCreatedWPA2EnterpriseProfiles()
var profile : WPA2EnterpriseProfile
profile = profiles[0]
print(profile.ssid)
print(profile.outerIdentity)
print(profile.username)
print(profile.trustedServerNames)
print(profile.installedBy)
print(profile.installed)

NSArray<WPA2EnterpriseProfile *> *profiles = [cloud4WiSDKWiFi getCreatedWPA2EnterpriseProfiles];
WPA2EnterpriseProfile* profile = [profiles firstObject];
NSLog(@"%@", profile.ssid);
NSLog(@"%@", profile.outerIdentity);
NSLog(@"%@", profile.username);
NSLog(@"%@", profile.trustedServerNames);
NSLog(@"%@", profile.installedBy);
NSLog(@"%@", profile.installed);

output

Optional("securewifi.io") <- ssid
Optional("anonymous@get.securewifi.io") <- outerIdentity
Optional("YYYYYZZZXXX1") <- username
Optional(["get.securewifi.io"]) <- trustedServerNames
Optional("com.cloud4wi.c4wiapp") <- installedBy
Optional(2022-07-08 08:08:44 +0000) <- installed

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:

Initialize the SDK

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

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

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

- (NSString *) getCustomerId;

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;

Update a Customer metadata

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

List of methods

List of methods

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

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

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:

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

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

you can put it into didFinishLaunchingWithOptions for example

It deletes the WPA2 enterprise profile installed by the app.

Cloud4WiSDKWiFi mobileSDK;
mobileSDK.deleteWPA2EnterpriseProfile();

It deletes the Passpoint profile installed by the app.

Cloud4WiSDKWiFi mobileSDK;
mobileSDK.deletePasspointProfile();

Get the of applications interlinked with the current one

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

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;

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.

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

Add or update WPA2-Enterprise Wi-Fi profile

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.

Add or update Passpoint Wi-Fi profile

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

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.

    /**
     * Check if customer with provided via CustomerQuery properties already exists
     *
     * @param query - <CustomerQuery> object with at least one field initialized
     * @param onSuccess - invoked if `customer exists` call was proceeded without exceptions
     * @param onError - invoked if exception occurred
     * @return future with boolean result of `customer exists` result
     */
    public Future<Boolean> checkIfCustomerExists(CustomerQuery query, Callback<Boolean> onSuccess, Callback<MobileSDKException> onError);

Returns list of created Passpoint profiles

/**
     * Returns list of created Passpoint profiles
     *
     * @return List of PasspointConfiguration objects
     * @throws Exception
     */
    public List<PasspointConfiguration> getCreatedPasspointProfiles() throws Exception {
        return wiFiProfileService.getCreatedPasspointProfiles();
    }

Check if Passpoint feature is supported on current device.

    /**
     * Check if Passpoint feature is supported on current device.
     *
     */
    public boolean isPasspointSupported() {
        return wiFiProfileService.isPasspointSupported();
    }

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

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.

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

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.

List of application identifiers current interlinked with

/**
     * List of interlinked applications with C4WIMobileSDK incorporated
     *
     * @return List of interlinked applications which incorporate C4WIMobileSDK
     * to get installed WiFi network suggestions
     */
    @TargetApi(Build.VERSION_CODES.Q)
    public List<String> getInterlinkedC4WIMobileSDKApplications();

Close customer session

    /**
     * Close customer session (it removes the customerId saved during the create customer)
     * Removes any reference to the customer
     */
    @TargetApi(Build.VERSION_CODES.JELLY_BEAN_MR2)
    public void logout();

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

It deletes passpoint internet profiles and wpa2-enterprise installed in the device using createPasspointProfile.

Set SDK authentication parameters

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

Returns list of created WPA2EnterpriseProfiles

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.

Format

Policies

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

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

Update a Customer metadata

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

1.0.0

• First release

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 debugging add following record to your application's string.xml:

<resources>
    ...
    <bool name="com.cloud4wi.sdk.wifi.debug_mode">true</bool>
</resources>

Firebase Messaging token

Cloud4WiDSK searches for com.google.firebase.messaging.FirebaseMessaging class in classpath. If such a class is present it means SDK can call getToken() methods and therefore update push-token.

Your application needs to have MyFirebaseMessagingService

public class MyFirebaseMessagingService extends FirebaseMessagingService {
    public static String TAG = "MyFirebaseMessagingService";

    @Override
    public void onMessageReceived(@NonNull RemoteMessage remoteMessage) {
        Log.i(TAG, "Message data payload: " + remoteMessage.getData());
    }
}

registered in AndroidManifest.xml

<application

        ...

        <service
            android:name=".MyFirebaseMessagingService"
            android:exported="false">
            <intent-filter>
                <action android:name="com.google.firebase.MESSAGING_EVENT" />
            </intent-filter>
        </service>

</application>

and google-services.json file retrieved from https://console.firebase.google.com placed next to your project build.gradle

Interlinking multiple applications on one device.

Cloud4WiSDKWiFi allows you to share information about installed Wi-Fi profiles among applications on the same Android 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 the following in the 'application' section of your AndroidManifest.xml file:

NOTE: 'multiprocess' and 'exported' parameter values have to be set to 'true'

<application>

...

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

</application>

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

Cloud4WiSDKWiFi mobileSDK = new Cloud4WiSDKWiFi(getApplicationContext());
   
   List<String> interlinkedC4WIMobileSDKApplications = new ArrayList<>();
   interlinkedC4WIMobileSDKApplications.add("com.c4w.applicationtwo");
   mobileSDK.setInterlinkedC4WIMobileSDKApplications(interlinkedC4WIMobileSDKApplications);

The Cloud4Wi Location SDK (referenced as GeoUniq) abstracts away cross-platform differences between location services, allowing you to add geofencing and location tracking to your apps with just a few lines of code.

Quickstart

Want to get started quickly? Follow these four steps:

3. Configure geofencing. Create custom geofences

Projects and Client Apps

Device registration, Device IDs, and Device Base

When the Location SDK is integrated into a mobile app that has been configured as a Client App of a Project, every device on which the mobile app gets installed will be automatically registered by the Location SDK on Cloud4Wi.

Each device obtains a Device ID, generated automatically by Cloud4Wi, that can then be obtained by the mobile app.

The set of devices registered for all the Client Apps of a Project represents a unique Device Base for the Project, regardless of the Client App they belong to.

‍

Location SDK performances

The Location SDK is lightweight and minimizes the impact on the mobile OS performance, both in terms of battery consumption as well as access to location data services. ‍

Frameworks

The SDK doesn't impose any requirement on the experience to enroll users into the WiFi service. The two main functions (initializing a user and installing the WiFi profile) can be deployed contextually or at different moments.

The WiFi user can be initialized at any time, even in the background, for example:

• when a user signs up the first time for the app

• the first time the app is opened after installing the app update that includes the SDK

• at the moment the user explicitly makes some action for enabling the WiFi service

Once the WiFi user is initialized, the installation of the WiFi profile can be triggered by any user experiences, for example:

• sending a push notification to the user informing them about the new WiFi service

• with a banner in the home of the app

• with a link in a menu

Regardless of the user experience that triggers the WiFi profile installation, Cloud4Wi advises creating and showing a dedicated informative screen that explains to the user the benefits of the service before calling the method to install the WiFi profile. In fact, installing the WiFi profile will open a dialog of the OS (different by OS and version) that might be confusing for the user if not previously informed.

First-time mobile app users

For users who just downloaded the app and opened it for the first time, you can integrate the WiFi enrollment as part of your app onboarding or sign-up experience, if any.

As soon as the user sign-up/sign-in to your app, you can present the user a screen that invites him to enroll in the WiFi service. At that point, you can initialize the user in Cloud4Wi using the proper method and then invoke the method to install the WiFi profile.

Here is an example of onboarding experience in the Cloud4Wi demo application

Existing uses

For existing users with the app already installed, you should create an onboarding experience triggered by a call to action. For example, you can:

• send a push notification to the user informing them about the new WiFi service

• show a menu or a banner in the app

Below is an example of a user experience that includes a menu icon to prompt the user to enroll in the WiFi service, which then presents the user with an informative screen before installing the WiFi profile on the device.

Note that the WiFi activation process is required only once, so it is not advised to create static banners or menus that remain visible also after the WiFi service activation.

Operative System Alerts

The native OS alert that appears to the user to confirm the WiFi profile installation depends on the OS (iOS or Android), OS version, and, in the case of Android, eventually also on the smartphone vendor.

iPhone

Android 10

When the Profile is installed by the SDK, Android 10 doesn't prompt any immediate action. When a supported network is in range, Android triggers a silent notification that suggests the user to connect to a WiFi network.

Because the notification may appear with some delay after the profile installation, we advise instructing the user with a dedicated screen explaining the steps required to finalize the enrollment.

Android 11

In Android 11, as soon as the profile is installed, the device prompts an overlay on the current screen that immediately asks the user to accept to connect to suggested networks.

Prompts may vary by smartphone model.

‍

‍

What the users see once connected

When connecting to a WiFi network thanks to a Passpoint profile provisioned via mobile SDK, the user will see the device associated with the WiFi, but Android and iOS show this in a different way

On iOS, the user will see the name of the SSID followed by a second line reporting "Hidden Network".

On Android, the user will see the Friendly Operator Name instead of the SSID, followed by a second line reporting "Connected via <name of the mobile App>"

What the userss see once connected

Once the device connects automatically to the network thanks to a Passpoitn profile installed via the SDK, the user will see their device connected to the network.

iOS will show the name of the WiFi network (SSID) with a second line reporting "Hidden Network"

On Android devices, users will see the Friendly Operator Name instead of the SSID name, and a second line reporting "Connected via <name of the mobile app>"

Introduction

The plugin was developed with Flutter version 3.24.5, it contains a sample app that installs a WPA2 certificate. To perform a test it is necessary to enter correct keys. The integration and configuration include a first phase on the Flutter project and a second phase in the individual iOS and Android projects

Flutter installation

Run this command:

With Flutter:

This will add a line like this to your package's pubspec.yaml (and run an implicit flutter pub get):

Alternatively, your editor might support flutter pub get. Check the docs for your editor to learn more.

Import it

Now in your Dart code, you can use:

Android installation

Integration

To integrate SDK library into your Android project you need to add Cloud4Wi repository inside build.gradle

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

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:

Required permissions

AndroidManifest of this library requires following permissions

Keep the customer update - Init method

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

iOS installation

Required Capabilities

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

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: