watchRTC JS SDK

watchRTC enables application developers to collect, track and analyze telemetry and metrics of real users on any WebRTC application. This is done by including our watchRTC SDK which connects to the testRTC backend and collects the relevant data. Please check out our watchRTC knowledge base to learn more about the features and capabilities of this WebRTC monitoring service.

Installation

via NPM

npm install @testrtc/watchrtc-sdk

via Yarn

yarn add @testrtc/watchrtc-sdk

via CDN

<script src="https://unpkg.com/@testrtc/watchrtc-sdk/lib/index.js"></script>

Usage

Before any of your WebRTC javascript code, you need to include and initialize our SDK.

Inclusion and initialization

The watchRTC.init() needs to take place prior to including or loading any 3rd party SDKs that interact with WebRTC - failing to do so may hinder our ability to collect data. Use the following initialization sequence:

javascript (ES6+)

const watchRTC = require("@testrtc/watchrtc-sdk");
watchRTC.init();

Typescript

import watchRTC from "@testrtc/watchrtc-sdk";
watchRTC.init();

javascript (ES5+)

with CDN

<!doctype html>
<html lang="en">
  <head>
    <title>watchRT SDK</title>
  </head>
  <body>
    <script src="https://unpkg.com/@testrtc/watchrtc-sdk/lib/index.js"></script>
    <script>
      watchRTC.init();
    </script>
  </body>
</html>

Configuration

Before you start, be sure to also read our Getting started with watchRTC guide. Configuring the SDK to connect to the watchRTC backend requires passing the following parameters to the SDK:

rtcApiKey - watchRTC API key, as provided by testRTC
rtcRoomId - an identifier to the session/room/conference. This will enable an analysis of all participants in the same room as a single logical unit. Read more about rooms and peers in watchRTC.
rtcPeerId - an identifier of this peer/user in the session. This will make it easier to identify and troubleshoot users. It is recommended to use non-PII data here as much as possible (no emails or names for example)
keys - (optional) key value object. Used to associate with this peer connection. These can later be searched for or filtered. Read more about keys in watchRTC.
console - (optional) collect browser console log messages. Read more about collecting console logs in watchRTC.
proxyUrl - (optional) secured web socket proxy server address, the proxy server should forward the connection to testRTC's watchRTC servers Based on your application's logic, you can and should pass these configuration parameters at different stages. Read more about Setting up a proxy for watchRTC traffic.
collectionInterval - (optional) the number of seconds in which watchRTC will collect stats. Used until the connection to watchRTC server won't be opened. Read more about collection interval in watchRTC

In the call to the watchRTC.init()
In the call to watchRTC.setConfig()
Upon the creation of an RTCPeerConnection()

via watchRTC.init()

Passing configuration parameters in the init() is the direct/easy way to provide this information. This is useful if you are planning to use a known/specific roomId for this session. The disadvantage of this approach is that it is rigid, and doesn't allow much flexibility. You can call the init() function multiple times, but it will be initialized only on the first call.

watchRTC.init({
  rtcApiKey: "watchRTC API key",
  rtcRoomId: "identifier for the session",
  rtcPeerId: "identifier for the current peer",
  keys: { key1: "value1", key2: "value2" },
  console: { level: "error", override: true },
  proxyUrl: "wss://{your-proxy}",
  collectionInterval: 8,
});

You can call init() multiple times, but it will be initialized only at the first time. Following calls will be ignored.

via watchRTC.setConfig()

You can use watchRTC.setConfig() function to set watchRTC configuration after calling watchRTC.init() and before the creation of RTCPeerConnection objects. This approach is useful if you don't have the information needed in your watchRTC.init() call or when you don't have direct/easy access to the RTCPeerConnection objects (for example, when using a third party CPaaS SDK). If needed, you can pass the rtcApiKey in the watchRTC.init() call while passing the rtcRomId, rtcPeerId and keys in the watchRTC.setConfig() call. You can call this function multiple times, usually whenever a new session/room needs to be created or entered.

