Using custom keys in watchRTC

When you connect a session with watchRTC, you provide a roomId and a peerId. Oftentimes, this isn’t enough to offer the context you need. To compensate for that, watchRTC includes a custom keys mechanism which enables you to add whatever values you want to that peerId. This information can be your own internal index values, a specific client location, user type (doctor and patient for example) or anything else you see fit.

There are a few things to know about custom keys before you use them:

1. The keys must be defined in advance
2. Keys are defined for either search or search and aggregation

More on this below.

Since there are multiple ways to set keys, then you should understand and decide which one to use in your application.

Setting keys in watchRTC.init() is simple and straightforward. The challenge here is that init() should be called relatively quickly, and at that point you might not have the values at hand. A better approach would be to use either setConfig() or addKeys().

Calling watchRTC.setConfig() makes sense when you want the custom keys and their values to be persistent between sessions. If your web page allows joining and leaving multiple separate sessions, then keys and values passed in setConfig() will be maintained across these sessions.

Calling watchRTC.addKeys() is specific to the current active session only. It doesn’t “survive” closing the session and opening a new one – in such a case, the keys passed won’t make it to the next session (where as init() and setConfig() would). Calling addKeys() also overrides any previous values given to these custom keys throughout the duration of the current session.

For a peer, you can set multiple values for the same key.

This is useful for example, if you’d like to indicate which media servers your peer is connected to and you can connect to multiple servers concurrently.

watchRTC.addKeys({ single: "value1", multiple: ["value2_1", "value2_2"] });

In the example above, a custom key called single gets the value of value1 while a custom key called multiple gets two values: value2_1 and value2_2.

If you want to use custom keys, you will need to contact our support and indicate what keys you wish to use.

During that process, we will configure on your account the keys you need.

There are two types of keys:

1. Searchable – searchable custom keys are keys that you can use to search for a certain peerId. They don’t need to have unique values, but should not have many peers with the same value either. These are best used to correlate between information you know on your end and sessions you’d like to review on watchRTC
2. Aggregable – aggregable custom keys are keys that can be used to filter data in Highlights and Trends dashboards. These are great when you want to understand how certain users, devices, locations, etc behave versus the rest of your population

Custom keys are a simple yet powerful tool. They can be used in many different ways.

Here’s some ways that we’ve seen our clients make use of them:

1. Determine the user’s role in a session. For example, DOCTOR and PATIENT
2. Assign to a specific customer account, for those who have large customers
3. Indicate which media server instance the session connected to
4. Use for report creation in aggregate
5. Add peer or room specific metadata: name, internal identifier, etc
6. A/B testing