Sky Analytics API Demo Page

Contributing

The source code is available in a private repository on Github, along with instructions for building/running the project locally. Please fork it from here: https://github.com/skyglobal/analytics/

Feature Requests: If there is no similar request here, create a New Issue and flag it as an 'enhancement'
Bug Reporting: If there is no similar request here, create a New Issue and flag it as a 'bug'

Getting Started

Please use the following: <script src=//analytics.global.sky.com/1.3.2/analytics.js></script> (this works over http or https). If your project uses RequireJS, Click here to see a requireJS example.

Then add the following onto your page with the correct account details to initialise the tracking.

analytics.setup({
    site: 'global',
    section: 'skyglobal/analytics/demo',
    account: 'bskybdemodev'
});

analytics.trackPage();

Boom. Job Done.

Now anchors, buttons, submits and any element with [data-tracking] are automatically tracking.

Click here to see this basic config in action.

Resetting the Config

If you have a single-page app and need to reset the config, you can use the analytics.setup as often as required.

Default Config

There are a few things you get for free. These are:

On Page View

ageGender

campaign

customerType

externalSearchTerm

fullCampaign

fullPageDescription

optIn

repeatVisit

samId

sessionCamID

The sessionCamID variable gets set if the page has SessionCam.

searchEngine

sessionCampaign

testAndTarget

tnt

visitNum

On Click

sessionCamID

The sessionCamID variable gets set if the page has SessionCam.

linkClick Event

linkDetails

The masthead variable gets tracked automatically when a link is clicked within the masthead.

refDomain

url

Config in Detail

To get you config correct, please get the details for your project from implementation@bskyb.com. The following shows the options:

site: [mandatory] Team Identifier e.g. 'sports', 'mysky' or 'skycom' etc. Do not include the sky/portal/ prefix.
section: [mandatory] General page location, slash deliminated. e.g. 'make-the-most/tv-preference'
account: [mandatory] Omniture account name. e.g. bskybskycomaccountprod
page: [optional] Unique identifier for your page e.g. "mini connector - registration success"
headline: [optional] Subject title for the page article
contentType: [optional] Type of page descriptor
contentId: [optional] UID for articles over time (i.e. if headline text is duplicated)
loadVariables: [optional] A way to a standard tracking variable to your site on page load. details here >>
loadEvents: [optional] A way to a standard tracking events to your site on page load. details here >>
customVariables: [optional] A way to customise tracking for your site. details here >>
customEvents: [optional] A way to customise tracking for your site. details here >>
trackClicks: [optional] [boolean]. Set to false to prevent binding of omniture calls on link clicks. click here to see how to manually bind your link clicks
debug: [optional] [boolean]. Set to true to turn on debug on page load to capture the page view event

Debugging

You can either add debug:true or execute analytics.debug([true|false]);. Click here to see debug on load in action.

Try turning debug on and debug off then clicking the following link: Sky.com Homepage

Please note, when debug is on, the user is not taken to the link. This behaviour is intentional and allows the user to check the tracking in the console or browser's net tab.

Example config

    analytics.trackPage({
        page: document.title,
        site: 'global',
        section: 'skyglobal/analytics/demo',
        account: 'bskybdemodev',
        loadVariables: {'videoTitle':'My Home Video', 'externalSearchTerm':'thrill rides'},
        loadEvents: ['activateComplete'],
        customEvents: [
            {'magic_happened': {event: 101, onPageLoad:true}}
        ],
        customVariables: [
            {'drink': {'eVar': 72}},
        ],
        debug: true
    });

Click here to see this custom config in action.

Click here to see another custom config in action.

Clicks

Pages are commonly split up in the following areas: Modules, Pods and other. You may also want to track Editorial-Themes or the Context along with the clicked text¹.

Optional tracking Attributes

Add the following data attributes to the relevant containers within your page. When an element is clicked, the JS will traverse up the DOM looking for these attributes.

