@testrtc/watchrtc-sdk NPM

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 identifer 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 - key value object. Used to associate with this peer connection. These can later be searched for or filtered. Read more about keys 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.

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

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

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

Adding keys

You can also add keys to a room after joining the room. This can be done by calling watchRTC.addKeys() function.

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

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 a 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(). 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" } });

Mapping streams

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.mapStream('). Read more about mapping streams in watchRTC.

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

watchRTC.mapStream("lyk0zS1eyvZfJRLis3OIwBx3UvH3:oxrhEtb3sV7VutbQ:video", "User A");

Samples

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

Changelog

1.29.2 (July 22, 2021)

New features

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

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