Callbacks and Error Handling
The WebRTC application can provide callback functions to callstats.js which are invoked in case of the following events:
- After the initialize
- To enquire the stats
- To obtain pre-call test results
- To obtain the default configuration
- To obtain the recommended configuration
- To check the errors
The initialize callback (csInitCallback)
The csInitCallback function is given as a parameter to the initialize() call. To report different success and failure cases, which can occur during initialize() or sending measurements to callstats.io. The callback takes the form of:
csError and csErrMsg are of type String. csErrMsg is a descriptive error returned by callstats.io.
// initialize the callstats js API
var callstats = new callstats();
callstats.initialize(AppID, AppSecret, localUserId, csInitCallback, csStatsCallback);
function csInitCallback(csError, csErrMsg) {
console.log("Status: errCode= " + csError + " errMsg= " + csErrMsg ); }
The stats callback (csStatsCallback)
The csStatsCallback function can either be given as a parameter to the initialize() call, or set separately with the on() functionality.
The csStatsCallback() will be called by the callstats.js for each PeerConnection independently at regular intervals. By default the interval is set as 10 seconds to make sure we do not overwhelm the app with too many messages. For more information, please check out our blog on csStatsCallback()
// initialize the callstats js API
var callstats = new callstats();
callstats.initialize(AppID, AppSecret, localUserId, csInitCallback, csStatsCallback);
var reportType = {
inbound: 'inbound-rtp',
outbound: 'outbound-rtp'
};
// callback function to receive the stats
var csStatsCallback = function (stats) {
var ssrc;
for (ssrc in stats.streams) {
console.log("SSRC is: ", ssrc);
var dataSsrc = stats.streams[ssrc];
console.log("SSRC Type ", dataSsrc.reportType);
if (dataSsrc.reportType === reportType.outbound) {
console.log("RTT is: ", dataSsrc.rtt);
} else if (dataSsrc.reportType === reportType.inbound) {
console.log("Inbound loss rate is: ", dataSsrc.fractionLoss);
}
}
}
// JSON description of the metrics structure
"stats": {
"connectionState":, // one of: online, offline
"fabricState":, // one of: initialising, established, disrupted.
"conferenceURL":, // URL of the conference
// New csStatsCallback format
"mediaStreamTracks": [
[0]: {
"remoteUserID":, // associated during the addNewFabric() API
"statsType":, // inbound-rtp, outbound-rtp, remote-inbound-rtp, remote-outbound-rtp
// data here is parsed from the local and remote SDP
"cname":, // CNAME associated with the SSRC
"msid":, // mediastreamID associated with the SSRC
"mediaType":, // either video or audio
// provided in associateMstWithUserID() API
"usageLabel":, //usage information
"associatedVideoTag":, // video tag that renders the media
"bitrate":, // interval bitrate in kbps
"packetRate":, // packets per second
"fractionLoss":, // interval fractional loss
"packetLossPercentage":,// Packet loss in percentage
"jitter":, // interval jitter in ms
"averageJitter":, // Average jitter
"rtt":, // round-trip time in ms.
"averageRTT":, // Average round-trip time in ms
"quality":, // interval quality as per boundary conditions.
"audioInputLevel":, // audio input level
"audioOutputLevel":, // audio output level
},
...
]
};
callstats.on()
The "on" function is used to set the callbacks for events during the call. We also use the same callback for smart connectivity tests, and they are documented at: callstats.js Precall Test APIs.
| Params | Argument | Type | Description |
|---|---|---|---|
eventName | Required | String | The allowed values are "defaultConfig", "recommendedConfig", "error", and "stats". |
csEventCallback | Required | Callback | The callback asynchronously provides new event data whenever it is available. |
callstats.on(eventName, csEventCallback);
csDefaultConfigurationCallback
The csDefaultConfigurationCallback function is set with the on() functionality. The callback is invoked when the default configuration provided in the callstats.io dashboard is available. It is only fired once.
config.peerConnectionobject is of type RTCConfigurationconfig.mediaobject is of type MediaStreamConstraints
The integration steps are listed here
Note
- While we maintain high reliability and availability in our service, we still recommend that the app should not crash or block on this callback.
- The default configuration provided in the callback is the exact entry you provided on the dashboard. Please make sure that the config is valid and usable by a RTCPeerConnection. This configuration SHOULD be updated with any on-the-fly calculated values in the app.
function csDefaultConfigurationCallback(config) {
var pc = new RTCPeerConnection(config.peerConnection);
getUserMedia(config.media);
}
The recommended configuration callback (csRecommendedConfigurationCallback)
The csRecommendedConfigurationCallback function is set with the on() functionality. The callback is invoked when the recommended configuration provided by callstats.io is available.
Note
- While we maintain high reliability and availability in our service, we still recommend that the app should not crash or block on this callback.
- The recommended configuration is provided by callstats.io. This configuration SHOULD be updated with any on-the-fly calculated values in the app.
function csRecommendedConfigurationCallback(config) {
var pc = new RTCPeerConnection(config.peerConnection);
getUserMedia(config.media);
}
Updated about a year ago