data-tracking-module: Add this to a top-level container.
This defines a distinct horizontal band on a page.
eg. data-tracking-module=carousel
data-tracking-pod: Add this to a mid-level container.
This commonly defines a vertical band within the module or a segment of content.
eg. data-tracking-pod=slide2
data-tracking-other: Add this to a Low level container.
This might be useful for multi-level navigation.
eg. data-tracking-other=subnav-text
data-tracking-theme: Add this to the element being clicked or a container.
Used to group items or related links that may be across modules.
eg. data-tracking-theme=friends-and-family
data-tracking-context ... or ... data-tracking-context-id: Add this to the element being clicked or a container.
Useful when multiple links have the same text, you may need more context around the link i.e. 'remote record' may need the context of what is being recorded
eg. data-tracking-context=bond-11 or data-tracking-context-id=search-box
data-tracking-label: Add this to the element being clicked
A text alternative. Useful when the text clicked may be too long or non-unique.
eg. data-tracking-label=bond-remote-record
data-tracking-search: Add this to the button/link that triggers the search.
Must be used with data-tracking-context-id.
eg. data-tracking-search=weather data-tracking-context-id=search-box
data-tracking: Add this to an element you do/do not want tracked
A way to force tracking of an element or to stop the tracking of an element.
eg. data-tracking=false

¹ By default we automatically track the text that is clicked along with the site name. In order of priority, we track text by looking for the attributes: 'data-tracking-label', 'alt', 'value' and 'name'. If these are not found we will use the elements inner-text.

Examples

Standard link

'a' tags will be tracked automatically

        HTML
            <a href='#' >link</a>    
        Javascript
        none
    

'button' tags will be tracked automatically

        HTML
            <button>Button</button>    
        Javascript
        none
    

'input' tags with type=submit will be tracked automatically

        HTML
            <input type="submit" value="Submit"/>    
        Javascript
        none
    

Tracking everything else

the attribute 'data-tracking' needs to be added to any other tags you wish to track

        HTML
            <span data-tracking >Span</span>    
        Javascript
        none
    

Link tracked with different text

By adding 'data-tracking-label' you can change the text that is tracked.

        HTML
            <a data-tracking-label='label-text' href="#">Link</a>
        Javascript
        none
    

Similar CTA's, different actions

By adding 'data-tracking-context' you can differentiate between 2 CTA's that do different things.
E.g. Remote Record buttons that record different programmes.

HTML<a href="#" data-tracking-context='Sky News'>Record</a>
<a href="#" data-tracking-context='Sky Sports'>Record</a>
        
Javascriptnone

Same module, pod 1

Same module, pod 2

By adding 'data-tracking-pod' and 'data-tracking-module' you can provide more information about where in the page links are located.

HTML<div data-tracking-module=testing>
    <div data-tracking-pod=pod-1>
        <a href="#!" >pod 1</a>
    </div>
    <div data-tracking-pod=pod-2>
        <a href="#!">pod 2</a>
    </div>
</div>
Javascriptnone

Tracking further info

Tracking themes

'data-tracking-other' can be used to track any other useful info, i.e. when navigation gets past 2 levels.
'data-tracking-theme' can be used to allow editors monitor page elements that are related over time.

HTML<div data-tracking-module=testing>
    <div data-tracking-other=js-off-link>
        <a href="#!" >Other info</a>
    </div>
    <div data-tracking-theme=editorial-promo-winter>
        <a href="#!">Themes</a>
    </div>
</div>
Javascriptnone

Standard link, not tracked

By adding 'data-tracking=false' you can stop any element from tracked automatically.

HTML
            <a data-tracking=false href="#">link</a>
<button class="btn" data-tracking="false" id="button-not-tracked" >button</button>
<input type=submit data-tracking="false" value="Submit" id="submit-not-tracked" />
        
Javascriptnone

Variables

Standard

There are a number of variables that are standard within omniture, which means you can use them without mapping them to an eVar or prop id.

A list of standard variables can be found here.

Custom

When initialising, you will need to add customVariables array which may contain some options:

