Search

Canary Documentation

Updated: Aug 17


1. Integration


1.1. Quickstart


Simply add our code snippet to the very top of your main HTML. We collect and stream metrics straight from the client browser to our server - don't worry, it's encrypted!


To get you up and running quickly, here's the "vanilla" setup:


1.2. Custom setup


1.2.1. Parameter overview

For finer tuning, we offer some customization options. One of them - appID - must be set in the initialize() function in our code snippet and cannot be reset later on; note that initialize() may only be called once, and that RTCanary will not start until it is called. Four others - sendStatsInterval, sendBufferedRecordsInterval, requestLocation, and p2pManageLoad - may be set in initialize() or left out, in which case they take on a default value, but also cannot be set or reset later. The other three - sessionID, peerID, and isTestSession - may be set or reset after the initialize() function gets called; the functions provided to do this are described below. Note that data collection will start immediately after initialize() is called, but messages will only be sent to the server once appID, sessionID, and peerID are set.


appID

  • string

  • we provide this for you

sessionID

  • string

  • unique identifier for the current session (e.g. room ID and start timestamp)

  • Set or reset this in order to start a new session by calling RTCanary.startNewSession(sessionID, isTestSession), where isTestSession is an optional boolean (it defaults to false if left out).

isTestSession

  • boolean - optional (default false)

  • set to true to mark session as a test session

  • Set or reset this while starting a new session by calling RTCanary.startNewSession(sessionID, isTestSession).

peerID

  • string

  • username or similar

  • Set or reset this by calling RTCanary.setPeerID(peerID).

sendStatsInterval

  • number - optional (default 5000)

  • milliseconds between data collection events

  • It is not recommended to set sendStatsInterval to less than 200 milliseconds, or to less than one-tenth of sendBufferedRecordsInterval.

sendBufferedRecordsInterval

  • number - optional (default 15000)

  • milliseconds between sends to server

requestLocation

  • boolean - optional (default false)

  • set to true to ask user for geolocation

p2pManageLoad

  • boolean - optional (default false)

  • set to true to dynamically adjust sendStatsInterval based on the number of peer connections - useful for reducing load on P2P platforms


1.2.2. Setter methods

Below are further details on the two setter methods described above.


RTCanary.startNewSession(sessionID, isTestSession)

  • Arguments

  • sessionID: string - required.

  • isTestSession: boolean - optional (default false).

  • This function is not required to start a new session! If a sessionID is passed into initialize(), it will start automatically. This function is for starting a session AFTER initialize() has been called.

  • Calling this function will start a new session with the passed-in sessionID. This is useful if a user joins a room after initialize() has been called. If this is called with the same sessionID as immediately before, RTCanary will assume this is unintentional and gracefully terminate itself in order to maintain data sanitation.

RTCanary.setPeerID(peerID)

  • Arguments

  • peerID: string - required.

  • This function will set the peerID for future outgoing messages to the passed-in argument. Note that all the peerID assigned to each message in the buffer will be renamed as well.


1.2.3. Parameter properties summary

Below is a quick reference containing the parameters and methods noted above, as well as the names of the getter methods. You can use the provided getter methods to get and setter methods to set (or reset) these parameters anywhere in your source code that is referenced below ours in your html file.


1.2.4. Example

Below is a setup for a situation in which peerID is not yet known at page load. In this situation, it is not set in initialize() - rather, it must be set later on in your own code using the setter method before any messages get sent to the server. This setup also sets sendStatsInterval to 500 milliseconds, sendBufferedRecordsInterval to 30 seconds, and each of requestLocation, isTestSession, and p2pManageLoad to true. These override the default values. As described above, you may also use RTCanary.startNewSession() to reset sessionID and isTestSession later on in your own code in order to start a new session with the new ID you pass in.


1.2.5. Details and notes

1.2.5.1. Initializing RTCanary

initialize() starts RTCanary; while including our script loads in the necessary guts of the program, it does nothing until initialize() is called. initialize() may be called only once, and it must include your appID. If initialize() is called more than once or is called without an appID, or if the parameters passed to initialize() or any setter method are of the wrong type, RTCanary will terminate itself (without affecting your software). Note that while in our examples above, initialize() is called at the top of the html, it may be called anywhere below where our script is loaded. It is not recommended to call any setter method before calling initialize().


It is not recommended to set sendStatsInterval to less than 200 milliseconds, or to less than one-tenth of sendBufferedRecordsInterval.


Setting requestLocation to true will request the user's permission to access their location as soon as initialize() is called.


1.2.5.2. Getters and setters

All parameters have getter methods that you can use in your own scripts to read their values. sessionID, isTestSession, and peerID may also be set or reset later in your code, after initialize() is called. This is useful if, for example, you do not know a user's peerID immediately upon page load and thus need to wait to set peerID, or if you start a new session and need to reset sessionID. Note that setting or resetting sessionID will immediately start a new session (and reset the clock on sendBufferedRecordsInterval, if applicable); if the old session is a test session and the new session is not, or vice versa, you should reset isTestSession as well.


1.2.5.3. Sending data

Messages collected before all three required parameters are set will be embargoed until the parameters are set. After the three required parameters are set, the messages collected up to that point will be filled in with the information in those parameters and then sent to the server. If a batch of messages fails to get sent to the server, the messages will be buffered and we will attempt to send them with the next batch. This will happen for as long as one hour, after which the tail end of the data will start getting cut off from the records to be sent so as to keep the length to one hour, so that it's small enough to send successfully.


1.2.5.4. Managing load in P2P frameworks

Ordinarily, we collect data for each peer connection. This is fine in a non-P2P platform, since there are few peer connections. However, users may experience heightened load in a P2P platform, where they may have many peer connections. Setting p2pManageLoad to true causes data to be collected every sendStatsInterval milliseconds times the number of peer connections, which effectively sets the average number of data collection events per second to be constant. This is intended to reduce client-side load on P2P platforms.



2. Custom Events


To log Custom Events please send a POST request, formatted as below, to our API endpoint. Ask us for the URL!



3. Displaying Data


And then we display it to you on your dashboard! View real-time data of your ongoing sessions, or look over historical data of terminated sessions.




76 views
    • @RTCanary
    • @RTCanary
    • @RT.Canary
    • RTCanary LinkedIN

    San Jose, CA 95128

    Email - founders@RTCanary.com

    Tel - +1 (949) 800-8496

    *RTCanary is a Postered Inc. product*