Skip to content

Configuring the template

Jump to bottom
Federico Dossena edited this page Mar 9, 2020 · 5 revisions

Here's an overview of the structure of the template, configured with the default settings. Click to expand.

Overview of the template

Download the template

The first thing to do is download latest version of the template:

git clone https://github.com/librespeed/speedtest-android

Now you will have a directory containing the template project and some documentation. Open the Speedtest-Android project in Android Studio.

Setting the package name

The template's default package name is your.name.here.speedtest; this must be changed to allow distribution. Typically it's going to be something like com.yourdomain.speedtest.

  • Right click app and click Open Module settings
  • Go to Modules > app > Default config, change Application ID to your new package name and press Ok
  • Expand app and double click manifests
  • Update package="your.name.here.speedtest" with your new package name
  • Expand app > java > com > fdossena > speedtest > ui
  • Open MainActivity.java and update import your.name.here.speedtest.R with your new package name
  • Do the same thing for GaugeView.java
  • Build the application

Adding your test points

Expand app > assets and open ServerList.json. Here you will find a list of test servers expressed as a JSON array.

  • Select all and delete
  • Add your test points following this syntax: 
    [
    {
        "name":"My Test Server 1",
        "server":"//example.yourdomain.com",
        "dlURL":"garbage.php",
        "ulURL":"empty.php",
        "pingURL":"empty.php",
        "getIpURL":"getIP.php"
    },
    {
        ...
    }
    ...
]
    If you want the test to load this list from an URL instead of a file, just put the URL that you want to be loaded in the file in quotes, like this: 
    "//mydomain.com/ServerList.json"
    The syntax of the remote JSON file is the same as the local one.
  • Save the file

Here's a more in-depth explanation of what the individual fields for each servers are:

  • "name": User friendly name (eg. "Milan, Italy")
  • "server": URL to the server where LibreSpeed is installed. If it only supports HTTP or HTTPS, specify it; if it supports both, simply use // followed by the address
  • "dlURL": Path on your server where the download test can be performed (typically "garbage.php" or "backend/garbage.php")
  • "urURL": Path on your server where the upload test can be performed (typically "empty.php" or "backend/empty.php")
  • "pingURL": Path on your server where the ping/jitter test can be performed (typically "empty.php" or "backend/empty.php")
  • "getIpURL": Path on your server where the IP address and ISP info can be fetched (typically "getIP.php" or "backend/getIP.php")

Important: This app DOES NOT handle HTTP redirects (3xx codes)!

Telemetry and results sharing

If you want to enable telemetry and results sharing, edit TelemetryConfig.json. Here you need to add the information about your telemetry server (LibreSpeed frontend server). This feature is disabled by default.

  • Follow this syntax:
{
    "telemetryLevel":"full",
    "server":"//speedtest.yourdomain.com",
    "path":"results/telemetry.php",
    "shareURL":"results/?id=%s"
}
  • Save the file

