Mobile SDK - Android

Requirements:

  • ARR library: download the password-protected zip package below. The password will be communicated by Cloud4Wi during delivery
    Download AAR
  • SSID name: note that the SSID is coded in the App, so make sure to know in advance the name of WiFi network you want to enable

Resources:

  • We prepared a getting started project that you can clone and import in your environment to get started. Contact our team to get access to the GIT.

1. Integration.

To integrate SDK library into your Android project copy provided AAR file to './app/libs'directory of your App.After that add following dependency to your project's build.gradlealong with 3 required dependencies as described below:


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(name:'cloud4wi-sdk-wifi-{lib-version}', ext:'aar')

}


2. Configuration.

In order to connect your application with Cloud4Wi API you need to provide SDK withclientKey/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 example below:


<resources>
    ...
    {client-key-value}
    {client-secret-value}
</resources>


Alternatively you can call 'setAPIAuthParams' on 'Cloud4WiSDKWiFi' object at Runtime.

In order to access local storage of Android the content provider need to be initialized.

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>


3. Framework API overview


/**
     * 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
     */
    public Future createWPA2EnterpriseProfile(String username, String password,
                                                             Callback onSuccess,
                                                             Callback onError);

    /**
     * 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
     */
    public Future createHotSpot20Profile(String username, String password,
                                       Callback onSuccess,
                                       Callback onError);
    /**
     * Create customer in the Volare platform (Guest User)
     *
     * @param customer - user (Guest User) you want to create
     * @param onSuccess - invoked if customer successfully created
     * @param onError - invoked if exception occurred
     *
     * @return future with CustomerCreateResponse object which represents saved customer
     */
    public Future createCustomer(Customer customer, Callback onSuccess, Callback onError);

    /**
     * Get customer info from API 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  result
     */
    public Future getCustomerInfo(String username, String password, Callback onSuccess, Callback onError);

    /**
     * Check if customer with provided via CustomerQuery properties already exists
     *
     * @param query -  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 checkIfCustomerExists(CustomerQuery query, Callback onSuccess, Callback onError);

    /**
     * Update API with customer metadata
     *
     * @param onSuccess - invoked if customer info update was proceeded without exceptions
     * @param onError - invoked if exception occurred
     */
    public void updateCustomerInfo(Callback onSuccess, Callback onError);

    /**
     * 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
     */
    public Future> getListOfPolicies(Callback> onSuccess, Callback onError);

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

    /**
     * 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 getCreatedWPA2EnterpriseProfiles() throws Exception;

    /**
     * For Android versions 10+ add interlinked applications
     * which incorporate C4WIMobileSDK to get installed WiFi network suggestions
     *
     * @param authorities in a form of List
     */
    public void addInterlinkedC4WIMobileSDKApplications(List authorities);

    /**
     * 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 getInterlinkedC4WIMobileSDKApplications();

    

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" />
    

4. Code examples:

In following code example we will create new customer in the API and then install WPA2-EnterpriseWi-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 -> {});

        mobileSDK.getCustomerInfo("test_cutomer_24@test.com", "secure_password",
        customerInfo -> {
            Log.i(TAG, "Customer Info result: " + customerInfo.getId());

            mobileSDK.updateCustomerInfo(
                    success -> {
                        Log.i(TAG, "Customer Info successfully updated");
                    },
                    e -> {
                        Log.e(TAG, "Customer Info update error: ", e);
                    });
        },
        e -> {
            Log.e(TAG, "Customer Info error: ", e);
        });

        CustomerQuery query = new CustomerQuery();
        query.setEmail("rrr@cloud4wi.com");
        mobileSDK.checkIfCustomerExists(query,
                customerExists -> {
                    if (customerExists) {
                        Log.i(TAG, "Customer EXISTS");
                    } else {
                        Log.i(TAG, "Customer DOES NOT EXIST");
                    }
                },
                e -> {
                    Log.e(TAG, "Customer exists error: ", 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());
                    runOnUiThread(new Runnable() {
                        @Override
                        public void run() {
                            logTextView.append("INFO: Got " + policies.size() + " policies." + "\n");
                            for (Policy p : policies) {
                                logTextView.append(p.getName() + "\n");
                            }
                        }
                    });

                    Customer customer = new Customer();
                    customer.setUsername("test_cutomer_25@test.com");
                    customer.setFirstName("Test");
                    customer.setLastName("Customer 2");
                    customer.setPassword("secure_password");
                    customer.setEmail(customer.getUsername());

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

                    /*
                     * Call Server API to create new customer
                     */
                    mobileSDK.createCustomer(customer,
                            customerCreateResponse -> {
                                Log.i(TAG, "Customer successfully created.");
                                runOnUiThread(new Runnable() {
                                    @Override
                                    public void run() {
                                        logTextView.append("INFO: Customer successfully created.\n");
                                    }
                                });

                                /*
                                 * Assure new customer has been successfully created via Server API by checking newly created customer's credentials
                                 * This step is OPTIONAL
                                 */
                                    mobileSDK.getCustomerInfo(customer.getUsername(), customer.getPassword(),
                                            customerInfo -> {
                                                runOnUiThread(new Runnable() {
                                                    @Override
                                                    public void run() {
                                                        Log.i(TAG, "Credentials approved.");
                                                        logTextView.append("INFO: Credentials approved.\n");

                                                        /*
                                                         * Here we are calling Android API to create WPA2-Enterprise Wi-Fi Profile for recently created new customer
                                                         */
                                                        mobileSDK.createWPA2EnterpriseProfile(customer.getUsername(), customer.getPassword(),
                                                                wpa2EnterpriseProfile -> {
                                                                    Log.i(TAG, "Wi-Fi profile successfully created.");
                                                                    runOnUiThread(new Runnable() {
                                                                        @Override
                                                                        public void run() {
                                                                            logTextView.append("INFO: Wi-Fi profile successfully created.\n");
                                                                        }
                                                                    });
                                                                },
                                                                e -> {
                                                                    Log.e(TAG, "Failed to create Wi-Fi profile: ", e);
                                                                    runOnUiThread(new Runnable() {
                                                                        @Override
                                                                        public void run() {
                                                                            logTextView.append("INFO: Failed to create Wi-Fi profile: " + e.getMessage() + "\n");
                                                                        }
                                                                    });
                                                                });
                                                    }
                                                });
                                            },
                                            e -> {
                                                Log.e(TAG, "Cannot approve credentials: ", e);
                                                runOnUiThread(new Runnable() {
                                                    @Override
                                                    public void run() {
                                                        logTextView.append("INFO: Cannot approve credentials - " + e.getMessage() + "\n");
                                                    }
                                                });
                                            }
                                    );
                            },
                            e -> {
                                Log.e(TAG, "Cannot create customer: ", e);
                                runOnUiThread(new Runnable() {
                                    @Override
                                    public void run() {
                                        logTextView.append("INFO: Cannot create customer - " + e.getMessage() + "\n");
                                    }
                                });
                            }
                    );
                },
                e -> {
                    Log.e(TAG, "Cannot get policies: " +  e.getMessage());
                    runOnUiThread(new Runnable() {
                        @Override
                        public void run() {
                            logTextView.append("INFO: Cannot get policies - " + e.getMessage() + "\n");
                        }
                    });
                }
        );

        

4. Additional features

Interlinking multiple applications on one device.

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

NOTE: 'multiprocess' and 'exported' parameter values show be set '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 interlinkedC4WIMobileSDKApplications = new ArrayList<>();
   interlinkedC4WIMobileSDKApplications.add("com.c4w.applicationtwo");
   mobileSDK.setInterlinkedC4WIMobileSDKApplications(interlinkedC4WIMobileSDKApplications);