Load the SDK using a script element:
<script async src="http://sdk.netscan.co/netscan.js" type="text/javascript"></script>
This will expose the global variable netscan
.
CAUTION: In this snippet, the
async
keyword is used. Be careful to wait for the it to load.
If you need to fetch the netscan SDK via SSL just use our S3 endpoint:
<script async src="https://s3.amazonaws.com/sdk.netscan.co/netscan.js" type="text/javascript"></script>
BEWARE! Using Netscan over TLS (SSL) will result in all plain HTTP tests to fail, that includes XHR and WebSocket HTTP tests, that is happening because of the built-in security policies of the browser which will not allow unsecure connections to happen when on secure mode (TLS).
There are three main way to load the Netscan SDK.
async
keyword.async
The proposed way of loading the Netscan SDK is by using the HTML5 async
attribute.
<script async src="http://sdk.netscan.co/netscan.js" type="text/javascript"></script>
The async
keyword does not support Internet Explorer 9 and back, so you might want to inject the Netscan SDK asynchronously with Javascript.
<script>
(function(d, t) {
var g = d.createElement(t);
var s = d.getElementsByTagName(t)[0];
g.src = 'http://sdk.netscan.co/netscan.js';
s.parentNode.insertBefore(g, s);
}(document, 'script'));
</script>
To be notified once Netscan has been loaded and is ready just push your method to the global Array netscanHooks
:
// Use existing Array or initialize a new one if none exists.
window.netscanHooks = window.netscanHooks || [];
// Attach a Netscan Ready listener
window.netscanHooks.push(function() {
console.log('Netscan is ready');
});
Here is an example:
// The onReady callback function.
var onReady = function () {
// Initialize
var nets = window.netscan();
// Setup token and options
nets.setup({
token: 'YOUR-TOKEN',
});
// Invocation - Start Scanning
nets.start(function(err, result) {
console.log(result);
});
}
// Push a callback function in a array, which the SDK calls after it has loaded.
window.netscanHooks = window.netscanHooks || [];
window.netscanHooks.push(onReady);
By the time Netscan initializes it performs a series of browser feature detections and offers the results under the property has
.
window.netscan.has.cookies; // true
window.netscan.has.cors; // true
window.netscan.has.es5array; // true
window.netscan.has.es5date; // true
window.netscan.has.es5function; // true
window.netscan.has.es5object; // true
window.netscan.has.es5strict; // true
window.netscan.has.es5string; // true
window.netscan.has.eventlistener; // true
window.netscan.has.fileapi; // true
window.netscan.has.flash; // Boolean Object
window.netscan.has.flash.blocked; // false
window.netscan.has.history; // true
window.netscan.has.json; // true
window.netscan.has.video; // Boolean Object
window.netscan.has.video.h264: "probably"
window.netscan.has.video.ogg: "probably"
window.netscan.has.video.vp9: "probably"
window.netscan.has.video.webm: "probably"
window.netscan.has.webgl; // true
window.netscan.has.webrtc; // true
window.netscan.has.webrtcFeatures; // Object
window.netscan.has.webrtcFeatures.audio; // true
window.netscan.has.webrtcFeatures.prefix; // "webkit"
window.netscan.has.webrtcFeatures.video; // true
window.netscan.has.websockets; // true
Netscan needs to be instantiated before you can operate with it. To create a new instance simply invoke the Netscan global:
var netscanInstance = window.netscan();
A new Netscan instance will be created and returned each time you invoke the global method.
netscanInstance.setup(config);
The setup()
method allows the configuration of Netscan, it accepts an Object with configurations options:
null
Your public token, this option is required.
false
Set this option to true
to get the whole Results Data Object when the test completes. You will get the Id and URL in either cases.
Control which connectivity tests will run:
tests.xhr
Type: Boolean Set to false to disable the XHR Connectivity tests.tests.websockets
Type: Boolean Set to false to disable the websockets Connectivity tests.tests.webrtc
Type: Boolean Set to false to disable the WebRTC Connectivity tests.Pass optional TURN server to be used for the test.
turnServer.username
Type: String Username for TURN server.turnServer.credential
Type: String Required credential for TURN server access.turnServer.urls
Type: Array.{}
Pass any custom data schemas as long as they are of Object type.
data.name
Type: String Name is a special data property, it is the only one that is visible on the dashboard. Any other that you pass can be read from the API route /result/{scanId}
(eg. https://www.netscan.co/result/Geru1) under the data
key.Example:
netscanInstance.setup({
token: 'xyz',
fetchResults: true,
tests: {
xhr: true,
websockets: true,
webrtc: true,
},
data: {
name: 'Matt Smith'.
anythingReally: 1,
},
turnServer: {
username: 'netscan',
credential: 'xxx',
urls: [
'turn:turn.example.com:3478?transport=udp',
'turn:turn.example.com:3478?transport=tcp',
'turn:turn.example.com:3479?transport=udp',
'turn:turn.example.com:3479?transport=tcp',
],
},
});
netscanInstance.start(callback);
The start()
method kickstarts the Netscan browser diagnostics and connectivity tests, you may add a callback as an argument.
Example:
netscanInstance.start(function(err, result) {
if (err) {
// handle error
return;
}
console.log(result);
});
As you can see in the example, the callback will get two arguments:
err
Type: Error|null Always check for errors, if no errors occurred the value will be null
. Errors are a very rare occasion.result
Type: Object In the result
key you will find the Result Data Object. If you've set the fetchResults
option to true the results
key will be available in the RDO, otherwise you will only get the root properties of the RDO.If you need to bind on events emitted by the Netscan instance use the on()
and off()
methods, Netscan uses the component-emitter NPM Package to provide an events API.
The Component Emitter instance is available at
netscanInstance.ee
.
Netscan wraps the on()
and off()
methods for your convenience:
Adds an event listener to the event called eventName
a String:
netscanInstance.on(eventName, callback);
Removes an event listener from the event called eventName
a String:
netscanInstance.off(eventName, callback);
start
The Netscan tests are initiating.xhrStart
Triggers for each test performed (HTTP & TLS), provides two arguments:port
Type: String The TCP port used, 80 for HTTP or 443 for TLS.result
Type: Object The specific port result object with the test results as analyzed in the Results Explained Document.xhrSuccess
Invoked upon a specific XHR test completion, provides two arguments:port
Type: String The TCP port used, 80 for HTTP or 443 for TLS.result
Type: Object The specific port result object with the test results as analyzed in the Results Explained Document.xhrError
Triggers when the Netscan client has failed to connect to the server, this issues a retry attempt up to the maximum number of allowed failed attempts, provides these two arguments:port
Type: String The TCP port used, 80 for HTTP or 443 for TLS.result
Type: Object The specific port result object with the test results as analyzed in the Results Explained Document.xhrEnd
Triggers once all the XHR (HTTP and TLS) tests have completed, provides a single argument:result
Type: Object The complete XHR result object including the port numbers as can be seen in the Results Explained Document.sockStart
Triggers with each test (HTTP or TLS), provides a single argument:result
Type: Object The WebSocket Result Data Object as can be seen in the Results Explained Document.sockOpen
Triggers once the WebSocket connection has been opened, provides a single argument:result
Type: Object The WebSocket Result Data Object as can be seen in the Results Explained Document.sockEnd
Triggers once the WebSocket tests are complete for the specific protocol (HTTP or TLS), provides a single argument:result
Type: Object The WebSocket Result Data Object as can be seen in the Results Explained Document.