-
Notifications
You must be signed in to change notification settings - Fork 2.1k
Making a custom front end
This section explains how to use speedtest.js in your webpages.
The best way to learn is by looking at the provided examples.
Single server:
-
example-singleServer-basic.html
: The most basic configuration possible. Runs the test with the default settings when the page is loaded and displays the results with no fancy graphics. -
example-singleServer-pretty.html
: A more sophisticated example with a nicer layout and a start/stop button. This is the best starting point for most users -
example-singleServer-progressBar.html
: Same asexample-singleServer-pretty.html
but adds a progress indicator -
example-singleServer-customSettings.html
: Same asexample-singleServer-pretty.html
but configures the test so that it only performs download and upload tests, and with a fixed length instead of automatic -
example-singleServer-gauges.html
: The most sophisticated example, with the same functionality asexample-singleServer-pretty.html
but adds gauges. This is also a good starting point, but the gauges may slow down underpowered devices -
example-singleServer-chart.html
: Shows how to use the test with the Chart.js library -
example-singleServer-full.html
: The most complete example. Based onexample-singleServer-gauges.html
, also enables telemetry and results sharing
Multiple servers:
-
example-multipleServers-pretty.html
: Same asexample-singleServer-pretty.html
but with multiple test points. Server selection is fully automatic -
example-multipleServers-full.html
: Same asexample-singleServer-full.html
but with multiple test points. Server selection is automatic but the server can be changed afterwards by the user
To use the speedtest in your page, first you need to load it:
<script type="text/javascript" src="speedtest.js"></script>
After loading, you can initialize the test:
var s=new Speedtest();
Now, you can set up event handlers to update your UI:
s.onupdate=function(data){
//update your UI here
}
s.onend=function(aborted){
//end of the test
if(aborted){
//something to do if the test was aborted instead of ending normally
}
}
The onupdate
event handler will be called periodically by the test with data coming from the speedtest worker thread. The data
argument is an object containing the following:
-
testState: an integer between -1 and 5
-
-1
= Test not started yet -
0
= Test starting -
1
= Download test in progress -
2
= Ping + Jitter test in progress -
3
= Upload test in progress -
4
= Test finished -
5
= Test aborted
-
-
dlStatus: either
- Empty string (not started or aborted)
- Download speed in Megabit/s as a number with 2 decimals
- The string "Fail" (test failed)
-
ulStatus: either
- Empty string (not started or aborted)
- Upload speed in Megabit/s as a number with 2 decimals
- The string "Fail" (test failed)
-
pingStatus: either
- Empty string (not started or aborted)
- Estimated ping in milliseconds as a number with 2 decimals
- The string "Fail" (test failed)
-
clientIp: either
- Empty string (not fetched yet or failed)
- The client's IP address as a string (with ISP info if enabled)
-
jitterStatus: either
- Empty string (not started or aborted)
- Estimated jitter in milliseconds as a number with 2 decimals (lower = stable connection)
- The string "Fail" (test failed)
- dlProgress: the progress of the download test as a number between 0 and 1
- ulProgress: the progress of the upload test as a number between 0 and 1
- pingProgress: the progress of the ping+jitter test as a number between 0 and 1
- testId: when telemetry is active, this is the ID of the test in the database. This is null until the test is finished, or if telemetry encounters an error. This ID is used for results sharing
The onend
event handler will be called at the end of the test (onupdate
will be called first), with a boolean telling you if the test was aborted (either manually or because of an error) or if it ended normally.
Before starting the test, you can change some of the settings from their default values. You might want to do this to better adapt the speedtest to a specific scenario, such as a satellite connection. To change a setting, use
s.setParameter("parameter_name",value);
For instance, to enable telemetry we can use:
s.setParameter("telemetry_level","basic");
And now the test results will be stored and we will get our test ID at the end of the test (along with the other data)
Main parameters:
-
time_dl_max: Maximum duration of the download test in seconds. If auto duration is disabled, this is used as the duration of the test.
- Default:
15
- Recommended:
>=5
- Default:
-
time_ul_max: Maximum duration of the upload test in seconds. If auto duration is disabled, this is used as the duration of the test.
- Default:
15
- Recommended:
>=10
- Default:
-
time_auto: Automatically determine the duration of the download and upload tests, making them faster on faster connections, to avoid wasting data.
- Default:
true
- Default:
-
count_ping: How many pings to perform in the ping test
- Default:
10
- Recommended:
>=3, <30
- Default:
-
url_dl: path to garbage.php or a large file to use for the download test.
- Default:
garbage.php
- Important: path is relative to js file
- Default:
-
url_ul: path to an empty file or empty.php to use for the upload test
- Default:
empty.php
- Important: path is relative to js file
- Default:
-
url_ping: path to an empty file or empty.php to use for the ping test
- Default:
empty.php
- Important: path is relative to js file
- Default:
-
url_getIp: path to getIP.php or replacement
- Default:
getIP.php
- Important: path is relative to js file
- Default:
-
url_telemetry: path to telemetry.php or replacement
- Default:
results/telemetry.php
- Important: path is relative to js file
- Note: you can ignore this parameter if you're not using the telemetry
- Default:
-
telemetry_level: The type of telemetry to use. See the telemetry section for more info about this
- Default:
none
-
basic
: send results only -
full
: send results and timing information, even for aborted tests -
debug
: same as full but also sends debug information. Not recommended.
- Default:
-
test_order: the order in which tests will be performed. You can use this to change the order of the test, or to only enable specific tests. Each character represents an operation:
-
I
: get IP -
D
: download test -
U
: upload test -
P
: ping + jitter test -
_
: delay 1 second - Default test order:
IP_D_U
- Important: Tests can only be run once
- Important: On Firefox, it is better to run the upload test last
-
-
getIp_ispInfo: if true, the server will try to get ISP info and pass it along with the IP address. This will add
isp=true
to the request tourl_getIp
. getIP.php accomplishes this using ipinfo.io- Default:
true
- Default:
-
getIp_ispInfo_distance: if true, the server will try to get an estimate of the distance from the client to the speedtest server. This will add a
distance
argument to the request tourl_getIp
.__getIp_ispInfo__
must be enabled in order for this to work. getIP.php accomplishes this using ipinfo.io-
km
: estimate distance in kilometers -
mi
: estimate distance in miles - not set: do not measure distance
- Default:
km
-
Advanced parameters: (Seriously, don't change these unless you know what you're doing)
-
telemetry_extra: Extra data that you want to be passed to the telemetry. This is a string field, if you want to pass an object, make sure you use
JSON.stringify
. This string will be added to the database entry for this test. -
enable_quirks: enables browser-specific optimizations. These optimizations override some of the default settings. They do not override settings that are explicitly set.
- Default:
true
- Default:
-
garbagePhp_chunkSize: size of chunks sent by garbage.php in megabytes
- Default:
100
- Recommended:
>=10
- Maximum:
1024
- Default:
-
xhr_dlMultistream: how many streams should be opened for the download test
- Default:
6
- Recommended:
>=3
- Default override: 3 on Edge if enable_quirks is true
- Default override: 5 on Chromium-based if enable_quirks is true
- Default:
-
xhr_ulMultistream: how many streams should be opened for the upload test
- Default:
3
- Recommended:
>=1
- Default:
-
xhr_ul_blob_megabytes: size in megabytes of the blobs sent during the upload test
- Default:
20
- Default override: 4 on Chromium-based mobile browsers (limitation introduced around version 65). This will be forced
- Default override: IE11 and Edge currently use a different method for the upload test. This parameter is ignored
- Default:
-
xhr_multistreamDelay: how long should the multiple streams be delayed (in ms)
- Default:
300
- Recommended:
>=100
,<=700
- Default:
-
xhr_ignoreErrors: how to react to errors in download/upload streams and the ping test
-
0
: Fail test on error (behaviour of previous versions of this test) -
1
: Restart a stream/ping when it fails -
2
: Ignore all errors - Default:
1
- Recommended:
1
-
-
time_dlGraceTime: How long to wait (in seconds) before actually measuring the download speed. This is a good idea because we want to wait for the TCP window to be at its maximum (or close to it)
- Default:
1.5
- Recommended:
>=0
- Default:
-
time_ulGraceTime: How long to wait (in seconds) before actually measuring the upload speed. This is a good idea because we want to wait for the buffers to be full (avoids the peak at the beginning of the test)
- Default:
3
- Recommended:
>=1
- Default:
-
ping_allowPerformanceApi: toggles use of Performance API to improve accuracy of Ping/Jitter test on browsers that support it.
- Default:
true
- Default override:
false
on Firefox because its performance API implementation is inaccurate
- Default:
-
useMebibits: use mebibits/s instead of megabits/s for the speeds
- Default:
false
- Default:
-
overheadCompensationFactor: compensation for HTTP and network overhead. Default value assumes typical MTUs used over the Internet. You might want to change this if you're using this in your internal network with different MTUs, or if you're using IPv6 instead of IPv4.
- Default:
1.06
probably a decent estimate for all overhead. This was measured empirically by comparing the measured speed and the speed reported by my the network adapter. -
1048576/925000
: old default value. This is probably too high. -
1.0513
: HTTP+TCP+IPv6+ETH, over the Internet (empirically tested, not calculated) -
1.0369
: Alternative value for HTTP+TCP+IPv4+ETH, over the Internet (empirically tested, not calculated) -
1.081
: Yet another alternative value for over the Internet (empirically tested, not calculated) -
1514 / 1460
: TCP+IPv4+ETH, ignoring HTTP overhead -
1514 / 1440
: TCP+IPv6+ETH, ignoring HTTP overhead -
1
: ignore overheads. This measures the speed at which you actually download and upload files rather than the raw connection speed
- Default:
If you want to use more than one test server, this is the time to add all your test points and select the best one. Skip this part if you don't want to use this feature.
The best way to do this is to declare an array with all your servers, and give it to the speedtest:
var SPEEDTEST_SERVERS=[
server1,
server2,
...
];
s.addTestPoints(SPEEDTEST_SERVERS);
Each server in the list is an object containing:
-
name
: user friendly name for this test point -
server
: URL to the server. If your server only supports HTTP or HTTPS, puthttp://
orhttps://
at the beginning, respectively; if it supports both, put//
at the beginning and it will be replaced automatically -
dlURL
: path to the download test on this server (garbage.php or replacement) -
ulURL
: path to the upload test on this server (empty.php or replacement) -
pingURL
: path to the ping test on this server (empty.php or replacement) -
getIpURL
: path to getIP on this server (getIP.php or replacement)
None of these parameters can be omitted.
Example:
{
name:"Milano, IT",
server:"http://backend1.myspeedtest.net/",
dlURL:"garbage.php",
ulURL:"empty.php",
pingURL:"empty.php",
getIpURL:"getIP.php"
}
Now, we can run the server selector:
s.selectServer(function(server){
//do something
})
The selectServer
function is asynchronous in order to avoid freeing the UI, and it will run a callback function when it is done choosing the server with the lowest ping.
The server
argument is the selected server, and you can display it in the UI if you want. You cannot start the test until the selection is done!
You can also set the test point manually (for instance, from a combobox in the UI):
s.setSelectedServer(server)
where server
is the server that you want to use.
Finally, we can run the test:
s.start();
During the test, your onupdate
event handler will be called periodically with data that you can use to update your UI. Your onend
handler will be called at the end of the test.
You can abort the test at any time:
s.abort();
When the test is finished, you can run it again if you want, or you can just destroy s
.