JSPM

@testrtc/watchrtc-sdk

1.30.3
    • ESM via JSPM
    • ES Module Entrypoint
    • Export Map
    • Keywords
    • License
    • Repository URL
    • TypeScript Types
    • README
    • Created
    • Published
    • Downloads 9233
    • Score
      100M100P100Q154945F
    • License ISC

    Monitor your WebRTC application by collecting WebRTC statistics from end users

    Package Exports

    • @testrtc/watchrtc-sdk

    This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@testrtc/watchrtc-sdk) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

    Readme

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

    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!");

    Initialize SDK. Can be called multiple times but it will be initialized only at the first time.

    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