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

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

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

- (NSString *) getCustomerId;

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.

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;

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;

Get the of applications interlinked with the current one

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

Close customer session

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

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

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

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

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

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

• First release

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. Retrieve App project API keys. 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 WiFi locations and access points in your Cloud4Wi account and configure your WiFi hardware with WPA2-Enterprise and/or Passpoint configuration.

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

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

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.

Passpoint profiles issued by Cloud4Wi are by default compatible with the OpenRoaming federation. Learn more about OpenRoaming.

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.

The automatic connection to WiFi allows Cloud4Wi to detect precisely all the customer visits and interactions and push the relevant Moments to your application systems via Webhooks or Connectors. The WiFi SDK cannot provide client-side events to the app since the detection and processing of location moments are actually performed server-side.

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.

You can design your own enrollment experience within your mobile app that includes the collection of consents.

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:

• Cisco Meraki

• Cisco WLC, Cisco Catalyst 9800

• Ruckus

• Aruba

• Extreme - Extremecloud IQ

• Fortinet (FortiGate)

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

• Cisco Meraki

• Cisco WLC

• Extreme - Extremecloud IQ

• Aruba - Wireless Controller

• Ruckus (Commscope) - Smart Zone

• Ubiquiti

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

List of methods

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.

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

Get the list of configured policies

Set SDK authentication parameters

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.

Check if Passpoint feature is supported on current device.

Return the customerId saved during the create customer

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.

Set SDK authentication parameters

How can I check if the app installed the WiFI Profile correctly?

The WiFi SDK provides a method to detect if a WiFi Profile is correctly installed in the device.

To manually check if the profile is installed on your iOS device, you can go to Settings > WiFi and click the "Edit" button on the top right corner. Profiles installed via WiFi SDK will be listed as a known network without a name, usually on top of the list. If you click on the info icon, you'll be able to see the username associated with the profile and find the matching user in your Cloud4Wi account.

Will the device connect automatically to WiFi upon completing the onboarding?

The answer depends on the OS and type of WiFi profile (WPA2 Enterprise or Passpoint).

When you install a WAP2 Enterprise profile in iOS, the device will attempt to connect immediatly to the WiFi network identified by the SSID written in the WiFi profile.

When you install a Passpoint profile in iOS, if you are already connected to a WiFi network, the device won't change the WiFi network it is associated with. If the device is not currently associated to WiFi while installing the profile, the device will take some time to do the match between availalbe network and the WiFi profile just installed and eventually it might automatically connect. The time it takes, however, it is not deterministic and can very from immediatly up to a few minutes.

When you install a WAP2 Enterprise profile in Android, it depends on the Android version. Starting from Android 11, while installing the profile, the device will attempt to connect to WiFi. If the device was connected to another WiFi network while installing the WiFi, it will attempt to switch to the new WiFi if under coverage. In Android 10 and older, once the WiFi profile is installed, the device will prompt a silent notification inviting the user to connect to the WiFi network the first time the network is detected by the device and every time until the user either accept or decline the notification.

Will enabled devices connect automatically to the WiFi upon arrival at a location?

Yes, for both Passpoint and WPA2 Enterprise, the device will attempt to connect automatically to the WiFi network as soon as the device discovers the WIFi network and matches it with the WiFi profile installed in the device.

It might take some time before the device automatically connect after arriving under coverage. The reason of the delay is due to multiple factors:

1. The device refreshes the list of available network on certain intervals an

2. The device must match the available WiFi networks against the WiFi profile installed in the phone

There are also dynamics related to the power optimization mechanism of devices that could reduce the frequency of such operations while the phone is in standby mode.

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.

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
 */
- (void) checkIfCustomerExists: (CustomerQuery *) query
                     onSuccess: (void (^)(BOOL)) onSuccess
                       onError: (void (^)(NSError *error)) onError;

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

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

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.

Update a Customer metadata

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

Get the list of configured policies over API

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

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

• terms of use ("termsOfUse")

• privacy policy ("privacy")

• marketing ("marketing")

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

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

Returns list of created WPA2EnterpriseProfiles

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

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

The method GeoUniq.getInstance(context).resetDeviceId() reset the Device Id by invoking a new device registration.