eVar: [int] Omniture Variable Id. Needed for conversion reporting. (Max 75)
prop: [int] Omniture Prop Id. Needed for count based reporting. (Max 75)
list: [int] Omniture List Id. The value of this type must be an Array.
hier: [int] Omniture Hierarchy Id. The value of this type must be an Array
onPageLoad: [optional][boolean] Set if the variable should be sent when 'trackPage' is called
value: [optional][string or Array] Should be set if onPageLoad is set

The name of this object needs to match an HTML element using the attribute data-tracking-variable. Optionally, data-tracking-value can also be used to send an alternate value to Omniture, otherwise the text clicked will be tracked.

Examples

Send Standard Variable

Send a standard variable on click by setting data-tracking-variable.

HTML
            <button data-tracking-variable='videoTitle' data-tracking-value="My Videos" >Send Standard Variable</button>
            
Javascript
            none

Send Standard Variable on load

Add loadVariables in the config.

HTML
            <button data-tracking-variable='videoTitle' data-tracking-value="My Videos" >Send Standard Variable</button>
            
        
Javascript
               analytics.trackPage({
    site: 'global',
    section: 'skyglobal/analytics',
    account: 'bskybdemodev',
    loadVariables: {'videoTitle':'My Home Video', 'externalSearchTerm':'thrill rides'}
});
        

Tracking drink and setting the value to the content of a text box.

HTML
            <label for='input_field'>What is your favourite drink?</label>
    <input id='input_field' name='input_field' type='text' />
    <button data-tracking-variable='drink' data-tracking-value="" class='btn primary-cta'>Submit</button>
        
Javascript
            analytics.trackPage({
    ...
    customVariables: [
        {'colour': {eVar: 72 }}
    ]
});
            <script>//script to update data-tracking-value attribute
    $('[data-tracking-variable=drink]').attr('data-tracking-value',$('#input_field').val());
</script>
        

Tracking custom variable briansCat on page load as a prop.

HTML
            none
        
Javascript
            analytics.trackPage({
    ...
    customVariables: [
        {'briansCat': { prop: 66, value:'is great', onPageLoad:true }}
    ]
});
        

Tracking how_about_pina_coladas and setting it to the selected radio button

HTML
            <label>Do you like Pina Coldas?</label>
<input id='radio_yes' name='radio_field' type='radio' value='yes_to_pinas'/>
<label for='radio_yes'>Yes</label>
<input id='radio_no' name='radio_field' type='radio' value='no_to_pinas'/>
<label for='radio_no'>No</label>
<button data-tracking-variable='how_about_pina_coladas' class='btn primary-cta'>Submit</button>
            
Javascript
            analytics.trackPage({
    ...
    customVariables: [
       {'how_about_pina_coladas': {eVar: 73 }}
    ]
});
            <script>//script to update data-tracking-value attribute
    $('[data-tracking-variable=how_about_pina_coladas]').attr(
      'data-tracking-value',
        $('input[name=radio_field]:checked').val()
    );
</script>
        

Tracking colour and setting it to the value of the button clicked

HTML
            <button  data-tracking-variable="colour">Blue</button>
<button data-tracking-variable="colour">Gray</button>
Javascriptanalytics.trackPage({
    ...
    customVariables: [
        {'colour': {eVar: 71 }}
    ]
});        

Custom Var Page Load

To track a custom variable when the page loads, add onPageLoad: true in the config.

HTML    none
        Javascript
                var config = {
        ...
        customVariables: [
            {'how_about_pina_coladas': {eVar: 73, value:'my val on load', onPageLoad: true}}
        ]
    };
    analytics.trackPage(config);
            
        

List Variable on page load

To track a list variable use list and set the value to an Array.

HTML    none
        Javascript
                var config = {
        ...
        customVariables: [
            {'myListOfStuff': {list: 1, value:['val1','my second','final value'], onPageLoad: true}}
        ]
    };
    analytics.trackPage(config);
            
        

