Callbacks

Foreword

Managing “Callbacks” is a function of the Tracker, available from version 5.3.0 and onward. This option enables you to take into account and automatically execute any tagging functions declared outside of the site’s main tagged area, as in external partner scripts, for example. The main issues encountered when executing embedded tags are loading mode (synchronous or asynchronous), as well as Tracker availability at the time it is called. The “Callbacks” function provides a solution to this by enabling the declaration of completely independent functions, which the Tracker will automatically process when it is initialised.

Principle

Using this function requires a specific tagging format explained below. This tag can be positioned either before or after the main tag.

Setup

You must enable the function within the general settings in the Tag Composer interface:

• Manage callbacks: This option, ticked by default, enables automatic callback management (if the option is ticked: the function is enabled, if the option is unticked: the function is disabled).

Tagging

Complete tagging example

<script type="text/javascript">
    // Tag "Callbacks"
    window.ATInternet = window.ATInternet || {};
    window.ATInternet.Callbacks = window.ATInternet.Callbacks || {};
    window.ATInternet.Callbacks.Callback1 = window.ATInternet.Callbacks.Callback1 || function (tag) {
        tag.mvTesting.set({
            test: '1[My_first_Test]',
            waveId: 1,
            creation: '2[Version2_page_subscription]'
        });
        tag.mvTesting.add({
            variable: '1[Header]',
            version: '2[Grey]'
        });
        tag.mvTesting.add({
            variable: '2[Sidebar]',
            version: '4[Black]'
        });
    };
    window.ATInternet.Utils = window.ATInternet.Utils || {dispatchCallbackEvent: function () {}};
    window.ATInternet.Utils.dispatchCallbackEvent('Callback1'); 
    
    // Main tag
    var tag = new ATInternet.Tracker.Tag();
    tag.page.set({
        name: 'pageName',
        customObject: {
            MyPageLabel: 'my_page',
            MyChapters: {level1: 'my_chapter1', level2: 'my_sub_chapter1', level3: 'my_sub_chapter2'}
        }
    });
    tag.dispatch(); 
</script>

A “Callbacks” tag is composed of different parts:

Declaring the callback function

<script type="text/javascript">
    window.ATInternet = window.ATInternet || {};
    window.ATInternet.Callbacks = window.ATInternet.Callbacks || {};
    window.ATInternet.Callbacks.Callback1 = window.ATInternet.Callbacks.Callback1 || function (tag) {
        tag.mvTesting.set({
            test: '1[My_first_Test]',
            waveId: 1,
            creation: '2[Version2_page_subscription]'
        });
        tag.mvTesting.add({
            variable: '1[Header]',
            version: '2[Grey]'
        });
        tag.mvTesting.add({
            variable: '2[Sidebar]',
            version: '4[Black]'
        });
    };
</script>

Note: In this example, the callback function’s label is “Callback1”. This label may be freely defined, but the same label must be used within a same page. In the case of two identical labels, only the first callback will be taken into account. The function contains specific MV Testing tagging, but technically speaking, allows for any type of tagging.

Generating a specific event to enable adding to the list of callbacks, in case of deferred code loading

<script type="text/javascript">
    window.ATInternet.Utils = window.ATInternet.Utils || {dispatchCallbackEvent: function () {}};
    window.ATInternet.Utils.dispatchCallbackEvent('Callback1'); 
</script>

Note: In this portion of the code, it is important to use the same label as in the function declared just above (“Callback1” in our example).

Asynchronous tagging example

The “Callbacks” function is compatible with the asynchronous version of the Tracker, which nonetheless must be adapted in order to avoid overwriting any potential previously declared callbacks:

window.ATInternet = window.ATInternet || {};
window.ATInternet.onTrackerLoad = function () {
    window.tag = new window.ATInternet.Tracker.Tag();
    // your tag
}
(function(){      
    var at=document.createElement('script');
    at.type='text/javascript';   
    at.async=true;    
    at.src='http://www.site.com/smarttag.js';
    (document.getElementsByTagName('head')[0]||document.getElementsByTagName('body')[0]||document.getElementsByTagName('script')[0].parentNode).insertBefore(at,null);   
})();

Full asynchronous tagging

<script type="text/javascript">
    // Tag "Callbacks"
    window.ATInternet = window.ATInternet || {};
    window.ATInternet.Callbacks = window.ATInternet.Callbacks || {};
    window.ATInternet.Callbacks.Callback1 = window.ATInternet.Callbacks.Callback1 || function (tag) {
        tag.mvTesting.set({
            test: '1[My_first_Test]',
            waveId: 1,
            creation: '2[Version2_page_subscription]'
        });
        tag.mvTesting.add({
            variable: '1[Header]',
            version: '2[Grey]'
        });
        tag.mvTesting.add({
            variable: '2[Sidebar]',
            version: '4[Black]'
        });
    };
    window.ATInternet.Utils = window.ATInternet.Utils || {dispatchCallbackEvent: function () {}};
    window.ATInternet.Utils.dispatchCallbackEvent('Callback1');
    
    // Asynchronous tag    
    window.ATInternet = window.ATInternet || {};
    window.ATInternet.onTrackerLoad = function () {
        var Tag = ATInternet.Tracker.Tag;
        window.tag = new Tag();
        window.tag.page.set({
            name: 'pageName',
            customObject: {
                MyPageLabel: 'my_page',
                MyChapters: {level1: 'my_chapter1', level2: 'my_sub_chapter1', level3: 'my_sub_chapter2'}
            }
        });
        window.tag.dispatch();
    };
    (function () {
        var at = document.createElement('script');
        at.type = 'text/javascript';
        at.async = true;
        at.src = 'smarttag.js';
        (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0] || document.getElementsByTagName('script')[0].parentNode).insertBefore(at, null);
    })();
