wifix-scan-coreplugin

Wifix Scan CorePlugin

The Wifix Scan CorePlugin is a Cordova plugin that provides essential functionality for scanning Wi-Fi networks.

Installation

To install the Wifix Scan CorePlugin in your Cordova project, use the following command:

cordova plugin add wifix-scan-coreplugin

Demo

you can find a demo ionic cordova app using this library here:

Sample App - wifix-library-ionic-cordova

Configuration

Android

No special configurations needs to be done, just ensure that these permissions are granted in AndroidManifest.xml:

  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  <uses-permission android:name="android.permission.WRITE_SETTINGS" tools:ignore="ProtectedPermissions" />
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  <uses-feature android:name="android.hardware.location.gps" />
  <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
  <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
  <uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
  <uses-permission android:name="android.permission.CAMERA" />
  <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_COARSE_LOCATION" />

iOS

In your xcode project you need to:

Add entitlements to you current Development Team / Provisioning Profile / developer apple Account

You will need to add these entitlements so that the current access for wifi information is allowed, otherwise it will fail to fetch:

• Access Wi-Fi Information
• Hotspot
• Network Extensions

You can add these entitlements / capabilities directly to your xcode project on Signing & capabilities or by adding these entries to your config.xml cordova project:

    <config-file parent="com.apple.developer.networking.HotspotConfiguration"
      target="*/Entitlements-Debug.plist">
      <true />
    </config-file>
    <config-file parent="com.apple.developer.networking.HotspotConfiguration"
      target="*/Entitlements-Release.plist">
      <true />
    </config-file>
    <config-file parent="com.apple.developer.networking.networkextension"
      target="*/Entitlements-Debug.plist">
      <array />
    </config-file>
    <config-file parent="com.apple.developer.networking.networkextension"
      target="*/Entitlements-Release.plist">
      <array />
    </config-file>
    <config-file parent="com.apple.developer.networking.wifi-info"
      target="*/Entitlements-Debug.plist">
      <true />
    </config-file>
    <config-file parent="com.apple.developer.networking.wifi-info"
      target="*/Entitlements-Release.plist">
      <true />
    </config-file>

Known Issues

Android

iOS

Missing features

Currently, due to Apple restrictions on Wifi Access Information and ICMP restrictions, the following features ARE NOT available in iOS:

• Nearby Network (Redes Cercanas)

SDK does not contain 'libarclite' at the path '/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/arc/libarclite_iphoneos.a'; try increasing the minimum deployment target

This issue is related to the FastSocket deployment target being set to 8.0. You can resolve this by doing

pod install

In the root folder of your cordova/ ionic project.

Example Usage

// Create an instance of the Plugin
const wifix = new window.cordova.plugins.WifixScan();

wifix.doQuickScan(
  (supportManager) => {
    console.log("===> The scan was succesful");
    console.log(
      `Scan details and support provided via supportManager: ${supportManager}`
    );

    let testResult = await this.supportManager.runWifiSignalTest();
    console.log(`Result from testing wifi signal: ${testResult}`)
  },
  (error) => {
    console.log("XXX> error from ");
    console.log(error);
  },
  "1234567890",
  "myapikey"
);

API Definition

WifixScan Class

The WifixScan class encapsulates the public API for the Wifix plugin. It is responsible for handling scan requests and executing the required workflow for them.

Constructor

constructor(baseURL: string = WifixConstants.DEFAULT_ISP_URL)

• Description: Creates an instance of the WifixScan class.
• Parameters:
  • baseURL (optional): The base URL for scan HTTP requests. Defaults to the default ISP URL specified in WifixConstants.

Properties

baseURL: string

• Description: The base URL for scan HTTP requests.
• Default Value: WifixConstants.DEFAULT_ISP_URL

doFullScan Method

The doFullScan method is a crucial function within the WifixScan class, designed for initiating a full scan workflow in your Wifix npm plugin library. This method performs various checks, gathers information, and provides callbacks for handling success and errors.

Method Signature

/**
 * Initiates a full scan.
 *
 * @param {(supportManager: ScanSupportManager) => void} successCallback - A callback function that receives an instance of the support manager for further scan testing.
 * @param {(error: Error) => void} errorCallback - A callback function to handle errors during the scan process.
 * @param {string} userContract - The user's contract information.
 * @param {string} apiKey - The API key for using the Wifix plugin (optional, defaults to an empty string).
 */
doFullScan(successCallback, errorCallback, userContract, apiKey = '') {}

Parameters

• successCallback (Function): A callback function that receives an instance of the ScanSupportManager when the scan is succesful. This instance is crucial for further scan testing and exploration.

• errorCallback (Function): A callback function that receives an Error object in case any step of the scan process encounters an error.

• userContract (String): The user's contract information required for the scan.

• apiKey (String, NOT OPTIONAL): The API key used for the Wifix plugin. Should be provided, otherwise an Invalid Key Error will be thrown instead.

doQuickScan Method

The doQuickScan method initiates a Support (Quick) scan intended to provide assistance to the customer. This scan performs tests and provides a ScanSupportManager instance through the success callback for further scan testing.

Method Signature

/**
 * Initiates a Support (Quick) scan. This scan is intended to provide help to the customer by making tests with the `ScanSupportManager` instance provided on the callback.
 *
 * @param {(supportManager: ScanSupportManager) => void} successCallback - A callback function that has an instance of the support manager that can be used for further scan testing.
 * @param {(error: Error) => void} errorCallback - A callback function to handle an error if any step of the scan process fails.
 * @param {string} userContract - The user's contract information.
 * @param {string} apiKey - The API key to use for this plugin.
 */
