Mobile SDK - Android

Requirements:

  • ARR library: download the password-protected zip package below. The password will be communicated by Cloud4Wi during delivery
    Download AAR
  • JWT Token, shared by Cloud4Wi during delivery
  • 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 Android Mobile SDK 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.gradle


<resources>
    ...
    {JWT-value}
    {SSID-value}
</resources>

2. Configuration.

To provide your Cloud4Wi JWT token to the SDK you can specify it in your App properties (strings.xml).
Property name should be set to 'cloud4wi_hs2api_jwt_token'.
In the properties, you can also set required SSID, key: 'cloud4wi_hs2api_ssid'.

NOTE: These two properties may be specified in Runtime. See the API overview and examples for more info.

Example:


<resources>
    ...
    {JWT-value}
    {SSID-value}
</resources>

3. Framework API overview


  /**
     *
     * This method add or update WPA2Enterprise Wi-Fi profile.
     *
     * @param username - authorization user name.
     * @param password - authorization password.
     * @throws Exception - exception thrown if profile cannot be created or updated.
     */
    public void createWPA2EnterpriseProfile(String username, String password) throws Exception;


    /**
     * This method adds / updates Wi-Fi HotSpot 2.0 network configuration.
     *
     * NOTE : minimum required version of Android - 8.0 (Android Oreo, API version - 26)
     *
     * @param username - authorization user name.
     * @param password - authorization password
     * @throws Exception - exception thrown if profile cannot be created or updated.
     */
    public void createHotSpot20ProfileWithUsernameAndPassword(String username, String password) throws Exception;


    /**
     * Set JWT token to use for web API.
     *
     * NOTE: JWT may be set using this method in app properties (strings.xml, key: 'cloud4wi_hs2api_jwt_token')
     *
     * @param jwtToken - valid JWT token
     * @throws Exception if token is invalid
     */
    public void setJwtToken(String jwtToken) throws Exception;


    /**
     * Returns configured SSID value for WPA2-Enterprise profiles
     * @default Set from 'cloud4wi_hs2api_ssid' property (strings.xml)
     * @return Current SSID value
     */
    public String getSSID();

    /**
     * Specifies SSID value for WPA2-Enterprise profiles
     *
     * NOTE: SSID value may be set using this method in app properties (strings.xml, key: 'cloud4wi_hs2api_ssid')
     *
     * @param ssid
     */
    public void setSSID(String ssid);

    /**
     * Returns list of policies for target organization.
     *
     * @return list of policies.
     * @throws Exception if policies cannot be obtained.
     */
    public List<Policy> getListOfPolicies() throws Exception;

    /**
     * Create customer in the Volare platform (Guest User)
     *
     * @param customer user (Guest User) you want to create.
     * @return CustomerCreateResponse object which represents saved customer.
     * @throws Exception if new customer cannot be created.
     */
    public CustomerCreateResponse createCustomer(Customer customer) throws Exception;

    /**
     * Check customer login/password credentials over API.
     *
     * @param username - customer login.
     * @param password - customer password
     * @throws Exception - exception thrown if error occured during API check.
     */
    public boolean checkCredentials(String username, String password) throws Exception;
    

Required permissions:

AndroidManifest of this library requires the following permissions:


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

4. Code examples:

In the following code example, we will create a new customer and then install the WPA2-Enterprise Wi-Fi profile on an Android phone. After that when the customer will be in the range of a Wi-Fi network with matching SSID - his device will connect automatically.

This example represents the following use-case.

  1. MobileSDK configuration. Setting of JWT and Wi-Fi SSID values.
  2. Read list of organization policies from API.
  3. Creating new customer in API.
  4. Verifying customer credentials in API.
  5. Creating the WPA2-Enterprise Wi-Fi profile on the Android device for test user to connect to test SSID.


HotSpot20SDKFramework mobileSDK = new HotSpot20SDKFramework(getApplicationContext());

        /*
         * Valid JWT Token needs to be provided for MobileSDK in order to integrate with Web API
         * JWT Token could be specified in properties (strings.xml) or at runtime as in the given example
         */
        try {

            mobileSDK.setJwtToken(JWT_TOKEN);

            Log.e(TAG,"JWT successfully set.");

        } catch (Exception e) {
            Log.e(TAG,"Cannot set JWT", e);
            return;
        }

        /*
         * Setting SSID for Wi-Fi profiles
         * Created WPA2-Enterprise profiles will connect to specified SSID automatically when in range
         */
        mobileSDK.setSSID("Mobile_SDK_Test");

        /*
         * To register new customer we need to obtain required polices from API Server
         */
        List<Policy> policies = new ArrayList<>();
        try {

            policies = mobileSDK.getListOfPolicies();

            Log.i(TAG, "Got policies. Num = " + policies.size());

        } catch (Exception e) {
            Log.e(TAG, "Cannot get policies: ", e);
            return;
        }

        Customer customer = new Customer();
        customer.setUsername("test_cutomer@test.com");
        customer.setFirstname("Test");
        customer.setLastname("Customer");
        customer.setPassword("secure_password");
        customer.setEmail(customer.getUsername());

        /*
         * In order to register new customer all polices requested by API Server should be accepted
         */
        List<ApprovedPolicy> approvedPolicies = new ArrayList<>();
         for (Policy policy : policies) {
             ApprovedPolicy approvedPolicy = new ApprovedPolicy();
             approvedPolicy.setId(policy.getId());
             approvedPolicy.setValue(true);

             approvedPolicies.add(approvedPolicy);
         }

         customer.setPolicies(approvedPolicies);

        /*
         * Call Server API to create new customer
         */
        try {

            CustomerCreateResponse customerCreateResponse = mobileSDK.createCustomer(customer);

            Log.i(TAG, "Customer successfully created.");

         } catch (Exception e) {
            Log.e(TAG, "Cannot create customer: ", e);
            return;
         }

        /*
         * Assure new customer has been successfully created via Server API by checking newly created customer's credentials
         * This step is OPTIONAL
         */
        try {

            mobileSDK.checkCredentials(customer.getUsername(), customer.getPassword());

            Log.i(TAG, "Credentials approved.");

        } catch (Exception e) {
            Log.e(TAG, "Cannot approve credentials: ", e);
            return;
        }

        /*
         * Here we are calling Android API to create WPA2-Enterprise Wi-Fi Profile for recently created new customer
         */
        try {

            mobileSDK.createWPA2EnterpriseProfile(customer.getUsername(), customer.getPassword());

            Log.i(TAG, "Wi-Fi profile successfully created.");

        } catch (Exception e) {
            Log.e(TAG, "Failed to create Wi-Fi profile: ", e);
        }