A guide to implementing & collecting widget sub ID stats
Sub ID tracking is a useful tool that can be customized to achieve your reporting needs. Some of the ways Publishers successfully utilize Sub ID tracking include tracking revenue by article, traffic source, social influencer, or to evaluate performance on different page variations.
Adding Sub ID Tracking to standard widgets
Gathering Sub ID data for your widgets has undergone a slight modification. To optimize performance, it is recommended to place the new Sub ID code just before the closing `</head>` tag of your document, as shown in the example below:
<head>
<script>
window.rcws = window.rcws || {
subIds: {
000000: {
key1: 'value1',
key2: 'value2'
}
}
}
</script>
</head>
After that, your widget code(s), as normal, will be placed where ever you want your widget code(s) to render:
<!-- RevContent -->
<div data-widget-host="revcontent" data-pub-id="000000" data-widget-id="000000"></div>
<script src="https://delivery.revcontent.com/000000/000000/widget.js"></script>
For convenience, you can position the Sub ID code near your widget code as shown below:
<!-- RevContent -->
<div data-widget-host="revcontent" data-pub-id="000000" data-widget-id="000000"></div>
<script> window.rcws = window.rcws || { subIds: { 000000: { key1: 'value1', key2: 'value2' } } } </script>
<script src="https://delivery.revcontent.com/000000/000000/widget.js"></script>
However, for optimal performance it is still recommended to place the Sub ID code within the `<head>` section of your document, as demonstrated in the example in the first example.
Adding Sub ID Tracking to legacy standard widgets
In order to start collecting Sub ID data you'll need to add a "data-sub-ids" array along with your custom key-value pairs into your widget script like we've done in the following example:
<div id="habitat"
data-rc-widget
data-widget-host="habitat"
data-endpoint="trends.revcontent.com"
data-widget-id=“000000"
data-sub-ids='{"KEY1":"VALUE1","KEY2":"VALUE2"}'></div>
<script type="text/javascript" src="//assets.revcontent.com/master/delivery.js" defer="defer"></script>
Adding Sub ID Tracking to AMP widgets
Collecting Sub ID data on an AMP widget will require the same "data-sub-ids" array and key-value pairs we used above, but in the following AMP code format:
<amp-ad layout="responsive" height="100" width="100" type="revcontent" data-revcontent data-id="12345" data-sub-ids='{"KEY1":"VALUE1","KEY2":"VALUE2"}'></amp-ad>
Adding Sub ID Tracking to RevMail widgets
Collecting Sub ID data on a RevMail widget (standard and dynamic) only requires the addition of the "sub_ids" parameter, as an array with key-value pairs.
- Standard RevMail widget:
<a href="https://revmail.revcontent.com/v2/click?id=1234&p=077735d7-a086-45d1-9743-da2aa9246d35&k={UNIQUEKEY}">
<img style="max-width:100%;" src="https://revmail.revcontent.com/v2/?id=1234&p=077735d7-a086-45d1-9743-da2aa9246d35&k={UNIQUEKEY}&s={SENDID}&sub_ids=[key_01:value_01,key_02:value_02]&sdt={DATETIME}&e={EMAIL}&emd5={MD5EMAIL}&esha1={SHA1EMAIL}&esha256={SHA256EMAIL}&esp={ESP}" />
</a>
Retrieving Sub ID Stats
To pull Sub ID reports you'll need a 3rd party API software. We recommend Postman which is free to use.
The API request used to pull Sub ID data can be found here in our API Documentation: Widget - Get Sub ID Stats
Optional Advanced Usage - Extracting Sub IDs from URLs
The following examples are optional advanced methods which would allow Sub IDs to be pulled directly from URLs.
The first is ES6 which is compatible with Chrome, FireFox, Edge, however not Internet Explorer:
//ES6
let el = document.getElementById('habitat');
let subids = {};
let params = new URLSearchParams(window.location.search);
for ( const [key, value] of params) {
subids[key] = value;
}
el.setAttribute('data-sub-ids', JSON.stringify(subids));
The second is conventional Javascript which is compatible across all browsers but is a bit more involved:
//Vanilla JS
function getParams() {
var params = {};
var query = window.location.search ? window.location.search.slice(1) : null;
if (query) {
var arr = query.split('&')
for (var i = 0; i < arr.length; i++) {
var entry = arr[i].split('=');
params[entry[0]] = entry[1];
}
}
return params;
}
var subids = getParams();
el.setAttribute('data-sub-ids', JSON.stringify(subids));
The logic above can be updated to get meta tags or any other unique values and serves as a general guideline for working with SubIDs outside of setting them directly on the div. As an example, if you were using the following params:
&rc_campaign=value1&utm_source=value2
The objects returned would be:
subids = { rc_campaign: value1, utm_source: value2 }