How to add manual tag orchestration to your website

There are times when you cannot automate the firing of your tags. When those times arise, there are still ways you can gate the firing of these tags based of your visitors consent albeit a little more manual. You can find a working sample here.

Add Ketch Smart Tag to page

To start, add the Ketch Smart Tag for your property as high up in the head of the page as you can.

<html>
    <head>
        <script>(function () {var a=document.createElement("script");a.type="text/javascript",a.src="https://global.ketchcdn.com/web/v1/config/organization_code/property_code/boot.js",a.defer=a.async=!0,document.getElementsByTagName("head")[0].appendChild(a),window.semaphore=window.semaphore||[];})();
        </script>
        ...
    </head>
    <body>
        ...
    </body>
</html>

Add manual orchestration script to page

With the Ketch Smart Tag added to the page, it is time to add the manual orchestration logic. This can be done by adding the following logic to a new JavaScript file, an already existing JavaScript file, or by placing it within a script tag on your pages.

For this example, we will be creating a new JavaScript file, `manual_orchestration.js`, and adding it to the head of our page below the Ketch Smart Tag.

```HTML
<html>
    <head>
        ...
        <!-- Add manual tag orchestration logic -->
        <script type="text/javascript" src="./manual_orchestration.js"></script>
        ...
    </head>
    <body>
        ...
    </body>
</html>

Add manual orchestration logic to JavaScript file

Create a new JavaScript file named manual_orchestration.js

    touch manual_orchestration.js

Inside manual_orchestration.js, add an an event listener to the onConsent event. This event is called whenever consent is loaded on to the page or updated by a visitor. The argument passed to the listener contains a purposes object. The purposes object contains all the purposes defined within the Ketch Platform for your organization and the end-users consent preferences.

Purposes object

{
    purposes: {
        essential_services: true,
        analytics: true,
        marketing: false
    }
}

Additionally, we get all the keys on the purposes object and pass them along with the purposes object to the loadTagsOnPage function.

window.semaphore.push(['onConsent', function(c) { 
    var puporsesKeys = Object.keys(c.purposes);
    loadTagsOnPage(c.purposes, puporsesKeys);
}])

Add logic to load purpose specific tags on page

Inside the loadTagsOnPage function, loop though the purposes object looking at the value for each key to determine if the function to load tags associated to that purpose should be loaded on to the page.

function loadTagsOnPage(purposes, purposesKeys) {
    purposesKeys.forEach(key => {
        switch(key) {
            case 'essential_services':
                // Load essential services tags if visitor has given consent
                if (purposes[key] === true) {
                    loadEssentialServicesTags();
                }
                break;
            ...
        }
    });
}

Loading tags on the page

Inside the function to load tags,

check as to whether or not the tag had been previously loaded, so as not to load the tag more than once on the page

    if (document.getElementById('essential-script')) return;

create a new script element, giving it a unique id to use in the previous check, and set its type to text/javascript

    var essentialScript = document.createElement('script');
    essentialScript.id = 'essential-script';
    essentialScript.type = 'text/javascript';

There are 2 ways to finish the script element depending on how it was provided by the provider

add the source location of the JavaScript to be loaded on to the page

    essentialScript.src = 'https://domain/filename.js'

add the JavaScript code to the tag using a text node element

    var inlineScript = document.createTextNode(`
    (function () { 
        //<JavaScript code goes here>
    })();
    `);

finally, add the script element to the head of the page

    document.head.appendChild(essentialScript);

Full tag loading function

function loadEssentialServicesTags() {
    
    if (document.getElementById('essential-script')) return;

    var essentialScript = document.createElement('script');
    essentialScript.id = 'essential-script';
    essentialScript.type = 'text/javascript';
    
    var inlineScript = document.createTextNode(`
    (function () { 
        alert('Analytics tags loaded');
    })();
    `);

    essentialScript.appendChild(inlineScript);

    document.head.appendChild(essentialScript);
}