watchRTC.setConfig({
  rtcApiKey: "watchRTC API key",
  rtcRoomId: "identifier for the session",
  rtcPeerId: "identifier for the current peer",
  keys: { key1: "value1", key2: "value2" },
  console: { level: "error", override: true },
});

via RTCPeerConnection()

If you have direct access to the RTCPeerConnection object creation, then you can add the necessary configuration parameters there. This gives you the highest level of control over what is done.

var pc = new RTCPeerConnection({
  ...,
  watchrtc:{
    rtcApiKey: "watchRTC API key",
    rtcRoomId: "identifier for the session",
    rtcPeerId: "identifier for the current peer",
    keys: { key1: "value1", key2: "value2" },
  console: { level: "error", override: true }
  }
});

Adding keys

You can also add keys to a room after joining the room. This can be done by calling watchRTC.addKeys() function. Returns a Promise which resolves with an empty object in success case, or with an error property if something went wrong.

keys - These can later be searched for or filtered. Read more about keys in watchRTC.

watchRTC.addKeys({ key1: "value1", key2: "value2" });

Enabling and disabling data collection

When needed, you can temporarily disable data collection. This is important for example if you want to conduct a pre-call test but you aren't interested in collecting that data. For that, you can use watchRTC.enableDataCollection() and watchRTC.disableDataCollection() to control what data you want to send.

Adding user ratings

You can collect the user's feedback as well. This can be done by calling watchRTC.setUserRating(). Returns a Promise which resolves with an empty object in success case, or with an error property if something went wrong.

rating - A number from 1 to 5. You can use it for a 5-stars rating system, or you can use 1 and 5 values only for a like/dislike type of rating system
comment - (optional) Simple string value, collecting user's "verbal" feedback

watchRTC.setUserRating(5, "the best video quality I ever experienced!");

Adding events

You can add your own events to the graphs and event logs. This enables you to monitor specific activity that you are interested in that is outside the generic scope of how WebRTC operates but part of your application logic. This is done by calling watchRTC.addEvent(). Returns a Promise which resolves with an empty object in success case, or with an error property if something went wrong. Read more about adding custom events in watchRTC.

name - The event name. This will be displayed when the event occurred
type - One of the following event types
- "log" - the event will appear only on the event log in the Advanced WebRTC Analytics for the peer
- "local" - the event will be in the event log as well as placed on the peer level charts
- "global" - the event will be in the event log, peer level charts and on the room level charts
parameters - (optional) JSON object to attach to the event. This will appear in the event log

watchRTC.addEvent({ name: "my event", type: "global", parameters: { param1: "value1" } });

Starting version 1.38, events can be associated to a RTCPeerConnection. Here is an example:

const audioPc = new RTCPeerConnection();

// At any time during the call
watchRTC.addEvent({
  name: "muted",
  type: "local",
  parameters: { value: true },
  pc: audioPc,
});

Mapping tracks

By default, watchRTC will assign the SSRC information as the name for incoming channels. You can change these to human-readable format indicating the source of the channels by mapping their streams. This is done by calling watchRTC.mapTrack(trackIdentifier). Read more about mapping streams in watchRTC.

id - the TrackIdentifier to map from in the PeerConnection object
name - the human-readable name to assign and display for it

watchRTC.mapTrack("c085d50a-bb28-4d9f-97b1-86bfc646e5b0", "User A");

Note: The trackIdentifier corresponds to the remote RTCMediaStreamTrack's Id attribute.

Persistent connections and nailup calls

In call center scenarios, there's a feature called persistent connection or nailup call. With it, a WebRTC peer connection is created and maintained, while actual real calls take place on top of that single connection, keeping it open in-between these calls. This is used to reduce call setup times and to reduce the amount of needed signaling messages. You can mark the begining and end of such application specific calls on a persistent connection using watchRTC.persistentStart(rtcRoomId, rtcPeerId) and watchRTC.persistentEnd(). Read more about persistent connections and watchRTC. Note: Make sure to pass new rtcRoomId for next call in order to separate sessions.

Open/Close connection to server

By default, watchRTC SDK will automatically establish a connection with the watchRTC server and close it after an idle period. At times, it might make sense for your application to manually open and close that connection explicitly. This is done by calling watchRTC.connect() and watchRTC.disconnect(). Read more about manually connecting/disconnecting to watchRTC servers.

