Smart Connectivity Test Suite has capabilities to perform active network tests before the call (pre-call tests) or in the background at any time. This section covers the APIs to start/stop the tests and how to integrate the results from the various callback APIs .

API

To use the precalltest API, you should have added callstats.js to your app and initialized it. Specifically, steps 1 and 2 on callstats.js: Integrating with your WebRTC App.

callstats.startPrecallTests()

This API can be used to make precall tests continuously as per the interval given by the customers. The results of the precall test will be given in the preCallTestResults callback. Once we run precall tests on all the turn credentials provided, the connection recommendation is provided in the connectionRecommendation callback.

📘

Note

Interval default value is 60 seconds, if not provided. The minimum interval is 30 seconds, and the recommended interval is 300 seconds

callstats.startPrecallTests(iceServers, interval);

var iceServers = [
   {
      "urls":[
         "turns:taas.callstats.io:443?transport=udp",
         "turns:taas.callstats.io:443?transport=tcp",
         "turn:taas.callstats.io:80?transport=udp",
         "turn:taas.callstats.io:80?transport=tcp"
      ],
      "username":,
      "credential":,
      "label": "turn2"
   },
   {
      "urls":[
        "turn:turn-server-1.dialogue.io:3478"
      ],
      "username":,
      "credential":,
      "label": "turn2"
    }
];

callstats.stopPrecallTests()

This API to stop the precall tests started using the API startPrecallTests()

callstats.stopPrecallTests();

callstats.on()

The "on" function is used to set the callbacks for smart connectivity tests. We also use the same callback during the call, and they are documented at: callstats.js callbacks and onEvents API.

The pre-call test results callback (csPreCallTestResultsCallback)

The csPreCallTestResultsCallback function is set with the on() functionality. The callback is invoked when the pre-call test results are available. The pre-call test measures the Media Connectivity, Round Trip Time, Fractional Loss, and Throughput against callstats.io TURN servers. You can use the “status” to check if the pre-call test has succeeded, it will return success or failure. The pre-call test is enabled by default and is running as long as the callback is not fired. The pre-call test might return partial results if the tests are interrupted or the call begins during the pre-call test. You can disable pre-call test by setting "disablePrecalltest" to true in configParams.

//Usage
callstats.on("preCallTestResults", csPreCallTestResultsCallback);

function preCallTestResultsCallback(status, results) {

//Check the status
  if (status == callstats.callStatsAPIReturnStatus.success) {
    //Results
    var connectivity = results.mediaConnectivity;
    var rtt = results.rtt;
    var loss = results.fractionalLoss;
    var throughput = results.throughput;
    console.log(results);
  }
  else {
    console.log("Pre-call test could not be run");
  }
}

// console log output
{
    "mediaConnectivity": true,
    "throughput": 1796.1354352637957,
    "fractionalLoss": 0.004484480852075867,
    "rtt": 57.945068359375,
    "jitter": 309.0593613654375,
    "timestamp": 1616175041022.625,
    "provider": "callstats",
}

The connection recommendation callback (csConnectionRecommendationCallback)

The csConnectionRecommendationCallback function is set with the on() functionality. The callback is invoked when the precall tests are finished for all the TURN credentials given in 'startPrecallTest'. Connection recommendation gives the statistics measured, and the ranking of the TURN servers provided.

//Usage
callstats.on("connectionRecommendation", results => {
  console.log(results);
})

//console log output
{
   "aggregatedStats":[
      {
         "provider":"turn1",
         "roundTripTime":46.3499755859375,
         "jitter":143.7728006389737,
         "fractionLost":0,
         "throughput":4160.657588552875
      },
      {
         "provider":"turn2",
         "roundTripTime":106.699951171875,
         "jitter":1547.3617393722136,
         "fractionLost":0.5257732840987372,
         "throughput":584.6231721117872
      }
   ],
   "providerRanking":[
      {
         "provider":"turn1",
         "acceptable":true
      },
      {
         "provider":"turn2",
         "acceptable":false
      }
   ]
}

SCT notifications

We moved pctConnectionQualityChange to its own section!