List Variable on click

To track a list variable on click use list and update the HTML. If you set the value within the HTML, the list must be piped deliminated

HTML
            <button  data-tracking-variable="customer-offers">List Variable on click</button>
        Javascript
                var config = {
        ...
        customVariables: [
            {'customer-offers': {list: 2}}
        ]
    };
    analytics.trackPage(config);
            
        

Hierarchy Variable on page load

To track a hierarchy variable use hier and set the value to an Array.

HTML    none
        Javascript
                var config = {
        ...
        customVariables: [
            {'myHierarchyOfStuff': {hier: 2, value:['h1','second h','final hier'], onPageLoad: true}}
        ]
    };
    analytics.trackPage(config);
            
        

Hierarchy Variable on click

To track a hierarchy variable use on click hier and update the HTML. If you set the value within the HTML, the list must be piped deliminated.

HTML
            <button  data-tracking-variable="my-heirarchy">Hierarchy Variable on click</button>
        Javascript
                var config = {
        ...
        customVariables: [
            {'my-heirarchy': {hier: 2}}
        ]
    };
    analytics.trackPage(config);
            
        

Events

Standard

There are a number of events that are standard within omniture, which means you can use them without mapping them to an event id.

A list of standard events can be found here.

Custom

An array of 'Custom Events' can be added to the analytics config on initialisation..

The Custom Events array will contain an object with the following options:

event name: [string] Event alias
event: [int] Omniture Event Id
serial: [optional][int] Serialisation Id
onPageLoad: [optional][boolean] Set if the event should be passed to Omniture when the page loads

Examples

Send Standard Event

Send a standard event on click by setting data-tracking-event.

HTML
            <button data-tracking-variable='liveChat' >Send Standard Event</button>
            
Javascript
            none

Send Standard Events on load

Add loadEvents in the config.

HTML
            <button data-tracking-variable='liveChat'>Send Standard Event</button>
            
        
Javascript
            analytics.trackPage({
    site: 'global',
    section: 'skyglobal/analytics',
    account: 'bskybdemodev',
    loadEvents: ['liveChat']
});
        

Custom Event

To track a custom event when an element is clicked, add data-tracking-event=eventName to the relevant element.

HTML    <a href='#' data-tracking-event='magic_happened'>Custom Event</a>Javascript
                var config = {
                ...
                customEvents: [
                    {'magic_happened': {event: 101}}
                ]
            };
            analytics.trackPage(config);
            
        

Custom Page Load

To track a custom event when the page, add onPageLoad: true in the config.

HTML    none
        Javascript
                var config = {
                ...
                customEvents: [
                    {'magic_happened': {event: 101, onPageLoad: true}}
                ]
            };
            analytics.trackPage(config);
            
        

Send serialised Event

To track an serialised event, add serial in the config.

HTML    none
        Javascript
                var config = {
                ...
                customEvents: [
                    {'serial-event': {event: 666, serial: 'devil12345'}}
                ]
            };
            analytics.trackPage(config);
            
        

Page Types

Searches

To track searchType and searchTerms, you need to add the following into your HTML:

data-tracking-search: Add this to the search button and set it to the type of search e.g. weather
data-tracking-context-id: Add this to the search button and set it to the id of the element that contains what was searched for.

Once the search is complete and results have been returned, the above info should be sent with trackPage along with how many results we're returned.

Examples

Using 'data-tracking-search' with 'data-tracking-context-id' will activate the Omniture Search Variables.

If you do not have a data-tracking-other set, then either 'click' or 'keydown' will also be tracked.

HTML
            <input id="search" type="text" placeholder="Postcode or town">
<button data-tracking-search="weather" data-tracking-context-id="search">Search</button>
        
Javascriptnone

If there is a data-tracking-other already defined, it will not get over-written.

HTML
            <input id="search" type="text" placeholder="Postcode or town">
                <button data-tracking-search="weather" data-tracking-context-id="search">Search</button>
        
Javascriptnone

