@meduxspeedchecker/sdk-agent-cordova

Cordova plugin for Medux SDK Agent

Integrated solution with Medux SDK Agent for Cordova (Apache Cordova) and Ionic Cordova applications

Release notes

v1.0.44

iOS

• Use average ping for server selection.

check out the Release history for more details

Table of contents:

• Installing
• How to use
• Updating
• Uninstalling

Supported platforms

• Android
• iOS

Requirements

• Permissions:

  • ACCESS_COARSE_LOCATION
  • ACCESS_FINE_LOCATION
  • ACCESS_BACKGROUND_LOCATION

• Platform-specific requirements:

  • Android:
    • minSDK version: 22 or higher
    • Cordova Android version: android 11.x of higher
  • iOS:
    • Xcode 13.3.1 or later
    • Development Target 11.0 or later

Installing

1. Create a Cordova project

cordova create [project folder] app.medux.demo [name]

2. Go to project directory

cd [project folder]

3. Add your platform

cordova platform add android@11.0.0

cordova platform add ios

4. Add this configuration in the config.xml file of your Cordova project

• Android:

<platform name="android">
        <config-file target="res/xml/config.xml" parent="/*">
            <feature name="SpeedCheckerPlugin" >
                <param name="android-package" value="org.apache.cordova.speedchecker.SpeedCheckerPlugin"/>
            </feature>
        </config-file>
        <source-file src="platforms/android/app/src/main/java/org/apache/cordova/speedchecker/SpeedCheckerPlugin.java" target-dir="src/org/apache/cordova/speedchecker" />
    </platform>
    <preference name="android-minSdkVersion" value="22" />
    <preference name="android-targetSdkVersion" value="31" />
    <preference name="android-compileSdkVersion" value="31" />
    
    // set to true to allow plugin receive latest SDK version, or set to false to keep the SDK version the same all the time
    <preference name="isAutoSdkUpdateEnabled" value="false" />

• iOS

<!--Location permission keys-->
<config-file target="*-Info.plist" parent="NSLocationAlwaysAndWhenInUseUsageDescription">
    <string>your custom text here</string>
</config-file>
<config-file target="*-Info.plist" parent="NSLocationAlwaysUsageDescription">
    <string>your custom text here</string>
</config-file>
<config-file target="*-Info.plist" parent="NSLocationWhenInUseUsageDescription">
    <string>your custom text here</string>
</config-file>

<!--Background modes key-->
<config-file target="*-Info.plist" parent="UIBackgroundModes">
    <array>
        <string>location</string>
        <string>processing</string>
    </array>
</config-file>

<!--BGTaskSchedulerPermittedIdentifiers key-->
<config-file target="*-Info.plist" parent="BGTaskSchedulerPermittedIdentifiers">
    <array>
        <string>com.speedchecker.bgtests</string>
    </array>
</config-file>

<!--Background test setup keys-->
<config-file target="*-Info.plist" parent="SpeedCheckerBackgroundTestEnabledOnInit">
    <true/>
</config-file>

5. Install the plugin from npm repository

npm i @meduxspeedchecker/sdk-agent-cordova

6. Add the plugin to your Cordova project

cordova plugin add @meduxspeedchecker/sdk-agent-cordova

7. Prepare the project

cordova prepare android
cordova prepare ios

8. Run or emulate the project

cordova run android
cordova run ios

cordova emulate android
cordova emulate ios

How to use

Use the following (sample) functions in index.js:

To start speed test by event (e.g. button click):

Plugin includes "startTest" function, which has following signature:

startTest = function (
    onFinished,
    onError,
    onReceivedServers = function (obj) { },
    onPingStarted = function () { },
    onPingFinished = function (obj) { },
    onDownloadStarted = function () { },
    onDownloadProgress = function (obj) { },
    onDownloadFinished = function (obj) { },
    onUploadStarted = function () { },
    onUploadProgress = function (obj) { },
    onUploadFinished = function (obj) { },
) {...}

You need to implement these functions in index.js, similar to these sample functions startSpeedTest() and setStatus() below:

