Support & information center

Installing the watchRTC JavaScript SDK

Table of contents

Introduction

watchRTC requires you to integrate an SDK with your own running code. For that purpose, you will need to add the watchRTC JavaScript SDK to your JS application

To start using the watchRTC JavaScript SDK library to collect WebRTC-related data from your web application, you need to perform a few basic tasks first. Then you can begin to log and analyze your data.

For integration with the SDK, you will first need to have a watchRTC API key. If you haven’t already done so, please make sure to create a watchRTC API key before you continue.

Install the SDK

Add the watchRTC JS SDK to your JS application using one of the following methods.

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>

Initialize the SDK

Once installed, to initialize our SDK, add the following setup code in your application, prior to using WebRTC APIs. To do this, use one of the following initialization sequences:

Note: 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!

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>

Once initialized, find where you create peer connections in your code and pass along the additional parameters necessary.

Configuring the SDK

Configuring the SDK to connect to the watchRTC backend involves passing specific parameters. These parameters are essential for setting up your SDK correctly. These parameters are all mandatory unless marked otherwise. Here’s an explanation of each parameter:

  • rtcApiKey: This is your watchRTC API key. If you haven’t already done so, please make sure to create a watchRTC API key before you continue
  • rtcRoomId: Think of this as a virtual room or session identifier. It groups all participants in the same room together, making it easier to analyze their interactions. Read learn more about rooms and peers in watchRTC
  • rtcPeerId: This is an identifier for the individual within a session. It helps identify and troubleshoot specific users. It’s a good practice to avoid using PII (Personally Identifiable Information) like emails or names
  • keys (optional): This is a key-value object that can be associated with the peer connection. These keys can later be used for searching or filtering purposes. It’s an optional parameter. Read more about keys in watchRTC
  • console (optional): If you set this option, it allows you to collect browser console log messages, which can be useful for debugging. This is also an optional parameter. Read more about collecting console logs in watchRTC
  • proxyUrl (optional): This parameter is for specifying a 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. It’s optional, but it’s important for setting up a proxy for watchRTC traffic. Read more about Setting up a proxy for watchRTC traffic
  • collectionInterval (optional): This determines the frequency in seconds at which watchRTC will gather statistics. It remains active until your SDK establishes a connection to the watchRTC server. Once the connection is made, the collection interval setting no longer applies. Read more about collection interval in watchRTC

How to pass parameters

Now, let’s discuss how and when to pass these configuration parameters. There are three methods to choose from:

In the call to watchRTC.init() This is the easiest and most direct way to provide configuration information. It’s suitable when you have a specific room in mind for the session. However, it’s less flexible. You can call init() multiple times, but it will be initialized only on the first call. Here’s how you can do it:

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

via watchRTC.setConfig() This method is useful when you don’t have all the necessary information in your watchRTC.init() call or when you can’t directly access the RTCPeerConnection objects. It allows you to set watchRTC configuration after initializing. You can call this function multiple times, typically when a new session or room needs to be created or entered. Example:

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, you can add the necessary configuration parameters there. This provides the highest level of control. Example:

var pc = new RTCPeerConnection({
  // Other RTCPeerConnection parameters,
  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 }
  }
});

Usage

Open/Close connection to the server

By default, the watchRTC JavaScript 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();

Some things to remember:

Was this article helpful?

Yes ↑ No ↓

Related Articles