All Watching That plugins consist of a few core libraries built to gather data from the environment and send that data to our ingesting endpoint (the collector). Most of the data is gathered by listening to player events but some of the data may also be retrieved directly from the browser environment where needed. For some players no other 3rd party plugins are needed (Brightcove and JW players), for others we might need extra plugins to help forward ad events on the player (VideoJS).
Briefly, the steps to get a plugin running are:
- load the plugin from our cdn. Typically, you do this with a
<script src="..."></script>tag somewhere in your html code but, of course, any other way of loading a remote script is fine. Note that for the Brightcove player this step is not needed as it pre-bundles it with the player.
- start the plugin. You do this by calling the
wtAdTracerfunction with some options detailed below.
Consult the individual plugin pages for specific setup details.
Whenever you call the
wtAdTracer function to start the plugin, you must pass it some options. At the very least you
apiKey which identifies your plugin in our system. You can retrieve the api key from the
Watching That app > My Account > Settings > Player plugin setup page or from your Watching That rep.
|apiKey||yes||Required identifier for your plugin|
|debug||Set to |
|sendAllCustom||Set to |
|sendDebug||Set to |
If you want to enable debug logs just for your browser, so you can test your custom fields without affecting anyone else
then a better alternative to setting the
debug option above is to enter
localStorage.setItem('wtDebug', 1) in the
browser's devtools console and refresh the page. To stop debug logs for showing enter
Example start with all options:
Our plugins are configured to send a set list of fields and player events to our collector. We review and update this list on a regular basis but in case you want to send some data we don't currently support then you have a great way of doing this yourself.
All our plugins check for the presence of a special object defined on the window:
The general structure of this object is
It is important for this object to be defined before the player is ready, otherwise our plugin might not see it and it might not send your custom data with some early events.
window.wtatCustom.fields object allows you to send custom data together with the data our plugins send by default.
For example, to send a field
userCity, you'd do:
You can send any number of fields this way:
Apart from static fields like above, you can also define a field as a function:
In the example above
mySite would be set to the value of
Make sure you always return a value from your functions otherwise the field will not be sent.
Functions are run everytime new data is prepared to be sent to our servers so heavy functions might badly affect the user experience on your page. Make sure you cache this sort of functions or replace them with static fields where possible. The above example can be rewritten in a more efficient way like this:
Functions receive a parameter consisting of all the data prepared to be sent so far, including the "official" data collected by us.
In the example above the
mySite field is sent only when the event type is
To avoid sending the same data multiple times to our servers, static fields are only being sent with the first event of
a session (
Function fields, on the other hand, are evaluated and sent with all events. We assume that, being a function, its output
might change over time or based on the parameters it receives.
As noted above, if you're always sending the same data, it's better to send it as a static field.
If you want to send all your custom fields with all events you can set the
sendAllCustom plugin option to
you initialise the plugin. For the exact setup see the individual plugin documentation.
Please let us know the exact list of custom fields you're capturing so that we can expose these fields in our application UI.
Apart from custom data fields you can also send other player events we're not already capturing. Consult your player documentation for the list of events it exposes.
The easiest way to send extra events is to set the
window.wtatCustom.events object like this:
This will listen for the
loadedmetadata events on the player and send them to our collector endpoint
along with the required data and your custom fields every time the player triggers these 2 events.
If, for some reason, you don't want to send the type as the event name then you can do
type field is mandatory as it identifies the event type in our data. Failing to set it will prevent the event from
being sent to our collector.
Finally, if you need to calculate some fields or decide whether to send the event or not with a more complex logic,
then you can use a function for the value of the event. The function must return an object with at least the
field set. Note that functions receive the player event as a parameter:
This will send the
time event every 5 seconds for the duration of the video along with the position of the player.
It is important you send extra fields as part of the
custom field as in the example above, otherwise your field might
not be included in the sent data.
The plugin captures and sends all the relevant events it receives. However, in rare situations you might not want
certain events to be captured.
window.wtatCustom.ignoredEvents offers you a way to do this.
In contrast to the other keys of the
ignoredEvents is an array. Every item in the array must be
an object with field names as keys and possible values for those fields as values.
For example, if you want to ignore (discard, really) all
INVALID_ASSET_CUSTOM_ID error events you can do so:
This will run a filter against the events and whenever it finds one having
type set to
err set to
INVALID_ASSET_CUSTOM_ID it simply ignores it as if it was never triggered.
To specify several events to be ignored, each with its own filtering criteria, you can add multiple items to the array:
You can also ignore events based on the custom fields you set. For this you need to prefix your custom
custom. (so if you have a custom field named
foo then you'd match it with
Take great care not to ignore important events by setting your filtering criteria too broad.
ignoredEvents lets you
ignore any event, even the ones that are crucial for the correct functioning of our application.