doQuickScan(successCallback, errorCallback, userContract, apiKey) {}

Parameters

• successCallback (Function): A callback function that receives an instance of the ScanSupportManager when the scan is succesful. This instance is crucial for further scan testing and exploration.

• errorCallback (Function): A callback function that receives an Error object in case any step of the scan process encounters an error.

• userContract (String): The user's contract information required for the scan.

• apiKey (String, NOT OPTIONAL): The API key used for the Wifix plugin. Should be provided, otherwise an Invalid Key Error will be thrown instead.

ScanSupportManager Class

The ScanSupportManager class is responsible for handling various scan support features such as tests, capturing pictures, opening channels, and initiating video conferences. This instance is returned on a succesful scan in the callback function for both doFullScan or doQuickScan method.

Each method of this Scan Support Manager, except for those that perform other things like getCurrentScanData, takeScanPicture and startRemoteAssistance, returns a result object ScanSupportTestResult providing information about the successfulness of the test.

The definition of ScanSupportTestResult is the following:

{
  sucess: boolean, //Tells if the test or method executed was succesful or not
  message: string, // A message with information about the current test
  error: string, // If present, indicates the error ocurred during the test / method
}

getCurrentScanData Method

Gets the current scan info by returning an object with the following structure:

• host: url of the ISP http api.
• preffix: the preffix that tells the name of the current ISP.
• token: the token authorization for the ISP http API.
• scanCode: The code of the scan that is hosted by the current ISP API.
• wifiGateway: The ip address of the gateway that the app will use for remote support

Method Signature

 /**
   * returns the data for the current scan like scanCode, host of the current ISP api, wifiGateway and more.
   * @returns {ISPApiData} - the data of the current scan
   */
  getCurrentScanData () {

runWifiSignalTest Method

Runs the WiFi signal test and updates the remote scan information.

Method Signature

/**
 * Runs the WiFi signal test and updates the remote scan information.
 * @returns {ScanSupportTestResult} - The result of the test.
 */
async runWifiSignalTest() {
  return { success: true, message: "Wifi signal data updated successfully", error: null };
}

runCurrentWifiAndNearestWifiNetworksTest Method

Runs the current WiFi info and nearest WiFi networks test and updates the remote scan information.

Method Signature

/**
 * Runs the current WiFi info and nearest WiFi networks test and updates the remote scan information.
 * @returns {ScanSupportTestResult} - The result of the test.
 */
async runCurrentWifiAndNearestWifiNetworksTest() {
  return { success: true, message: "Wifi and nearest wifis data updated successfully", error: null };
}

runCurrentNetworkInfoAndDevicesConnectedTest Method

Runs the current network info and connected devices test and updates the remote scan information.

Method Signature

/**
 * Runs the current network info and connected devices test and updates the remote scan information.
 * @returns {ScanSupportTestResult} - The result of the test.
 */
async runCurrentNetworkInfoAndDevicesConnectedTest() {
  return { success: true, message: "Current network and connected devices data updated successfully", error: null };
}

runSpeedTest Method

Runs a speed test on the current WiFi network and updates the remote scan information.

Method Signature

/**
 * Runs a speed test on the current WiFi network and updates the remote scan information.
 * @returns {ScanSupportTestResult} - The result of the test.
 */
async runSpeedTest() {
  return { success: true, message: "Speed Test data updated successfully", error: null };
}

takeAndUploadPicture Method

Open the device camera to take a picture and send it to the server to update the proper scan data.

Method Signature

/**
 * takes a picture from camera and uploads it to the proper scan data
 * @returns {ScanSupportTestResult} - The result of taking the picture
 */
async takeAndUploadPicture () {}

startRemoteAssistance Method

This method makes a request to start a remote assistance, since this is a asynchronous request that can take long time. You will need to provide callbacks for each scenario of the remote assistance response:

Method Signature

/**
 *
 * @param {(result: RemoteAssistanceRequestResult) => void} onSuccess - callback when remote assitance request was succesful
 * @param {(error: string) => void} onError - callback when the remote assistance request was failed
 * @param {() => void | undefined} onClosed - optional callback when the remote assistance was remotely closed.
 * @returns
 */
startRemoteAssistance(onSuccess, onError, (onClosed = undefined));

Parameters

• onSuccess: This is a callback that will be called when the remote assistance request was succesful. When this callback is called an object with the following properties is passed:
  • remoteAssistanceURL: The url created to get through the network gateway
  • closeRemoteAssistance - A callback that is used to close the communication from remote assitance. YOU WILL NEED TO SAVE THIS CALLBACK IN A REFERENCE OR VARIABLE IN ORDER TO MAKE ABLE TO CLOSE THE REMOTE ASSISTANCE CHANNEL. YOU SHOULD CLOSE THE REQUEST WITH THIS CALLBACK AT YOUR OWN.
• onError: This is a callback that will be called when the remote assistance request gets an error and can't recover from it. When this callback is called a string providing information about the error is passed
• onClose: This is an optional callback (you can omit it or not pass it) that is called when the remote assitance channel is closed and no more information will be given from this request.

Considerations

• YOU HAVE TO CLOSE THE COMUNNICATION FROM THE REMOTE ASSISTANCE WHEN YOU ARE DONE WITH IT OR IT IS NO LONGER REQUIRED. THAT'S WHY THE closeRemoteAssistance callback is provided, so that you can close this communication. Not closing it could lead to unexpected behavior and errors.