Making a custom UI

If you don't like the UI provided by the template or the customization is too limited, you might want to make your own UI. This is possible and APIs are provided to develop a custom UI, however it requires pretty good knowledge of Android and Java.

To make a custom UI:

• Make a new project in Android Studio. The minimum SDK supported by the speedtest is API 15.
• Copy the com.fdossena.speedtest.core package from the template into the new project
• Add the android.permission.INTERNET permission to the manifest
• Start developing

Before we continue, we need to discuss the license: the com.fdossena.speeedtest.core package is licensed under a GNU LGPLv3 license; you are now using it as a library to develop your project so your project can use whatever license you want (even a proprietary one if you want), but any modification made to the files inside the com.fdossena.speedtest.core package MUST be made publicly available in source code form. You must also credit the original author in your app (Federico Dossena, https://fdossena.com).

The Speedtest class

The com.fdossena.speedtest.core provides a handy Speedtest class that you can use to implement your test.

Constructor

The first thing to do is create an instance of the Speedtest class:

Speedtest st = new Speedtest();

You might want to store this object in a variable in your activity.

Configuration

If you don't want to use the default settings, you need to load your configuration:

SpeedtestConfig config=new SpeedtestConfig();
... change some of the settings ...
st.setSpeedtestConfig(config);

The config class provides getters and setters for all the test settings mentioned in the Advanced configuration section. Anything that you don't explicitly change will be set to the default value.

The SpeedtestConfig class can also be instantiated from a JSON object, which is very convenient if you want to load the settings from a file.

Telemetry

If you want to use telemetry, you need to load your configuration:

TelemetryConfig telemetryConfig=new TelemetryConfig(
    telemetryLevel,
    server,
    path,
    shareURL
);
st.setTelemetryConfig(telemetryConfig);

These are the same settings mentioned in the Telemetry and results sharing section.

The TelemetryConfig class can also be instantiated from a JSON object, which is very convenient if you want to load the settings from a file.

Adding your test points

To run the test you need at least 1 test point. To add a test point, use

TestPoint p=new TestPoint(name,server,dlURL,ulURL,pingURL,getIpURL);
st.addTestPoint(p);

You can also add test points from an array, or from a JSON array, which is very convenient if you want to load the settings from a file:

TestPoint[] servers=new TestPoint[]{
    new TestPoint(name,server,dlURL,ulURL,pingURL,getIpURL),
    ...
};
st.addTestPoints(servers);

If you want to load the servers from an URL instead, use:

st.loadServerList(url)

Important: This function is blocking and must not be called from the UI thread.

These are the same settings mentioned in the Adding your test points section.

Server selection

To run the server selection process, use

st.selectServer(new Speedtest.ServerSelectedHandler(){
    @Override
    public void onServerSelected(TestPoint server){
        //do something
    }
});

The selection process is asynchronous. The onServerSelected method will be called at the end of process: server will either be the server with the lowest ping, or null if none of them were reachable.

To manually choose one of the servers, use

TestPoint p=new TestPoint(...);
st.setSelectedServer(p);

Note: selectServer can only be called once, and you cannot call it after using setSelectedServer!

Note: You cannot change the configuration, or add other test points after selecting a server!

Running the test

Finally, we can run the test:

    st.start(new Speedtest.SpeedtestHandler(){
        @Override
        public void onDownloadUpdate(double dl, double progress){
            //update your UI
        }
        public void onUploadUpdate(double ul, double progress){
            //update your UI
        }
        public void onPingJitterUpdate(double ping, double jitter, double progress){
            //update your UI
        }
        public void onIPInfoUpdate(String ipInfo){
            //update your UI
        }
        public void onTestIDReceived(String id){
            //update your UI
        }
        public void onEnd(){
            //test finished
        }
        public void onCriticalFailure(String err){
            //do something
        }
    });

The test is done asynchronously. During the test, the following callbacks will be called:

• onDownloadUpdate is called periodically during the download test to report the download speed. dl is the current speed in Mbps, progress is a number between 0 and 1 representing how close we are to the time limit
• onUploadUpdate is called periodically during the upload test to report the upload speed. ul is the current speed in Mbps, progress is a number between 0 and 1 representing how close we are to the time limit
• onPingJitterUpdate is called periodically during the ping+jitter test to report ping and jitter times. ping is the current ping, jitter is the current jitter, progress is a number between 0 and 1 representing how close we are to the time limit
• onIPInfoUpdate is called when the IP address and ISP information is received. ipInfo is a string combining this information
• onTestIDReceived is called at the end of the test when we receive an ID from the telemetry. id is a string containing the test ID that can be used to generate a share link
• onEnd is called at the end of the test
• onCriticalFailure is called if the test fails. err is a string containing details about the error

Note: if some functions are disabled (for instance, telemetry), the corresponding event will not be called.

After the test is over, the test can be ran again, with a different server if you want.

Aborting the test

The test can be aborted at any time using

st.abort();

Note: aborting the test is not instantaneous. This is done asynchronously. If the test is running, the onEnd event will be called.