</script>

Customised tagging

You may customise the tag by filling in different properties to specify the rules for taking callbacks into account for a given tag. Two properties, “include” and “exclude”, allow you to respectively declare a list of callbacks (designated by their label) to be executed, or inversely, to be ignored, according to your needs. By default, when this function is enabled, each declared tag object on the page will trigger the code included in all callbacks, considering that a callback automatically inherits the settings properties of the tag that triggered it (site number, etc.).

Example of callback inclusion

<script type="text/javascript">
    // Tag "Callbacks" #1
    window.ATInternet = window.ATInternet || {};
    window.ATInternet.Callbacks = window.ATInternet.Callbacks || {};
    window.ATInternet.Callbacks.Callback1 = window.ATInternet.Callbacks.Callback1 || function (tag) {
        tag.mvTesting.set({
            test: '1[My_first_Test]',
            waveId: 1,
            creation: '2[Version2_page_subscription]'
        });
        tag.mvTesting.add({
            variable: '1[Header]',
            version: '2[Grey]'
        });
        tag.mvTesting.add({
            variable: '2[Sidebar]',
            version: '4[Black]'
        });
    };
    window.ATInternet.Utils = window.ATInternet.Utils || {dispatchCallbackEvent: function () {}};
    window.ATInternet.Utils.dispatchCallbackEvent('Callback1'); 
    
    // Tag "Callbacks" #2
    window.ATInternet = window.ATInternet || {};
    window.ATInternet.Callbacks = window.ATInternet.Callbacks || {};
    window.ATInternet.Callbacks.Callback2 = window.ATInternet.Callbacks.Callback2 || function (tag) {
        tag.click.set({
            name: 'clickName',
            chapter1: 'myChapter1',
            chapter2: 'myChapter2',
            chapter3: 'myChapter3',
            level2: 'clickLvl2',
            type: 'navigation',
            customObject: {
                param1: 'val1',
                param2: 2
            }
        });
    };
    window.ATInternet.Utils = window.ATInternet.Utils || {dispatchCallbackEvent: function () {}};
    window.ATInternet.Utils.dispatchCallbackEvent('Callback2');

    // Main tag
    var config = {
        callbacks: {
            include: ["Callback2"]
        }
    };    
    var tag = new ATInternet.Tracker.Tag(config);
    tag.page.set({
        name: 'pageName',
        customObject: {
            MyPageLabel: 'my_page',
            MyChapters: {level1: 'my_chapter1', level2: 'my_sub_chapter1', level3: 'my_sub_chapter2'}
        }
    });
    tag.dispatch(); 
</script>

Note: In this example, only the callback function with the label “Callback2” will be executed.

Example of callback exclusion

<script type="text/javascript">
    // Tag "Callbacks" #1
    window.ATInternet = window.ATInternet || {};
    window.ATInternet.Callbacks = window.ATInternet.Callbacks || {};
    window.ATInternet.Callbacks.Callback1 = window.ATInternet.Callbacks.Callback1 || function (tag) {
        tag.mvTesting.set({
            test: '1[My_first_Test]',
            waveId: 1,
            creation: '2[Version2_page_subscription]'
        });
        tag.mvTesting.add({
            variable: '1[Header]',
            version: '2[Grey]'
        });
        tag.mvTesting.add({
            variable: '2[Sidebar]',
            version: '4[Black]'
        });
    };
    window.ATInternet.Utils = window.ATInternet.Utils || {dispatchCallbackEvent: function () {}};
    window.ATInternet.Utils.dispatchCallbackEvent('Callback1'); 
    
    // Tag "Callbacks" #2
    window.ATInternet = window.ATInternet || {};
    window.ATInternet.Callbacks = window.ATInternet.Callbacks || {};
    window.ATInternet.Callbacks.Callback2 = window.ATInternet.Callbacks.Callback2 || function (tag) {
        tag.click.set({
            name: 'clickName',
            chapter1: 'myChapter1',
            chapter2: 'myChapter2',
            chapter3: 'myChapter3',
            level2: 'clickLvl2',
            type: 'navigation',
            customObject: {
                param1: 'val1',
                param2: 2
            }
        });
    };
    window.ATInternet.Utils = window.ATInternet.Utils || {dispatchCallbackEvent: function () {}};
    window.ATInternet.Utils.dispatchCallbackEvent('Callback2');

    // Main tag
    var config = {
        callbacks: {
            exclude: ["Callback2"]
        }
    };    
    var tag = new ATInternet.Tracker.Tag(config);
    tag.page.set({
        name: 'pageName',
        customObject: {
            MyPageLabel: 'my_page',
            MyChapters: {level1: 'my_chapter1', level2: 'my_sub_chapter1', level3: 'my_sub_chapter2'}
        }
    });
    tag.dispatch(); 
</script>

Note: In this example, only the callback function with the label “Callback1” will be executed, as the function “Callback2” has been excluded.