Initialize Users

In order to track geofencing events, you need to initialize a user in your Cloud4Wi account.

Once both the WiFi and Location SDKs are installed you can use the following snippet to initialize the customer in Cloud4Wi as soon the deviceId is assigned to the phone. This function will initialize an anonymous user without any additional attribute or personal data associated.

Cloud4WiSDKWiFi mobileSDK = new Cloud4WiSDKWiFi(getApplicationContext());
GeoUniq mGeoUniq = GeoUniq.getInstance(this);
            mGeoUniq.setDeviceIdListener(new GeoUniq.IDeviceIdListener() {
                @Override
                public void onDeviceIdAvailable(String deviceId) {
                    mobileSDK.setupCustomer(
                            customerCreateResponse -> {
                                Log.d("", customerCreateResponse.toString());
                            },
                            e -> {
                                Log.d("", e.getMessage());
                            });
                }
            });

In the alternative, you can use the native WiFi SDK methods to initialize a customer.

The method GeoUniq.sharedInstance().getDeviceId() return the id relative to the device if it has been registered, nil otherwise.

The method GeoUniq.sharedInstance().resetDeviceId() reset the Device Id by invoking a new device registration.

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.

Get Work Location

Allows to get the work location calculated for this device. Return a WorkLocation object if work location is available or null otherwise.

Register Work Location listener

Sets the listener class that will receive updates when the work location changes. The listener must be impIement the IWorkLocationListener interface.

Unregister Work Location listener

Remove work location updates for the listener.

The locations of interest, such as home and work locations, are places identified based on the visits detected by the SDK.

Add or update WPA2-Enterprise Wi-Fi profile

Examples

Add or update Passpoint Wi-Fi profile

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

Examples

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:

1.7.0

• Track customers profile status

1.6.0

• fix getCreatedWPA2EnterpriseProfiles and getCreatedPasspointProfiles

• introduced deleteWPA2EnterpriseProfile

1.5.0

• Added deletePasspointProfile method

• In the logout are removed the Passpoint profile installed

1.4.0

• Added method updateCustomer

• Added DEBUG_MODE

• Fix support iOs simulator for Apple Silicon architecture

1.3.1

• fix date format in 'lastSeen' field

1.3.0

• Passpoint support

1.2.0

• New create customer function with deduplication on specific parameter

• Extended support of custom policies

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

Migration guide

Customer Create

The signature of the method

has been replaced by

To create a customer without deduplication:

Get list policies

The signature of the method getListOfPolicies

has been replaced by

1.1.0

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

• WPA2-Enterprise profile creation support

• Integration with Location SDK

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

For the SDK to be able to accomplish its main task, that is tracking the device position, the following requirements must be met:

• The foreground location permission must be granted to the app

• The background location permission must be granted to the app, if it meets the Google Play Store policies for background location

• The location functionality must be enabled on the device

• Google Play Services must be installed on the device (almost always met)

The SDK provides a simple way for checking all the requirements and optionally solve the related issues. Solving an issue generally implies showing an alert to the User. Depending on the specific requirement, a different alert will be shown.

The example below shows hot to check for all requirements and solve them. In the example, the check is performed on the onStart() method of the main activity

The SDK can be enabled and disabled at runtime. To make GeoUniq SDK start, you need to enable it by calling the method GeoUniq.enable() at least once.

You might do that into the main activity of your app, as in the example below.

Once enabled, the SDK will not stop until you disable it by calling GeoUniq.disable(). That is, it will keep performing automatic operations, such as tracking the device position, even after a device reboot or an update of the app. Disabling the SDK at runtime is useful if you want the SDK to stop completely. For example, you could remotely control a configuration parameter of your app to stop the SDK for all or some of your installations.

The locations of interest, such as home and work locations, are places identified based on the visits detected by the SDK.

Installation

CocoaPods

Swift Package Manager

Repository: https://github.com/Cloud4Wi-Create/iOS-LocationSDK-SwiftPackage

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("[email protected]") <- outerIdentity
Optional("YYYYYZZZXXX1") <- username
Optional(["get.securewifi.io"]) <- trustedServerNames
Optional("com.cloud4wi.c4wiapp") <- installedBy
Optional(2022-07-08 08:08:44 +0000) <- installed

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

