Netscan Javascript API

Table of Contents

  1. How to Load the SDK
    1. Loading via TLS (SSL)
    2. Loading Methods
  2. Netscan Runtime Feature Detection
  3. Instantiating Netscan
  4. Instance Methods
    1. The "setup" Method
    2. The "start" Method
  5. Instance Events
    1. netscanInstance.on Method
    2. netscanInstance.off Method
    3. The Instance Events
      1. Core Events
      2. XHR Events
      3. WebSockets Events

How to Load the SDK

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.

Loading via TLS (SSL)

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).

⬆ back to TOC

Loading Methods

There are three main way to load the Netscan SDK.

  1. Synchronously.
  2. Asynchronously using the async keyword.
  3. Asynchronously using Javascript injection.

Using 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>

Using Javascript injection

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>

Use the SDK when loading it asynchronously

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);

⬆ back to TOC

Netscan Runtime Feature Detection

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

⬆ back to TOC

Instantiating Netscan

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.

⬆ back to TOC

Instance Methods

The "setup" Method

netscanInstance.setup(config);

The setup() method allows the configuration of Netscan, it accepts an Object with configurations options:

token

  • Type: String
  • Default: null
  • REQUIRED

Your public token, this option is required.

fetchResults

  • Type: Boolean
  • Default: 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.

tests

  • Type: Object

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.

turnServer

  • Type: Object

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. Array of strings with the TURN server urls.

data

  • Type: Object
  • Default: {}

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',
    ],
  },
});

⬆ back to TOC

The "start" Method

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.

⬆ back to TOC

Instance Events

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:

netscanInstance.on Method

Adds an event listener to the event called eventName a String:

netscanInstance.on(eventName, callback);

netscanInstance.off Method

Removes an event listener from the event called eventName a String:

netscanInstance.off(eventName, callback);

⬆ back to TOC

The Instance Events

Core Events

  • start The Netscan tests are initiating.

XHR Events

  • 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:

⬆ back to TOC

WebSockets Events

  • sockStart Triggers with each test (HTTP or TLS), provides a single argument:
  • sockOpen Triggers once the WebSocket connection has been opened, provides a single argument:
  • sockEnd Triggers once the WebSocket tests are complete for the specific protocol (HTTP or TLS), provides a single argument:

⬆ back to TOC