This is the repo for the PeerMetrics JS SDK.
Peer metrics is a service that helps you collect events and metrics for your WebRTC connections.
You can read more about the service on peermetrics.io.
To use the sdk you can install the package through npm:
npm install @peermetrics/sdkThen
import { PeerMetrics } from '@peermetrics/sdk'Or load it directly in the browser:
<script src="//cdn.peermetrics.io/js/sdk/peermetrics.min.js"></script>To use the sdk you need a peer metrics account. Once you've created an organization and an app you will receive an apiKey
let peerMetrics = new PeerMetrics({
apiKey: '7090df95cd247f4aa735779636b202',
userId: '1234',
userName: 'My user',
conferenceId: 'conference-1',
conferenceName: 'Conference from 4pm',
appVersion: '1.0.1'
})
// initialize the sdk
await peerMetrics.initialize()In order to start tracking a connection, use the .addConnection() method:
let pc1 = new RTCPeerConnection({...})
await peerMetrics.addConnection({
pc: pc1,
peerId: '1' # any string that helps you identify this peer
})To instantiate the sdk you have the following options:
let peerMetrics = new PeerMetrics({
// the api key associated to the app created inside your account
apiKey: '', // String, mandatory
// a string that will help you indentify this user inside your peer metrics account
userId: '1234', // String, mandatory
// a readable name for this user
userName: 'My user', // String, optional
// an ID to identify this conference
conferenceId: 'conference-1', // String, mandatory
// a readable name for this conference
conferenceName: 'Conference from 4pm', // String, optional
// the version of your app. this helps you filter conferecens/stats/issues for a specific version
appVersion: '0.0.1', // String, optional
// if the sdk can't be run on the other side of the call (for example a SFU) you can still collect some stats for that using this flag
remote: true, // Boolean, optional, Default: true
// Object, optional: if you would like to save some additional info about this user
// there is a limit of 5 attributes that can be added. only string, number, boolean supported as values
meta: {
isRegistered: true,
plan: 'premium'
},
// if you would like to save events from some page events
pageEvents: {
pageVisibility: false // when the user focuses on another tab
}
})Used to initialize the SDK. Returns a promise that rejects if any problems were encountered (for example invalid apiKey, over quota, etc)
Used to integrate with different SDKs. See here list for options.
Adds a connection to the watch list.
options
{
`pc`: pc, // RTCPeerConnection instance
`peerId`: 'peer-1' // String, a unique Id to identify this peer
}Note: Monitoring of a peer will automatically end when the connection is closed.
The helper method stops listening to events on all connections and also ends the current session of this user.
This is useful for the case when multiple conferences happen consecutively without the user refreshing the page.
Stop listening for events on a specific connection.
options can be one of two options:
{
'connectionId': '123' // the one returned after calling `.addConnection()`
}OR
{
'pc': pc // the `RTCPeerConnection` instance
}Stop listening for events/stats on all the connections for this peer
Add a custom event for this participant. Example:
{
eventName: 'open settings',
description: 'user opened settings dialog'
}object doesn't require a specific structure, but if the eventName attribute is present, it will be displayed on the event timeline in your dashboard.
This helps you get a better context of the actions the user took that might have impacted the WebRTC experience.
Save event that user muted/unmuted the microphone
Method used to get the peer metrics page url for a conference or a participants. Useful if you would like to link to one of these pages in your internal website/tool.
await PeerMetrics.getPageUrl({
apiKey: 'you-api-key', // mandatory
userId: 'my-user-id', // the userId provided to peer metrics during a call
// or
conferenceId: 'confence-id' // an ID provided for a past conference
})You can use PeerMetrics with many well known WebRTC SDKs.
In order to integrate you can initialize the SDK as usually and then call .addSdkIntegration() with special options:
let peerMetrics = new PeerMetrics({
apiKey: '7090df95cd247f4aa735779636b202',
userId: '1234',
userName: 'My user',
conferenceId: 'room-1',
conferenceName: 'Call from 4pm'
})
// initialize the SDK
await peerMetrics.initialize()
// call addSdkIntegration() with the appropriate options for each SDK
await peerMetrics.addSdkIntegration(options)
// That's itThe options object differs depending on the integration.
Note: There's no need to call addConnection() anymore, the PeerMetrics SDK will take care of adding connection listeners and sending events.
To integrate with LiveKit' js sdk you need to pass an instance of Room.
Note You need at least version v0.16.2 of livekit-client.
import { Room } from 'livekit-client'
const room = new Room(roomOptions)
peerMetrics.addSdkIntegration({
livekit: {
room: room, // mandatory, the livekit client Room instance
serverId: '', // string, optional, an ID to indentify the SFU server the user connects to (default: livekit-sfu-server)
serverName: '' // string, optional, a more readable name for this server (default: LiveKit SFU Server)
}
})You can integrate with v2 of Twilio Video SDK. To do that, you need to pass the instance of Room. For example:
import Video from 'twilio-video'
Video.connect('$TOKEN', { name: 'room-name' }).then(room => {
peerMetrics.addSdkIntegration({
twilioVideo: {
room: room, // mandatory, the twilio video Room instance
}
})
})To integrate with mediasoup you need to pass in the device instance:
import * as mediasoupClient from 'mediasoup-client'
let device = new mediasoupClient.Device({
handlerName : this._handlerName
})
peerMetrics.addSdkIntegration({
mediasoup: {
device: device, // mandatory, the mediasoupClient.Device() instance
serverId: '', // string, optional, an ID to indentify the SFU server the user connects to (default: mediasoup-sfu-server)
serverName: '' // string, optional, a more readable name for this server (default: MediaSoup SFU Server)
}
})If you are using the Janus javascript sdk to create connections to Janus server, you can integrate by sending the plugin handler that result from calling .attach(). First thing:
let peerMetrics = new PeerMetrics({
...
})
await peerMetrics.initialize()And then:
let janus = new Janus({
server: server,
success: function() {
// Attach to VideoCall plugin
janus.attach({
plugin: "janus.plugin.videocall",
opaqueId: opaqueId,
success: function(pluginHandle) {
peerMetrics.addSdkIntegration({
janus: {
plugin: pluginHandle, // mandatory
serverId: '', // string, optional, an ID for this SFU server (default: janus-sfu-server)
serverName: '' // string, optional, a more readable name for this server (default: Janus SFU Server)
}
})
...
}
})
}
})To integrate with Vonage SDK (previously Tokbox) you will need to load PeerMetrics before it. For example:
<!-- First we need to set a special global option -->
<script>
var PeerMetricsOptions = {
wrapPeerConnection: true
}
</script>
<!-- Load the sdk -->
<script src="//cdn.peermetrics.io/js/sdk/peermetrics.min.js"></script>
<!-- Then setup PeerMetrics. This can alse be done later, but before calling OT.initSession() -->
<script>
(async () => {
let peerMetrics = new PeerMetrics({
...
})
await peerMetrics.initialize()
peerMetrics.addSdkIntegration({
vonage: true
})
})()
</script>
<!-- Load the OpenTok sdk -->
<script src="https://static.opentok.com/v2/js/opentok.min.js"></script>To integrate with Agora SDK you will need to load PeerMetrics before it. For example:
<!-- First we need to set a special global option -->
<script>
var PeerMetricsOptions = {
wrapPeerConnection: true
}
</script>
<!-- Load the sdk -->
<script src="//cdn.peermetrics.io/js/sdk/peermetrics.min.js"></script>
<!-- Then setup PeerMetrics. This can alse be done later, but before calling OT.initSession() -->
<script>
(async () => {
let peerMetrics = new PeerMetrics({
...
})
await peerMetrics.initialize()
peerMetrics.addSdkIntegration({
agora: true
})
})()
</script>
<!-- Load the Agora sdk -->
<script src="https://download.agora.io/sdk/release/AgoraRTC_N.js"></script>Or, if you are using a bundler:
import { PeerMetrics } from '@peermetrics/sdk'
// call wrapPeerConnection as soon as possible
PeerMetrics.wrapPeerConnection()
let peerMetrics = new PeerMetrics({...})
await peerMetrics.initialize()
peerMetrics.addSdkIntegration({
agora: true
})Integrating with Pion is dead simple. If for example you are using ion sdk js, just initialize peer metrics first and you are good to go:
import { Client, LocalStream, RemoteStream } from 'ion-sdk-js';
import { IonSFUJSONRPCSignal } from 'ion-sdk-js/lib/signal/json-rpc-impl';
import { PeerMetrics } from '@peermetrics/sdk'
let peerMetrics = new PeerMetrics({...})
await peerMetrics.initialize()
peerMetrics.addSdkIntegration({
pion: true
})
// then continue with the usual things
const signal = new IonSFUJSONRPCSignal("wss://ion-sfu:7000/ws");
const client = new Client(signal);
signal.onopen = () => client.join("test session", "test uid")You can pass additional details to addSdkIntegration() to better identify the SFU server the user is connecting to:
peerMetrics.addSdkIntegration({
pion: {
serverId: 'pion-sfu-na',
serverName: 'Pion SFU North America'
}
})To integrate with SimplePeer you would just need to pass the RTCPeerConnection to PeerMetrics. For example:
var peer = new SimplePeer({
initiator: true,
config: iceServers,
stream: stream,
trickle: true
})
peerMetrics.addConnection({
pc: peer._pc,
peerId: peerId
})Right now, the SDK is compatible with the latest version of Chromium based browsers (Chrome, Edge, Brave, etc), Firefox and Safari.
If you app permits the user to have multiple calls on page you'll need to initialize the PeerMetrics instance every time.
For example:
-
On page load initialize the SDK as mentioned in the docs
let peerMetrics = new PeerMetrics({ apiKey: '7090df95cd247f4aa735779636b202', userId: '1234', userName: 'My user', conferenceId: 'conference-1', conferenceName: 'Conference from 4pm', appVersion: '1.0.1' })
-
Call
initialize()await peerMetrics.initialize()
-
Call
addConnection()or if you use one of our SDK integration, follow the steps for that specific caseawait peerMetrics.addConnection({ pc: pc1, peerId: '1' # any string that helps you identify this peer })
-
At the end of the current call/conference, call
.endCall()await peerMetrics.endCall()
-
To start monitoring again, call
initialize()again with details for the new conferenceawait peerMetrics.initialize({ conferenceId: 'conference-2', conferenceName: 'Second Conference', })
-
Continue from step
3
MIT