3.1.6 Release notes (03-02-2025)

Enhancements

• Update play-services-ads-identifier to 18.2.0

3.1.5 Release notes (24-06-2024)

Fixed

• Minor bug fix.

3.1.4 Release notes (18-06-2024)

Enhancements

• Added support to Android 14

Fixed

• Fixed proguard rule that prevent the obfuscation of client App.

• Removed the static permission ACTIVITY_RECOGNITION.

3.1.0 Release notes (07-02-2024)

Enhancements

• The SDK now support play-services-location library versions higher 20.0.x.

Fixed

• Fixed proguard rule that prevent the obfuscation of client App.

3.0.3 Release notes (05-09-2023)

Enhancements

• Added trigger geofence when enter for the first time

• Added API resetDeviceId()

• Now you can change the base API url declaring the meta data

  Copy

  com.geouniq.geo_api_base

3.0.2 Release notes (26-07-2023)

Fixed

• Removed fingerprint validation SDK side

3.0.1 Release notes (22-04-2022)

Fixed

• Fixed bug in the trigger manager that caused an error when updating the remote trigger list

3.0.0 Release notes (08-04-2022)

Enhancements

• Added engine that allow the SDK to identify "Locations Of Interest" as "Home Location" and "Work Location"

• Added engine that manage Triggers set by remote

As soon as the SDK starts for the first time, a Device ID is assigned to that specific installation of your app.

The Device ID assigned to an installation might change in case of rare events, for example if the local storage of the device gets erased.

The SDK provides two different ways to obtain the Device ID.

Getting the Device ID through a Device ID listener

The first method to obtain the Device ID is to set a IDeviceIdListener, as shown in the example below. When a listener is set, the SDK immediately returns the Device ID through the onDeviceIdAvailable() callback if the Device ID is already available. Otherwise, it will call the callback method as soon as the ID is obtained.

The best practice for an app that want to collect on a backend systems the Device ID assigned to each installation, is to set a IDeviceIdListener each time it starts. The mobile app would receive the Device ID each time and should always send it to the backend system. Then, the backend system should overwrite any previously stored value if the new received value is different.

Getting the Device ID by calling an explicit class method

The second way is to call the GeoUniq.getDeviceId() method. This method returns the value of the Device ID if it has already been obtained or null if the Device ID has not been obtained yet.

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.

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

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:

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

registered in AndroidManifest.xml

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'

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

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

Gradle Configuration

Open the file build.gradle file of the application module (not the main project) on Android Studio. Add the following lines to import geouniq url repository

Add the following dependency

Manifest Configuration

The library already declare the basic permissions that needs, if your app meets the Google Play Store policies for background location, make sure you've declared permission to access background location:

ProGuard Configuration

The library already contains its ProGuard configuration file, which will be merged with your application's during the build process.

Providing the Mobile Key

The Mobile Key generated for your app when you configured your project (see here) must be provided as a string resource with name "geouniq_mobile_key".

This can be done by putting the following line into the Gradle build script of your app (build.gradle file of your app module)

It could be convenient to set a different value for the debug and the relase build types.

Note that the certificates used for the two build types are generally different, and thus their SHA1 fingerprint will be different. For this reason, you should create two different Client Apps, one for the debug and one for the release build, each with its own fingerprint (see Project Configuration). A common solution is to create two different projects, one for test and one for production, and create an Android Client App on each project, using the debug fingerprint for the test project and the release fingerprint for the production project.

Initialize SDK

Before initializing the SDK, the below must be imported.

After import, add the below code under the Application class onCreate() method. The SDK must be enabled before calling any of the other SDK methods.

To start the tracking engine call enable method. You can do that into the didFinishLaunchingWithOptions method. It is possible to enable directly the tracking engine when the initialize method is called. Once enabled, the SDK will not stop until you disable it by calling GeoUniq.sharedInstance().disable() If the application does not have the permissions or has not yet requested them, the enable method will request them.

Update the customer's attributes

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

The attributes:

username, password, lock

are not available in customer update.

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

Examples

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

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

customer?.emailVerified=false

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

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

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

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