watchRTC.connect();
watchRTC.disconnect();

Collect WebRTC statistics (BETA)

Be careful, this API is in beta. API and content could change in future releases. Once a call is established, WatchRTC exposes WebRTC statistics collected from the existing RTCPeerConnections. Accessing to these statistics can be done by adding a listener from the application.

const statsListener = (stats) => {
  // Called each time new statistics are available
};
watchRTC.addStatsListener(statsListener);

Each time new statistic are available, the listener will be called with a JSON object containing the statistics. The JSON object contains 2 main properties:

connections: Which lists the connections (based on the RTCPeerConnection used) and the properties associated to each connection,
streams: Which lists all the streams involved in the call

For each connection in connections, the following properties are available:

connection: String value. Can be one of direct or relay,
transport: String value. Can be one of udp, tcp or tls,
address: String value using format 'address:port'. This is the remote IP address and port,

For each stream in streams, the following properties are available:

peerID: String value. This is the ID of the associated connection,
kind: String value. Can be one of audio or video,
direction: String value. Can be one of inbound or outbound,
mappedName: String value. The name given when calling mapTrack and associated with this stream. null by default,
codec: The name of the codec used,
jitter: Number in seconds. Average during the last interval. Null if not available,
roundTripTime: Number in seconds. Average during the last interval. Null if not available,
bytesReceived: (Inbound streams only). Number of bytes received during the last interval. Null if not available,
bytesSent: (Outbound streams only). Number of bytes sent during the last interval. Null if not available,
packetsReceived: (Inbound streams only). Number of packets received during the last interval. Null if not available,
packetsSent: (Outbound streams only). Number of packets sent during the last interval. Null if not available.
packetsLost: Number of packets sent or received that has been lost during the last interval. Null if not available,
packetsLoss: Percent of packets sent of received that has been lost during the last interval. Null if not available,
bitrate: Number of bits sent or received per second. Average during the last interval. Null if not available,
frameWidth: (Video streams only). Number of pixels for the width of the video. Null if not available,
frameHeight: (Video streams only). Number of pixels for the height of the video. Null if not available,
framerate: (Video streams only). Number of frame per second. Null if not available,

Note: To stop receiving the statistics, pass null to the addStatsListener function. The existing listener will be unsubscribed and removed.

Listen to the SDK's connectivity state

Once the watchRTC SDK is initialized, it will report its state changes. Listening to the state can be done by adding a listener from your application.

const stateListener = (state) => {
  // Called each time SDK state is changed
};
watchRTC.addStateListener(stateListener);

Each time the state changes, the listener will be called with a JSON object containing new state. The JSON object contains 1 property:

connectionStatus: String value. Can be one of connected or disconnected,
reason: String value (Optional, only when connectionStatus is disconnected). The reason of the state change. Can be one of clientRejectedNoRetry, disconnectedPrematurely, cantConnectToServer, serverRejectedNoRetry or applicationDisconnected.

Here is some additional information about the reasons:

clientRejectedNoRetry: The SDK has been disconnected because the configuration was incorrect. This can happen when the fields rtcApiKey, rtcRoomId or rtcPeerId are missing. The SDK will not try to reconnect automatically.
disconnectedPrematurely: The SDK has been disconnected because the connection was lost. It will automatically try to reconnect using an exponential backoff mechanism.
cantConnectToServer: The SDK is disconnected and has failed to connect. It will try to reconnect automatically using an exponential backoff mechanism.
serverRejectedNoRetry: The SDK has been disconnected because the server has rejected the connection. This can happen when the authentication using the rtcApiKey fails. The SDK will not try to reconnect.
applicationDisconnected: The SDK has been disconnected because the application has called the disconnect method or because the SDK automatically disconnects when all peer-connections have been closed. The SDK will not try to reconnect automatically.

Note: To stop listening, pass null to the addStateListener() function. The existing listener will be unsubscribed and removed.

qualityRTC integration

