Fastah Network Kit API - Add network intelligence to your app or game (4G LTE, WiFi and 3G)

Introduction

Fastah Network Kit provides an Android library to carry out fine grained network quality estimation. This is useful for apps that want to adapt their user experience and behaviour in response to varying network conditions on the 4G <-> 3G <-> 2G <-> WiFi scale. More specfically, latency and congestion are measured using a global fleet of low latency servers.

In addition to the network quality (QoS) API documented below for Android, a prediction API that uses geo-location and time of day to give a probability of network failure is being planned.

Who is this for?

This API is for apps that want to estimate Quality of Service (QoS) of a cellular or WiFi network in near real time. Paired with an application-specific behaviour, it can be used to guard critical points in the UX of an app, so that when the user moves to a suburb or is in a congested area: the experience does not degrade, monetary transactions do not fail, and more.

When smartphone users pays for 3G or 4G service, the delivered quality of service to the smartphone may still be poor:high latency or high packet losses are particularly rife in emerging markets.

Image of state of mobile internet connectivity

(Image courtesy Facebook F8 conference)

Example behaviours for an Uber-like on-demand transportation app might be:

  • On network degradation scenarios save transaction data such as end trip, start trip for later synchronization to Uber servers.
  • On network improvement scenarios pre-load locations based on user’s past behaviours.
  • Predict dead zones by time-of-day and user location, there by pre-caching mapping data for the Uber Partner (Driver) application.

For a Netflix or SoundCloud like multimedia streaming service:

  • Dynamic switching of the streaming bitrates depending on latencies.
  • Anticipating and communicating streaming outage to the user in the app, pre-emptively.
  • Pre-loading streams which high performance network is available.

In an Amazon.com style of commerce and catalog application:

  • As the user browses successive screens in a catalog, fetch high-res or low-res images or media based on realtime network conditions.
  • Protect sales transaction flow and UX by predicting network failures and preemptively caching data.

Comparison


Android OS Facebook Network Connection Class Fastah API
Sensing Type - Passive Active
Accuracy Very Low Moderate High
Low Latency Servers - App hosting dependent Global Network
Download bandwidth - Yes Yes
Upload bandwidth - - Yes

What it contains

  • City level visualizations of your app users network performance. Mobile internet speed map

Integration

  • Add dependencies to app/build.gradle
    android {
        repositories {
            // Release repository for Fastah Network Kit library
            maven { url 'http://maven.getfastah.com/libs-release' }
        }
    }

    dependencies {
        // The core Fastah Network Kit library
        compile 'com.getfastah.networkkit:networkkit-android-core:1.2.+'
    }
  • Add permissions to app/src/main/AndroidManifest.xml
        <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
        <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />


        <!-- The following permissions are automatically added by the Fastah Network Kit library manifest file.
        All are PROTECTION_NORMAL permissions, as definied by Android https://developer.android.com/guide/topics/security/normal-permissions.html
        -->
        <!--uses-permission android:name="android.permission.INTERNET" /-->
        <!--uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /-->
        <!--uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /-->
        <!--uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" /-->
  • Configure your Fastah Network Kit Application Name and Application Key in app/src/main/AndroidManifest.xml
        <application>
                <!-- Replace the value below with the application name (e.g com.product.android) associated with your Fastah for Android key -->
                <meta-data android:name="com.getfastah.networkkit.MeasureConfig.ApplicationName"
                android:value="com.example.www" />

                <!-- Replace the value below with the Fastah for Android key provided to you. Note that the key starts with an fnk. prefix -->
                <meta-data android:name="com.getfastah.networkkit.MeasureConfig.ApplicationKey"
                android:value="fnk.abcXYZdef==" />

                <!-- Optional: Interval duration in seconds after which network performance is automatically profiled using Android's background job scheduler (default is -1 or OFF) -->
                <meta-data android:name="com.getfastah.networkkit.MeasureConfig.Telemetry.Frequency" android:value="600" />
        </application>

Once the Application Name and Application Key are configured you are good to go with the auto scheduled measurements that run every 20 minutes. If you need manual control over the measurements, then please proceed to the advanced integration section.

Advanced Integration

Initialize

Call the init method once in the onCreate method of your Activity/Application.

MeasureManager.getInstance().init(this);

Implement Listener Callback

Instantiate a listener object which gets notified when new measurement samples are available.

MeasureManager.MeasurementCompletedListener mListener;
mListener = new MeasureManager.MeasurementCompletedListener() {
    @Override
    public void onMeasurementComplete(MeasureSample sample) {
        // The sample object holds the measurement results.
        }
    };

Register Callback

Register the above mentioned object with the MeasureManager.

MeasureManager.getInstance().register(mListener);

Start measurement

Call the following to run one network test. The onMeasurementComplete method will be invoked when the test completes.

MeasureManager.getInstance().measureOnce(ctx);

Here ctx is a android.content.Context

Optional: Tagging a sample

To label a sample with contextual information, such as user’s activity or application state, pass a short character sequence as a second argument.

MeasureManager.getInstance().measureOnce(ctx, tag);

De-register Callback

In your onDestroy stop listening for updates by calling the following method.

MeasureManager.getInstance().deregister(mListener);

FAQ

  • What are the dependencies of Fastah Network Kit library.

The Fastah Network Kit library depends on Google Play Location Services, Firebase Jobdispatcher and AWS Kinesis, which are implicitly satisfied while you compile the library.

Run ./gradlew app:dependencies to get a detailed dependency report, and look for the section after com.getfastah.networkkit:networkkit-android-core:.

  • Do I need to write proguard minification/obfuscation rules for Fastah Network Kit library.

Fastah Network Kit comes with a consumer proguard rule set, which will be automatically pulled in while you compile your app with minification enabled.

Support