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
-
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:
-
javascript (ES6+)
const watchRTC = require("@testrtc/watchrtc-sdk"); watchRTC.init();
-
Typescript
import watchRTC from "@testrtc/watchrtc-sdk"; watchRTC.init();
-
javascript (ES5+)Using 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:
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,
});
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 },
});
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().
watchRTC.connect();watchRTC.disconnect();
Read more about manually connecting/disconnecting to watchRTC servers.
Some things to remember:
- Once installed and initialized, you should decide on how to allocate rooms and peers
- There are more configuration settings available. These are documented on the watchRTC SDK installation page.
- If you don’t see any results, you can try to troubleshoot it yourself.
- View the Changelog to stay up to date with recent changes that may affect your use of the SDK.