function startSpeedTest() {

    setStatus("Test started");
    SpeedCheckerPlugin.startTest(
        // onFinished
        function(obj) {
            console.log(JSON.stringify(obj));
            setStatus('Test finished <br>ping: ' + obj.ping.toFixed() + ' ms<br> packetLoss: ' + obj.packetLoss.toFixed() +  '<br>download speed: ' + obj.downloadSpeed.toFixed(2) + ' Mbps' + '<br>upload speed: ' + obj.uploadSpeed.toFixed(2) + ' Mbps<br> jitter: ' + obj.jitter + '<br>connectionType: ' + obj.connectionType + '<br>server: ' + obj.server + '<br>ip: ' + obj.ipAddress + '<br>isp: ' + obj.ispName + '<br>timestamp: ' + obj.timestamp);
        },
        //onError
        function(err) {
            console.log(err);
            setStatus('error code: ' + err.code);
        },
        //onReceivedServers
        function(obj) {
            console.log(JSON.stringify(obj));
            setStatus('Received servers');
        },
        //onPingStarted
        function() {
            console.log('Ping started');
            setStatus('Ping started');
        },
        //onPingFinished
        function(obj) {
            console.log(JSON.stringify(obj));
            setStatus('Ping: ' + obj.ping.toFixed() + ' ms');
        },
        //onDownloadStarted
        function() {
            console.log('Download started');
            setStatus('Download started');
        },
        //onDownloadProgress
        function(obj) {
            console.log(JSON.stringify(obj));
            setStatus('Download progress: ' + obj.progress.toFixed(0) + ' %' + '<br>speed: ' + obj.downloadSpeed.toFixed(2) + ' Mbps');
        },
        //onDownloadFinished
        function(obj) {
            console.log(JSON.stringify(obj));
            setStatus('Download speed: ' + obj.downloadSpeed.toFixed(2) + ' Mbps');
        },
        //onUploadStarted
        function() {
            console.log('Upload started');
            setStatus('Upload started');
        },
        //onUploadProgress
        function(obj) {
            console.log(JSON.stringify(obj));
            setStatus('Upload progress: ' + obj.progress.toFixed(0) + ' %' + '<br>speed: ' + obj.uploadSpeed.toFixed(2) + ' Mbps');
        },
        //onUploadFinished
        function(obj) {
            console.log(JSON.stringify(obj));
            setStatus('Upload speed: ' + obj.uploadSpeed.toFixed(2) + ' Mbps');
        }
    )
}

function setStatus(text) {
    document.getElementById("log").innerHTML = text;
}

To enable/disable background network test:

function setBackgroundNetworkTesting(isEnabled) {
    SpeedCheckerPlugin.setBackgroundNetworkTesting(
        isEnabled,
        function(err) {
            console.log(err);
        }
    )
}

To receive background network test status:

function getBackgroundNetworkTestingEnabled() {
    SpeedCheckerPlugin.getBackgroundNetworkTestingEnabled(
        function(enabled) {
            console.log('Background tests enabled: ' + enabled);
        },
        function(err) {
            console.log(err);
        }
    )
}

To set/get/remove MSISDN value:

function getMSISDN() {
    SpeedCheckerPlugin.getMSISDN(
        function(msisdn) {
            console.log('Current MSISDN is ' + msisdn);
        },
        function(err) {
            console.log(err);
        }
    )
}

function setMSISDN(value) {
    SpeedCheckerPlugin.setMSISDN(
        value,
        function(err) {
            console.log(err);
        }
    )
}

function removeMSISDN() {
    setMSISDN(null);
}

To set/get/remove UserID value:

function getUserID() {
    SpeedCheckerPlugin.getUserID(
        function(userID) {
            console.log('Current UserID is ' + userID);
        },
        function(err) {
            console.log(err);
        }
    )
}

function setUserID(value) {
    SpeedCheckerPlugin.setUserID(
        value,
        function(err) {
            console.log(err);
        }
    )
}

function removeUserID() {
    setUserID(null);
}

To get DeviceUniqueID value:

function getDeviceUniqueID() {
    SpeedCheckerPlugin.getUniqueID(
        function(uniqueID) {
            console.log('Current Unique deviceID is ' + uniqueID);
        },
        function(err) {
            console.log(err);
        }
    )
}

Updating

To update the plugin, install it again from npm repository with the following commands

npm i @meduxspeedchecker/sdk-agent-cordova
cordova plugin add @meduxspeedchecker/sdk-agent-cordova

To check all installed plugins and their current version in your project, run the following commands

cordova plugin list

Uninstalling

To uninstall the plugin, run the following commands

npm uninstall @meduxspeedchecker/sdk-agent-cordova
cordova plugin remove sdk-agent-cordova