Narcissistic Pickle Meister

    @testrtc/watchrtc-sdk
    TypeScript icon, indicating that this package has built-in type declarations

    1.33.6 • Public • Published

    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 - (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 consoel 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.
    1. In the call to the watchRTC.init()
    2. In the call to watchRTC.setConfig()
    3. 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}"}
    });

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

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

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

    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

    1.30.2 (October 3, 2021)

    Bug fixes

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

    1.30.3 (October 5, 2021)

    • Updated the readme

    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.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.6 (November 19, 2021)

    New features

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

    1.30.7 (February 14, 2022)

    Bug fixes

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

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

    Install

    npm i @testrtc/watchrtc-sdk

    DownloadsWeekly Downloads

    2,151

    Version

    1.33.6

    License

    ISC

    Unpacked Size

    456 kB

    Total Files

    12

    Last publish

    Collaborators

    • mulyoved
    • muly