If you have licensed qualityRTC, then you can also conduct ad-hoc network tests to your agents and users as an integral part of your application, to quickly understand and troubleshoot WebRTC connectivity and quality issues.

Learn more about qualityRTC SDK.

Usage

  const progressCallback = (progress: number) => {
    console.log(`runNetworkTest progressCallback ${progress}%`, {});
  }

  const runNetworkTest = async (testName: string) => {
    const answer = await watchRTC.qualityrtc.run({
        options: {
            // run: "Location",
            // any other parameter from https://support.testrtc.com/hc/en-us/articles/8428284359823-URL-parameters-in-qualityRTC
        },
        progressCallback
    });

    // any time can call stop to stop the test
    // watchRTC.qualityrtc.stop();


    // answer is in the format described in https://support.testrtc.com/hc/en-us/articles/8428324242319-Webhook-support-in-qualityRTC
    console.log(`runNetworkTest answer`, answer);
  }

Samples

Additional samples on how to integrate the watchRTC SDK can be found on our official GitHub repository: https://github.com/testRTC/sample-Twilio-video-app-React-TypeScript-watchRTC

Changelog

1.41.1 (November 27, 2024)

official release

1.41.1-beta.8 (Nov 18, 2024)

Fix crash happened when parsing the userAgentData properties

1.41.1-beta.7 (Nov 7, 2024)

Send "reconnect" event to display it on peer level

1.41.1-beta.6 (Oct 23, 2024)

Better detection of cases where several input or output devices are added or removed in a simulated manner
Fix TestRTC Companion timeouts.
Fix error reporting if websocket connection can not be established

1.41.1-beta.5 (Oct 16, 2024)

Better identify Windows version 11 when using Chromium-based browsers.
Better identify macOS version when using Safari

1.41.1-beta.4 (Oct 11, 2024)

Better handling of websocket status codes
Detect when devices are plugged or unplugged from the system.

1.41.1-beta.3 (Oct 1, 2024)

Fix crash happened on WebSocket connection error.
Fix userAgentData message to correctly detect the name and version of the OS used when on iPad.
testRTC Companion integration.

1.41.1-beta.2 (Sept 14, 2024)

Send a new message userAgentData containing the Client Hints information if available.

1.41.1-beta.1 (Sept 07, 2024)

Keep a full raw stats when the initial connection to TestRTC can't be done during more than 10 minutes.
Fix console logs override that prevented the SDK from collecting and sending internal logs
Remove the Chrome colored syntax from the logs sent to the server. Traces displayed in TestRTC should be more readable.
Rephrase the console logs to better distinguish error cases and to improve readability.

1.40.1 (August 26, 2024)

official release

1.40.1-beta.6 (August 19, 2024)

Avoid reconnecting automatically when the connect() method has been called and when the last active peer-connection has been closed manually.

1.40.1-beta.5 (July 03, 2024)

Avoid reconnecting to the server when there are several peer-connections locally. Don't trigger a new connection to the server for closed peer-connections.
Fix internal track listener for incoming tracks that prevented the peer-connection from being released properly.

1.40.1-beta.4 (Jun 13, 2024)

Fix crash when referencing local tracks

1.40.1-beta.3 (Jun 12, 2024)

Documented the interface for qualityRTC.

1.40.1-beta.2 (Jun 12, 2024)

Release the internal listeners on local tracks when the RTCPeerConnection is closed to let the garbage collector remove this peer-connection properly

1.40.1-beta.1 (Jun 4, 2024)

Send new parameter newConnection on WS handshake to detect new connection from reconnecting.

1.39.2.beta-2 (May 27, 2024)

add mapPC function to map peer connection to human-readable names.

1.39.2.beta-1 (May 17, 2024)

When reconnecting, avoid starting extra reconnection attempts for new peer-connections or when the peer-connections state changes.

1.39.1 (May 8, 2024)

official release

1.39.1.beta-13 (May 8, 2024)

performance improvements

1.39.1.beta-12 (May 7, 2024)

add log to detect potential data queued in websocket buffer and not sent when the websocket generates an error

1.39.1.beta-11 (May 2, 2024)

