Download PDF

SamKnows web test.

The Web SDK allows third parties to embed SamKnows measurements into their web applications. This is commonly used to deliver a web speed test, branded according to the third party's liking.

There are two ways that the Web SDK can be used. Firstly, the developers can use a library directly which allows you to completely configure the appearance and behaviour of the speed test. Alternatively, developers can use an embeddable iframe API which is far simpler to set up and still allows basic appearance customisation.

Supported tests

Due to the sandboxed nature of web browsers, the web test only runs a subset of the tests available in the router SDK or mobile apps:

  • Download speed
  • Upload speed
  • Latency
  • Jitter (derived from the latency test)

Supported browsers

We test the web test in the following browsers:

  • Google Chrome on Windows
  • Firefox on Windows
  • Internet Explorer 11 on Windows
  • Microsoft Edge on Windows
  • Google Chrome on OS X
  • Safari on OS X
  • Firefox on OS X
  • Google Chrome on Android
  • Safari on iPhone

The latency and upload tests both use WebSockets in all browsers, and the download test uses the fetch streaming API in Chrome, Firefox, and Safari, and WebSockets in Internet Explorer and Edge—basically, it uses the fetch streaming API in all browsers that support it except for Edge, where it was unreliable.

Iframe API

SamKnows provides an embeddable version of the speed test which is already set up to work with the library, available with a couple configurable styles.

It is hosted at http://speedtest.samknows.com/, and you can use an iframe to embed it in a page:

The responsive design allows for usage at a number of different sizes.

You can pass in options in the URL:

  • primary: Set the colour of the needle.
  • secondary: Set the colour of the button and gauge.
  • lang: Hardcode a different language. Defaults to browser language.
  • show-results: Whether to show the results. Defaults to true.

postMessage

The page inside the iframe emits events (containing data such as the results, test ID or any errors) using the postMessage API. You can listen to the events like this:

window.addEventListener('message', function (e) {
        if (e.origin !== 'https://embedded-speedtest.samknows.com') {
          return;
        }

        console.log(e.data);
      });

It's best to run the above code and see what's logged to the console to see what is emitted, but here's a quick overview of the different types, which you can access as e.data.type:

  • warning is emitted whenever there is something you should make the user aware of: for example, a possibly inaccurate test
  • test-id is emitted when the test has been stored in the SamKnows database, this ID can be used to refer to the test
  • progress is emitted while the test is running with the latest results
  • complete is emitted when the test has finished running, with an object containing the test results

The results object while the test is in progress looks something like this:

{
        "inProgress": "download",
        "latency": {
          "latency": 4.700000000048021,
          "jitter": 2.1000000002459274,
          "successes": 10,
          "failures": 0,
          "target": "10.0.0.106",
          "utc_datetime": "2018-06-12T10:27:30.599Z"
        },
        "download": {
          "bytes_sec": 30436705.76930629,
          "mbps": 243.49364615445032,
          "bytes_total": 204087040,
          "duration": 6284.699999999655,
          "successes": 1,
          "failures": 0,
          "target": "10.0.0.106",
          "utc_datetime": "2018-06-12T10:27:42.607Z"
        }
      }

When the test is complete, it will look something like this:

{
        "latency": {
          "latency": 3.540000000067812,
          "jitter": 0.7399999998611747,
          "successes": 10,
          "failures": 0,
          "target": "10.0.0.106",
          "utc_datetime": "2018-06-12T10:28:19.779Z"
        },
        "download": {
          "bytes_sec": 28178917.178344704,
          "mbps": 225.43133742675766,
          "bytes_total": 281783536,
          "duration": 9999.799999999595,
          "successes": 1,
          "failures": 0,
          "target": "10.0.0.106",
          "utc_datetime": "2018-06-12T10:28:31.778Z"
        },
        "upload": {
          "bytes_sec": 30436705.76930629,
          "mbps": 243.49364615445032,
          "bytes_total": 304087040,
          "duration": 9990.800000000483,
          "successes": 1,
          "failures": 0,
          "target": "10.0.0.106",
          "utc_datetime": "2018-06-12T10:28:43.825Z"
        }
      }