Trigger trackPage with loadVariables: searchResults, searchType and searchTerm¹.

HTML
            none
        
Javascriptanalytics.trackPage({
    site: 'global',
    section: 'skyglobal/analytics/results',
    account: 'bskybglobaldev',
    loadVariables: { 'searchResults': 1, 'searchType':'weather', 'searchTerm': 'london' }
});
        

¹When searchResults variable is set, the searchResults event will be sent automatically.

Errors

Tracking an error is as easy 1, 2, 404. You can either send an error on trackPage or via JS.

Examples

Send Error

Manually call the analytics.trackError function.

HTML
            none
        
Javascript
            analytics.trackError('myCustomError i.e. 404 or no-package-found');            
        

Send Error on page load

All you need to do is use loadVariablesin the trackPage config.

HTML
            none
        
Javascript
            SITECAT_CONFIG = {
    site: 'global',
    section: 'skyglobal/analytics/debug',
    headline: '',
    contentType: 'demo',
    contentId: '',
    account: 'bskybglobaldev',
    loadVariables: { errors: '404' }
};
analytics.trackPage(SITECAT_CONFIG);
            
        

Manual Tracking

You can trigger tracking using JS, and the event will be sent to Omniture as if the user had clicked the element themselves.

Bind tracking manually

If you have set trackClicks: false in the config you will need to manually set up the link track binding. You will also have to manually trigger analytics.trackPage for 'single-page apps'. This is useful for 'backbone' apps for example.

Examples

Ajax Event / Single page app

Pass in the updated config to, and call the trackPage function.

HTML
            none
        
Javascript
            analytics.trackPage(config);            
        

Span manually tracked by JS
Anchor being tracked with JS

All elements can be tracked via JS. even id data-tracking=false attribute exists.

HTML
            <span id='trackingOff'>tracked with js</span>            
        
Javascript
            $('#trackingOff').trigger('analytics.track');            
        

Span manually bound
Anchor manually bound

You can bind your DOM elements to execute analytics.trackClick manually

HTML
            <span id='manualBind'>tracked with js</span>            
        
Javascript
            $(document).on('click', '#manualBind, manualBindA', analytics.trackClick);
        

AdHoc Tracking

You can send events/variables to omniture during the life of a page using analytics.trackAdHoc.

Examples

Send AdHoc Tracking

setup and call the trackAdHoc function.

HTML
            none
        
Javascript
            analytics.setup({
    site: 'global',
    section: 'skyglobal/analytics/demo',
    account: 'bskybdemodev',
    contentType: 'analytics',
    customVariables: [
        {'briansCat': {'eVar': 66}}
    ],
    customEvents: [
        {'myAdHocEvent': {'event': 69} }
    ]
});
            analytics.trackAdHoc(
    {'briansCat': 'is still great'},
    {'testAndTarget': 'is poo'},
    'myAdHocEvent'
);
        

Send AdHoc Tracking page view Send AdHoc Tracking after page view

Send the config, track page view and then call the trackAdHoc function.

HTML
            none
        
Javascript
            analytics.setup({
    site: 'global',
    section: 'skyglobal/analytics/demo',
    account: 'bskybdemodev',
    contentType: 'analytics',
    customVariables: [
        {'briansCat': {'eVar': 66}}
    ],
    customEvents: [
        {'myAdHocEvent': {'event': 69} }
    ]
});
            analytics.trackPage();
            analytics.trackAdHoc(
    {'briansCat': 'is still great'},
    {'testAndTarget': 'is poo'},
    'myAdHocEvent'
);
        

Omniture Analytics v1.3.2

Contributing

Getting Started

Resetting the Config

Default Config

On Page View

On Click

Config in Detail

Debugging

Example config

Clicks

Optional tracking Attributes

Examples

Variables

Standard

Custom

Examples

Events

Standard

Custom

Examples

Page Types

Searches

Examples

Errors

Examples

Manual Tracking

Bind tracking manually

Examples

AdHoc Tracking

Examples