remove the limit on the maximum of attempts for the first connection added in 1.39.1.beta-10
fix the timeout issue that cause reconnection too often
update default URLs to watchRTC server
enabled channels splitting by default

1.39.1.beta-10 (Apr 29, 2024)

for the first connection, the SDK limits the number of attempts to 15 and then stops trying to connect
for the first connection, when all attempts have failed, the SDK sets the reason field to cantConnectToServerMaxAttemptsNoRetry
each attempt is aborted after a timeout of 15 seconds

1.39.1.beta-9 (Apr 29, 2024)

add a browser log when the SDK is disconnected

1.39.1.beta-8 (Apr 22, 2024)

add an incremental identifier to each webrtc report collected
send a nostats message when statistics reports are not sent to the server

1.39.1.beta-7 (Apr 9, 2024)

fix for "rejoined user second part of call is dropped" case

1.39.1.beta-6 (Mar 18, 2024)

add sessionId as common identifier for client

1.39.1.beta-5 (Mar 13, 2024)

allow to reconnect the Websocket in case of a "nail up" call join

1.39.1.beta-4 (Feb 27, 2024)

improvements in qualityRTC implementation

1.39.1.beta-3 (Feb 20, 2024)

add a reason field to the state listener when the connection status is disconnected

1.38.3 (Feb 14, 2024)

official release

1.39.1.beta-2 (Jan 26, 2024)

use an exponential backoff when trying to reconnect to the server

1.39.1.beta-1 (Jan 24, 2024)

add "data channels" mechanism too improve analyzing performance

1.38.3.beta-2 (Jan 18, 2024)

set default log level to "info"

1.38.3.beta-1 (Jan 18, 2024)

disable debug logs by default
fixed call stack size issue in clock synchronization mechanism
flush the buffer to avoid missing events when the socket is closed
collect first statistics earlier

1.38.2 (Dec 27, 2023)

official release with working qualityRTC-SDK

1.38.2.beta-1 (Dec 19, 2023)

fix cors issue for qualityRTC SDK API requests.

1.38.1 (Dec 12, 2023)

official release

1.38.1.beta-4 (Dec 8, 2023)

first getStats message does not get captured

1.38.1.beta-3 (Dec 6, 2023)

added server side compatibility.
fixed statsListener to allow passing null to remove the callback

1.38.1.beta-1 (Nov 9,2023)

Add more debug logs

added debug logs which makes it easier to track down issues related peer connection override, missing getStats API data and websocket reconnection.
added timestamp prefix when collecting console logs.

1.38.0.beta-5 (Oct 18, 2023)

fix "flush any data that is older than the last 10 minutes" logic, which would cause missing events

1.38.0.beta-4 (Oct 16, 2023)

add more info about "close" event log in debug mode
"nailUpCallEnd" log message does not include timestamp, which can cause incorrect time calculations

1.38.0.beta-3 (Oct 09, 2023)

add logLevel configuration property to give more control over logs on SDK initialization
deprecated debug configuration property in favor of logLevel
flush any data that is older than the last 10 minutes and not send it to the server before first connection with server

1.38.0.beta-2 (Sep 28, 2023)

removed track.mute and track.unmute events to minimize messages in logs in the case of large rooms or for peers with large number of channels.
better handling nail-up calls by calculating a report used as reference each time a call to persistentStart() is done. This avoids the initial spike in graphs.

1.38.0.beta-1 (Aug 28, 2023)

added pc property in addEvent to associate the event to an existing RTCPeerConnection
stop logging credentials of iceServer configuration

1.37.0.beta-3 (Jul 19, 2023)

Bug fixes

added codec in statsListener
fixed wrong message displayed in the console when configuration parameters have been set via RTCPeerConnection
better handling events on tracks to avoid removing application listeners

1.37.0.beta-1 (May 12, 2023)

Bug fixes

better handling collection interval mismatch case

1.36.3 (Apr 5, 2023)

removed getStats logs in debug mode to reduce resources usage
added logGetStats configuration property to enable getStats logs if needed

1.36.2 (Feb 21, 2023)

Added collectionInterval to the configuration, to deal with connectivity related edge cases. Read more about collection interval in watchRTC