Here's a more in-depth explanation of what the individual fields are:

  • "telemetryLevel":
    • "disabled": No telemetry sent at all. If you choose this, you don't need to specify anything else
    • "basic": Stores results for completed tests without log
    • "full": Stores results and log for all tests, even if they are aborted or if they fail
    • Default: "disabled"
  • "server": URL to the server where the LibreSpeed telemetry is installed (the frontend server). If it only supports HTTP or HTTPS, specify it; if it supports both, simply use // followed by the address
  • "path": Path on your server where telemetry can be stored (typically results/telemetry.php)
  • "shareURL": Path on your server where the results sharing links point to (typically results/?id=%s or an empty string if you don't want to enable this feature). %s will be replaced by the test ID. Omit this if you don't want to use results sharing

Privacy policy

Telemetry contains personal information (according to GDPR defintion), therefore it is important to treat this data respectfully of national and international laws, especially if you plan to offer the service in the European Union.

A template for a privacy policy is included in privacy_en.html. You MUST read it, change it if necessary, and att your email address for data deletion requests. Failure to comply with GDPR regulations can get you in serious trouble.

If you plan to support other languages, see the chapter on localization on how to localize the privacy policy.

Optional: Advanced configuration

The default speedtest configuration is fine for most use cases, but you can customize it if you want.

  • Edit SpeedtestConfig.json. Inside you will find an empty JSON object. This indicates that the test is uses the default configuration. Delete it.
  • Follow this syntax:
{
    "param1":"value",
    "param2":"other value",
    ...
}

Here's a list of all the test parameters. All parameters are optional. Do not change them unless you have a good reason to!

  • "dl_ckSize": Size in megabytes of the garbage data generated by garbage.php and downloaded by the test.
    • Default: 100,
    • Recommended: 1-400
    • Important: if you're not using garbage.php, make sure that your replaement file or whatever sends at least ckSize megabytes of data or the download test might fail!
  • "ul_ckSize": Size in megabytes of the garbage data sent by the upload test.
    • Default: 20,
    • Recommended: 1-100
  • "dl_parallelStreams": Number of concurrent streams used by the download test.
    • Default: 3
    • Recommended: 1-6.
  • "ul_parallelStreams": Number of concurrent streams used by the upload test.
    • Default: 3
    • Recommended: 1-6.
  • "dl_streamDelay": Delay in milliseconds between starts of concurrent streams in the download test
    • Default: 300
    • Recommended: 0-1000
  • "ul_streamDelay": Delay in milliseconds between starts of concurrent streams in the upload test
    • Default: 300
    • Recommended: 0-1000
  • "time_dl_max": Maximum duration in settings of the download test (if time_auto is set to false, this will be the fixed duration)
    • Default: 15
    • Recommended: 5-30
  • "time_ul_max": Maximum duration in settings of the upload test (if time_auto is set to false, this will be the fixed duration)
    • Default: 15
    • Recommended: 5-30
  • "time_auto": If set to true, the duration of the upload and download tests will be automatically decided according to the measured speed.
    • Default: true
  • "count_ping": Number of pings to be done during the ping+jitter test
    • Default: 10
    • Recommended: 3-50
  • "dl_graceTime": Seconds at the beginning of the download test where data is discarded (allows TCP window adjustment)
    • Default: 1.5
    • Recommended: >0
  • "ul_graceTime": Seconds at the beginning of the upload test where data is discarded (prevents initial spike due to buffering)
    • Default: 1.5
    • Recommended: >0
  • "errorHandlingMode": What the test should do in case an error is encountered
    • "fail": Fail the test immediately
    • "attempt-restart": If a stream dies, it tries to restart it. If reopening fails, the test fails
    • "must-restart": If a stream dies, keep trying to restart it indefinitely
    • Default: "attempt-restart"
  • "getIP_isp": If set to true, the test will request ISP information along with the IP address
    • Default: true
  • "getIP_distance": If getIP_isp is set to true, this tells whether to calculate approximate distance or not, and the unit
    • "no": Do not calculate distance
    • "km": Calculate distance in kilometers
    • "mi": Calculate distance in miles
    • Default: "km"
  • "overheadCompensationFactor": How much the download and upload values should be multipled by to compensate for transport overhead
    • Default: 1.06
    • Recommended: 1 to ignore overhead, or 1.06 for a decent estimate
  • "useMebibits": If set to true, the download and upload speeds will be measured in mebibits instead of megabits
    • Default: false
  • "test_order": The order in which tests are performed. Each character in this string represents a test. Tests can only be run once
    • Default: "IP_D_U"
    • I: IP address and ISP information
    • P: Ping+jitter test
    • D: Download test
    • U: Upload test
    • _: 1 second delay
  • "dl_connectTimeout", "dl_soTimeout": Timeouts in milliseconds for the sockets used in the download test.
    • Default: 5000, 10000
    • -1 means System default
  • "ul_connectTimeout", "ul_soTimeout": Timeouts in milliseconds for the sockets used in the upload test.
    • Default: 5000, 10000
    • -1 means System default
  • "ping_connectTimeout", "ping_soTimeout": Timeouts in milliseconds for the sockets used in the ping+jitter test, the server selector, IP/ISP fetching, and telemetry.
    • Default: 2000, 5000
    • -1 means System default
  • "dl_recvBuffer", "dl_sendBuffer": Sizes of socket buffers used in the download test
    • Default: -1
    • -1 means System default
  • "ul_recvBuffer", "ul_sendBuffer": Sizes of socket buffers used in the upload test
    • Default: -1 and 16384 respectively
    • -1 means System default
  • "ping_recvBuffer", "ping_sendBuffer": Sizes of socket buffers used in the ping+jitter test
    • Default: -1
    • -1 means System default

Branding

Logos and background

Expand app > res > drawable. Replace the following files (make sure that they actually go in the drawable folder!):

  • ic_launcher.png: App icon (256x256 recommended)
  • logo.png: Large logo file used in the splash screen (1000px width recommended)
  • logo_inapp.png: Small logo file shown above the test (800-1000px width recommended)
  • testbackground.png: Background image shown under the test (Large but not too large or it won't be loaded to prevent crashing low end devices)

App name and link

Expand app > res > values and edit strings.xml.

  • Replace the value of app_name with the name of your app
  • Replace the value of logo_inapp_link with a link to your website that users can open by clicking on the logo. Leave empty if you don't want the logo to be clickable.

Colors

Expand app > res > values and edit colors.xml.

Here's a list of where each color is used:

  • splashBackground: Displayed on the splash screen, under the logo
  • appBackground: Background color in the rest of the app
  • textColor: Color used by most of the text in the application
  • loadingColor: Color of the spinning progress bar displayed during server selection
  • gaugesBackground: Background color of the gauges
  • progressBackground: Background color of the progress bars below the download and upload indicators (ignored in older versions of Android)
  • progressColor: Color of the progress bars below the download and upload indicators (ignored in older versions of Android)
  • dlGauge: Color of the download gauge
  • dlText: Color of the text indicating the download speed
  • ulGauge: Color of the upload gauge
  • ulText: Color of the text indicating the upload speed
  • pingText: Color of the text indicating the ping time
  • jitterText: Color of the text indicating the jitter time
  • serverText: Color of the text indicating the server name
  • startButton_background: Color of the start button
  • startButton_test: Color of the text in the start button
  • failButton_background: Color of the fail button (the one that says Retry)
  • failButton_test: Color of the text in the fail button (the one that says Retry)
  • shareButton_background: Color of the share button
  • shareButton_test: Color of the text in the share button
  • restartButton_background: Color of the button to start a new test
  • restartButton_test: Color of the text in the button to start a new test
  • privacyLinks: Color of the link to open/close the privacy policy

Important: Make sure your text is always legible!

Optional: localization

The template only contains an English localization. To replace the English text or add other languages, expand app > res > values and double click strings.xml. From here you can change all the strings in the application. To add other languages, use Android Studio's localization editor.

Here's a description of each string:

  • app_name: Name of the app as it appears in the app drawer
  • logo_inapp_link: Link to open if the user clicks on the logo. Leave this empty if you don't want this
  • privacy_policy: URL to the privacy policy for this specific locale. You can have multiple privacy policies for different languages in the assets folder
  • init_init: Displayed while the app is loading
  • initFail_configError: Error that appears if the configuration couldn't be loaded
  • initFail_retry: Text of the Retry button when initialization or server selection fails
  • init_selecting: Displayed while the app is selecting a server
  • initFail_noServers: Displayed if no servers are available
  • serverSelect_message: Displayed above the server selection spinner
  • start: Text of the Start button
  • test_dl: Label above the download gauge
  • test_ul: Label above the upload gauge
  • test_speedMeasure: Label below the download and upload gauges
  • test_ping: Label above the ping time indicator
  • test_jitter: Label above the jitter time indicator
  • test_timeMeasure: Label next to the ping and jitter indicators
  • test_share: Text of the share button
  • test_restart: Text of the new test button
  • testFail_err: Displayed if an error occurs during the test
  • testFail_retry: Text of the Retry button when the test fails
  • privacy_open: Text of the link that opens the privacy policy
  • privacy_close: Text of the link that closes the privacy policy

The end

Your template is now fully configured for your LibreSpeed server(s). Enjoy!

This template is licensed under the GNU LGPLv3 License. In short, you are free to use, study, modify, and distribute modified copies of this application, but they must remain under the same GNU LGPLv3 license. This means that if you make any modification to the application, the source code must be made publicly available. Merely changing the configuration of this template as we did in this chapter does NOT count as a modified version, so you are free to distribute it as an APK, but any other change made to the app does count as a modification and you MUST provide the source code.

Topics

Advanced topics

Clone this wiki locally