Origami Frontend Components & Services

Readme: o-tracking

Include in your product to send tracking requests to the Spoor API.

The Spoor ecosystem

ScreenShot

Usage

Requirement: Polyfills & Doesn't cut the mustard

Applies to both quickstart examples below

Add the polyfill service to your site to make sure o-tracking runs in as many browsers as possible.

Require the noscript version of o-tracking incase the browser doesn't cut the mustard.

Checkout the Origami spec for the correct CTM logic, html and css changes needed.

o-tracking should have the following piece of html added, with the correct server and data filled in.

<div class="o-tracking o--if-no-js" data-o-component="o-tracking">
    <div style="background:url('http://server?data={}');"></div>
</div>

Use an onload handler to check when o-tracking has loaded and then init.

// CTM
if (cutsTheMustard) {
    var o = document.createElement('script');
    o.async = o.defer = true;
    o.src = 'https://build.origami.ft.com/v2/bundles/js?modules=o-tracking';
    var s = document.getElementsByTagName('script')[0];
    if (o.hasOwnProperty('onreadystatechange')) {
        o.onreadystatechange = function() {
            if (o.readyState === "loaded") {
                oTrackinginit();
            }
        };
    } else {
        o.onload = oTrackinginit;
    }
    s.parentNode.insertBefore(o, s);
}

The oTrackinginit function, used above, would have function calls to setup o-tracking and likely send a page view event. e.g.

function oTrackinginit() {
    var oTracking = Origami['o-tracking'];
    // Setup
    oTracking.init({...config...});
    // Page
    oTracking.page({...config...});
    // Clicks.
    oTracking.click.init(category);
    // Components/Elements views.
    oTracking.view.init({...opts...});
}

Alternative implementation using require

Use the build service or require locally to load o-tracking and init manually.

var oTracking = require('o-tracking');
if (cutsTheMustard) {
    // Setup
    oTracking.init({...config...});
    // Page
    oTracking.page({...config...});
    // Clicks
    oTracking.click.init(category);
    // Components/Elements views.
    oTracking.view.init({...opts...});
}

Example implementations

Full example

<!DOCTYPE html>
<!-- Add core class to head tag -->
<head class="core">
<head>
    <title>Full example</title>
    <!-- Add CTM styles -->
    <style type="text/css">
        /* Hide any enhanced experience content when in core mode, and vice versa. */
        .core .o--if-js,
        .enhanced .o--if-no-js { display: none !important; }
    </style>
    <!-- Add CTM check -->
    <script>
        var cutsTheMustard = ('querySelector' in document && 'localStorage' in window && 'addEventListener' in window);
        if (cutsTheMustard) {
        // Swap the 'core' class on the HTML element for an 'enhanced' one
        // We're doing it early in the head to avoid a flash of unstyled content
        document.documentElement.className = document.documentElement.className.replace(/\bcore\b/g, 'enhanced');
        }
    </script>
    <!-- Add Polyfil service -->
    <script src="https://cdn.polyfill.io/v1/polyfill.min.js"></script>
    <!-- INIT and make a page request -->
    <script>
        function oTrackinginit() {
            // oTracking
            var oTracking = Origami['o-tracking'];
            var config_data = {
                server: 'https://spoor-api.ft.com/px.gif',
                context: {
                    product: 'ft.com'
                },
                user: {
                    ft_session: oTracking.utils.getValueFromCookie(/FTSession=([^;]+)/)
                }
            }
            // Setup
            oTracking.init(config_data);
            // Page
            oTracking.page({
                content: {
                    asset_type: 'page'
                }
            });
        }
        if (cutsTheMustard) {
            var o = document.createElement('script');
            o.async = o.defer = true;
            o.src = 'https://build.origami.ft.com/v2/bundles/js?modules=o-tracking';
            var s = document.getElementsByTagName('script')[0];
            if (o.hasOwnProperty('onreadystatechange')) {
                o.onreadystatechange = function() {
                    if (o.readyState === "loaded") {
                        oTrackinginit();
                    }
                };
            } else {
                o.onload = oTrackinginit;
            }
            s.parentNode.insertBefore(o, s);
        }
    </script>
</head>
<body>
<!-- Add fallback if browsers don't cut the mustard -->
<div class="o-tracking o--if-no-js" data-o-component="o-tracking">
    <div style="background:url('https://spoor-api.ft.com/px.gif?data=%7B%22category%22:%22page%22,%20%22action%22:%22view%22,%20%22system%22:%7B%22apiKey%22:%22qUb9maKfKbtpRsdp0p2J7uWxRPGJEP%22,%22source%22:%22o-tracking%22,%22version%22:%221.0.0%22%7D,%22context%22:%7B%22product%22:%22ft.com%22,%22content%22:%7B%22asset_type%22:%22page%22%7D%7D%7D');"></div>
</div>
<!-- Send an event -->
<button onclick="document.body.dispatchEvent(new CustomEvent('oTracking.event', { detail: { category: 'element', action: 'click' }, bubbles: true}));">Send an event</button>
</body>
</html>

Events

o-tracking captures events automatically when initialised with the methods outlined above. In addition, o-tracking will capture custom oTracking.page and oTracking.event events:

Parameters

o-tracking will

Events are decorated with config values you pass in via init() or updateConfig() if they are part of context, user, or device objects. Values passed in as context to individual events will override context values from init.

Init

{
    server: "...",
    context: {
        product: "..."
    },
    user: {
        ft_session: "..."
    },
    device: {
        orientation: "..."
    }
}

Updating core configuration

{
    device: {
        orientation: "..."
    }
}

Page

{
    url: "...",
    referrer: "..."
    content: {
        uuid: "...",
        hurdle: "..."
    }
    ... any other key-values ...
}

Event

Important: To decide how to name the category and action fields, consider this sentence (square brackets denote that part is optional):

A user can {action} a {category}[ with/having a {context}[ to {destination}]]

For example:

{
    category: 'video',
    action: 'play',
    ... any other key-values ...
    id: '512346789',
    pos: '10'
}

Look at all the properties available for an event.

JSDoc

Switch component view

GitHub Repository

Install o-tracking

If using the Build Service, add o-tracking@^1.7.2 to your script tag.

If running a Manual Build, run bower install --save "o-tracking@^1.7.2".

Help & Support

o-tracking is maintained directly by the Origami team. If you have any questions about o-tracking or Origami in general, we are happy to help. 😊

Slack: #ft-origami
Email: origami.support@ft.com

Feedback / Issues

To report a bug or request features please create an issue on Github. For support or general feedback please get in touch 😊

Slack: #ft-origami
Email: origami.support@ft.com