1.36.1 (Feb 20,2023)

Add more debug logs

added debug logs for persistentStart and persistentEnd methods

1.36.0 (Feb 16,2023)

Handle NailUp calls behaviour

Added internal global sessionId
Use watchRTC.persistentStart(rtcRoomId, rtcPeerId) and watchRTC.persistentEnd() to start/stop nail up call. Make sure to pass new rtcRoomId for next call in order to separate sessions.

Deprecation methods

watchRTC.mapStream() method is deprecated and should be replaced by watchRTC.mapTrack()

New features

watchRTC.mapTrack() was added
Property mappedName added to the statsListener which contains the name associated to the stream.

1.35.3 (Dec 6, 2022)

New features

watchRTC.addStateListener() was added

1.35.2 (Nov 8, 2022)

Fixed media soup compatibility issues
Fixed console logs not beeing collected in case of "early" setConfig

1.35.0 (Sep 26, 2022)

Fixed bugs around "override console" feature
Improved SDK stability

1.35.0-beta.2 (Sep 12, 2022)

Bug fixes

Better handle "Converting circular structure to JSON" error when override console

1.35.0-beta.1 (Aug 25, 2022)

New features

Console warning if RTCPeerConnection object has been overriden before sdk initialization

1.34.1-beta.14 (July 22, 2022)

New features

Add support for multiple server versions

1.34.1-beta.12 (July 22, 2022)

Bug fixes

Add new debug log for "getStats" method

1.34.1-beta.10 (July 12, 2022)

Bug fixes

Handle "Converting circular structure to JSON" error when override console

1.34.1-beta.7 (July 8, 2022)

Bug fixes

HTTP trace did not work if websocket connection was not established in the first place

1.34.1-beta.5 (July 6, 2022)

Bug fixes

Console override now happens only if console logs are requested to be collected
When getstats timestamp property was provided as a string, data compression failed to work
Sometimes RTCRemoteInboundRTPAudio and RTCRemoteInboundRTPVideo reports were missed, resulting in a gap at the beginning of our chart data
addEvent now works more accurately for events captured before the websocket connection was established to the watchRTC server

1.33.6 (June 8, 2022)

New features

You can now collect console logs using the SDK. Read more about Collecting console logs in watchRTC
The SDK now tries to reconnect if it loses its connection to the watchRTC server
We now queue custom events if the SDK isn't connected to the server. These get sent to the server once a connection is available
You can now open/close the connection to server manually. Read more about manually connecting/disconnecting to watchRTC servers
You can now await on the following SDK methods: addKeys(), setUserRating(), addEvent(). These methods now return a Promise which resolves with an empty object on success case, or with an error property if something went wrong

1.30.8 (February 15, 2022)

Bug fixes

We now capture getUserMedia failures as well. These will be collected and reported if a peer connection object is created by the application

1.30.7 (February 14, 2022)

Bug fixes

Sometimes watchRTC froze when initiating a session. That has been fixed

1.30.6 (November 19, 2021)

New features

Added support for custom keys with multiple values
watchRTC.addEvent() now also supports parameters

1.30.5 (November 19, 2021)

New features

watchRTC.mapStream() was added. Read more about mapping streams in watchRTC
watchRTC.addEvent() was added. Read more about events in watchRTC
icecandidateerror() events are now collected by the SDK
RTCRtpSender.setParameters() calls are now collected by the SDK
Added support for parameterless setLocalDescription() calls

1.30.4 (October 12, 2021)

Fixed data collect when using Firefox
Fixed a CSP warning by making the watchRTC SDK self-suficient without any external dependencies

1.30.3 (October 5, 2021)

Updated the readme

1.30.2 (October 3, 2021)

Bug fixes

The SDK now doesn't collect WebRTC API calls into the event log twice

1.30.0 (September 26, 2021)

New features

watchRTC.addTags() was deprecated. We no longer support tags. These have been replaced with a key/value system
watchRTC.addKeys() was added. Read more about keys in watchRTC

1.29.2 (July 22, 2021)

New features

watchRTC.addTags() was added
watchRTC.setUserRating() was added