https://github.com/m-lab/ndt7-js
Web client for ndt7 written in JavaScript
https://github.com/m-lab/ndt7-js
Last synced: 6 months ago
JSON representation
Web client for ndt7 written in JavaScript
- Host: GitHub
- URL: https://github.com/m-lab/ndt7-js
- Owner: m-lab
- License: apache-2.0
- Created: 2020-06-16T22:21:49.000Z (about 6 years ago)
- Default Branch: main
- Last Pushed: 2026-01-15T16:50:03.000Z (6 months ago)
- Last Synced: 2026-01-15T16:52:22.880Z (6 months ago)
- Language: JavaScript
- Homepage:
- Size: 937 KB
- Stars: 29
- Watchers: 14
- Forks: 18
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ndt7-js
The official [NDT7](https://github.com/m-lab/ndt-server) Javascript client
library. This code works in all modern browsers and is the source for the npm
package [`@m-lab/ndt7`](https://www.npmjs.com/package/@m-lab/ndt7).
Includes an example web client in the `examples/` directory. Pull requests
gratefully accepted if you would like to write a more sophisticated web client
that uses the returned measurements to debug network conditions.
In case you need a standalone client binary that you can build and run on
multiple operating systems and CPU architectures (including embedded devices)
have a look at the
[official Go client](https://github.com/m-lab/ndt7-client-go) instead.
## API Reference
## ndt7 : object
**Kind**: global namespace
* [ndt7](#ndt7) : object
* [.discoverServerURLS](#ndt7.discoverServerURLS)
* [.downloadTest](#ndt7.downloadTest) ⇒ number
* [.uploadTest](#ndt7.uploadTest) ⇒ number
* [.test](#ndt7.test) ⇒ number
### ndt7.discoverServerURLS
discoverServerURLs contacts a web service (likely the Measurement Lab
locate service, but not necessarily) and gets URLs with access tokens in
them for the client. It can be short-circuted if config.server exists,
which is useful for clients served from the webserver of an NDT server.
**Kind**: static property of [ndt7](#ndt7)
**Access**: public
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| config | Object | | An associative array of configuration options. |
| [config.server] | string | | Optional server hostname to connect to directly, bypassing the locate service. Useful for testing against a specific NDT server. |
| [config.protocol] | string | "'wss'" | WebSocket protocol to use. Either 'wss' (secure WebSocket) or 'ws' (insecure). Defaults to 'wss'. |
| [config.metadata] | Object | | Optional metadata to identify your application. Recommended fields: `client_name` (your application name, e.g., 'my-speed-test') and `client_version` (your application version, e.g., '2.1.0'). These are sent as query parameters to help distinguish different integrations. The library automatically includes `client_library_name` ('ndt7-js') and `client_library_version`. |
| [config.loadbalancer] | string | | Optional custom locate service URL to use instead of the default M-Lab locate service. |
| [config.clientRegistrationToken] | string | | Optional JWT token for registered integrator access. When provided, identifies that tests are being run through a registered client integration, enabling access to the priority endpoint (v2/priority/nearest) with higher rate limits. The token should be obtained from your integrator backend that securely manages API credentials with the M-Lab token exchange service. This registers your client implementation, not individual end users. |
| userCallbacks | Object | | An associative array of user callbacks. |
| [userCallbacks.error] | function | | Called when an error occurs. Receives an error message string. If not provided, errors throw. |
| [userCallbacks.serverDiscovery] | function | | Called when server discovery starts. Receives `{loadbalancer: URL}` where URL is the locate service URL being queried. |
| [userCallbacks.serverChosen] | function | | Called when a server is selected. Receives the server object from locate results. |
### ndt7.downloadTest ⇒ number
downloadTest runs just the NDT7 download test.
**Kind**: static property of [ndt7](#ndt7)
**Returns**: number - Zero on success, and non-zero error code on failure.
**Access**: public
| Param | Type | Description |
| --- | --- | --- |
| config | Object | An associative array of configuration strings |
| userCallbacks | Object | |
| urlPromise | Object | A promise that will resolve to urls. |
### ndt7.uploadTest ⇒ number
uploadTest runs just the NDT7 download test.
**Kind**: static property of [ndt7](#ndt7)
**Returns**: number - Zero on success, and non-zero error code on failure.
**Access**: public
| Param | Type | Description |
| --- | --- | --- |
| config | Object | An associative array of configuration strings |
| userCallbacks | Object | |
| urlPromise | Object | A promise that will resolve to urls. |
### ndt7.test ⇒ number
test discovers a server to run against and then runs a download test
followed by an upload test.
**Kind**: static property of [ndt7](#ndt7)
**Returns**: number - Zero on success, non-zero on failure.
**Access**: public
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| config | Object | | An associative array of configuration options. |
| [config.server] | string | | Optional server hostname to connect to directly, bypassing the locate service. Useful for testing against a specific NDT server. |
| [config.protocol] | string | "'wss'" | WebSocket protocol to use. Either 'wss' (secure WebSocket) or 'ws' (insecure). Defaults to 'wss'. |
| [config.metadata] | Object | | Optional metadata to identify your application. Recommended fields: `client_name` (your application name, e.g., 'my-speed-test') and `client_version` (your application version, e.g., '2.1.0'). These are sent as query parameters to help distinguish different integrations. The library automatically includes `client_library_name` ('ndt7-js') and `client_library_version`. |
| [config.loadbalancer] | string | | Optional custom locate service URL to use instead of the default M-Lab locate service. |
| [config.clientRegistrationToken] | string | | Optional JWT token for registered integrator access. When provided, identifies that tests are being run through a registered client integration, enabling access to the priority endpoint (v2/priority/nearest) with higher rate limits. The token should be obtained from your integrator backend that securely manages API credentials with the M-Lab token exchange service. This registers your client implementation, not individual end users. |
| [config.userAcceptedDataPolicy] | boolean | | Must be set to true to indicate the user has accepted M-Lab's data policy. Required unless mlabDataPolicyInapplicable is true. |
| [config.mlabDataPolicyInapplicable] | boolean | | Set to true if M-Lab's data policy does not apply to your use case. |
| userCallbacks | Object | | An associative array of user callbacks. |
| [userCallbacks.error] | function | | Called when an error occurs. Receives an error message string. If not provided, errors throw. |
| [userCallbacks.serverDiscovery] | function | | Called when server discovery starts. Receives `{loadbalancer: URL}` where URL is the locate service URL being queried. |
| [userCallbacks.serverChosen] | function | | Called when a server is selected. Receives the server object from locate results. |
| [userCallbacks.downloadStart] | function | | Called when download test starts. Receives start event data. |
| [userCallbacks.downloadMeasurement] | function | | Called during download test. Receives `{Source, Data}` where Source is 'client' or 'server' and Data contains measurement values. |
| [userCallbacks.downloadComplete] | function | | Called when download completes. Receives `{LastClientMeasurement, LastServerMeasurement}`. |
| [userCallbacks.uploadStart] | function | | Called when upload test starts. Receives start event data. |
| [userCallbacks.uploadMeasurement] | function | | Called during upload test. Receives `{Source, Data}` where Source is 'client' or 'server' and Data contains measurement values. |
| [userCallbacks.uploadComplete] | function | | Called when upload completes. Receives `{LastClientMeasurement, LastServerMeasurement}`. |