How to Implement UCP with Tealium

[jwheeler]

Implementing with Tealium

This document provides instructions on how to implement support for the Evidon Universal Consent Platform (UCP) inside of the Tealium IQ Tag Manager.  Using these instructions our customers can leverage the UCP for consent at any level. 

Definitions

This section defines terms and acronyms used in this document. 

Consent:  this is the act of a site user granting permissions for some or all web technologies to execute on the site they are visiting. 

Category:  this is a name given to a group of similar advertising technologies.  EX:  Advertising. 

Tag:  another name for a web technology.  Typically, this refers to the block of JavaScript used to execute the technology. 

Vendor:  refers to a company who provides a web technology.  Ex:  Google. 

Prior Consent:  this refers to a legal requirement to gain consent from a user before executing non-essential web technologies during the users site visit. 

Granular Consent:  refers to the ability of a user to consent to a portion of technologies instead of all technologies.  Ex:  consent to use of Advertising tags but not Social tags.  Granular consent can be applied at either a Category or Vendor level. 

Global Consent:  refers to the user allowing all technologies to execute.  This typically happens if a user just “Accepts” the cookie prompt. 

Consent Management Provider (CMP):  a technology used to allow site publishers to comply with various consent laws (Ex:  GDPR). 

What does the Evidon Universal Consent Platform Do? 

The Evidon UCP is a robust, fully-configurable Consent Management Provider (CMP).  Using the UCP allows you to provide a central point of consent gathering.  The Evidon UCP can support consent at any level desired (global, category, or vendor) and can be configured to completely match the look and feel of the publisher site. 

What does Tealium IQ Tag Manager Do? 

The Tealium tag manager provides a centralized place to manage the technologies used on a publishers website.  Using a tag manager allows a publisher to manage their technologies, including things like adding or removing technologies, without having to redeploy their web code when changes need to be made. 

Getting Started

Before you get started setting up consent support for your Tealium tag manager you should have the following information in hand: 

1. Type of consent you want to support (global, category-level, vendor-level) 
2. List of tag categories or vendors that need consent to execute (should be all non-essential technologies). 
3. If you are using Category Consent you will need to know all the Tags that fall under each category for when you assign the rules. 
4. Your Evidon UCP Tag (pulled from the Evidon Privacy Application) 

This document also assumes the following: 

1. You are a current UCP customer 
2. You are a current Tealium customer 
3. You have a working knowledge of how to configure the Tealium IQ Tag Manager 

This document will provide instructions on how to configure different levels of consent in Tealium, but it will not go through things like how to add advertiser tags into Tealium. 

Setting Up Consent Support in Tealiuim

Enabling consent support in Tealium is a 4-step process: 

1. Add the Evidon UCP script as a tag in Tealium
2. Set up the correct consent variable
3. Build the rules
4. Apply the rules to your tags

Add the Evidon UCP Script as a Tag

The first part of setting up consent is to add the Evidon UCP script as a tag in Tealium.  This will allow the UCP tag to be deployed as part of the tag manager instead of directly on the site pages. 

Here is a link to Tealium documentation to augment the instructions in this section: 

https://community.tealiumiq.com/t5/iQ-Tag-Management/Tealium-Custom-Container/ta-p/14015 

Log Into the Evidon Privacy Application 

Go to https://privacy.evidon.com and log in.  Once in, click on the Mange item in the navigation menu.  Once you are in the notice list click on the “Get Site Notice Tag” link to open the dialog containing the UCP script.  Leave this open while you do the next step. 

Open Tealium 

In a new browser window log into your Tealium account.  Once you are logged in go into the Tags section under IQ Tag Management. 

In the section with the title “Manage Your Tags” click on the Add Tag button. 

Currently we are not listed as a vendor in the Tealium Marketplace so our UCP tag needs to be added as a Custom Container.  In the marketplace search bar type in Tealium Custom and that will limit the list to the Tealium Custom Container.  Click the Add button on that item. 

In the Tag Configuration section give this new tag a meaningful title.  We recommend:  Evidon Universal Consent Tag, but whatever makes sense to your team. 

For “Publish Locations” set these up to support your environments correctly.  These settings don’t impact the functionality of the UCP tag. 

In the “Bundle Flag” you can set this to Yes if you want to include the UCP tag as part of the utag delivery.  Or you can leave it set to “No”, the default.  We support either configuration. 

At this point you will Save your configuration.  For some reason Tealium requires a “Save” in order to get to the point where you can modify the template. 

Once the save is complete, you need to modify the template.  You can do this through either the Manage Templates section in the Admin menu, or you can re-open the tag, click on the “Edit” command in the Tag Configuration section.  In the dialog that opens, scroll down to the Advanced section and expand that.  Scroll to the bottom of that and click on the “Edit Templates” command to open the template editor. 

When you open the template editor you will be presented with a very large block of script.  Most of this is boilerplate necessary for Tealium to process the tag.  You will only need to modify one section of this template so don’t be too intimidated by the script. 

In the script editor scroll down until you see the following: 

/* Start Tag Sending Code */ 

          // Insert your tag sending code here. 

/* End Tag Sending Code */ 

That is the only section you will need to modify. 

In the Evidon Privacy Application (which you opened earlier) copy the Tag Template by clicking the “Copy” button on the dialog.   Paste that into the Tealium template editor, replacing the  

        // Insert your tag sending code here. 

With the code.  The result will look like this: 

        /* Start Tag Sending Code */ 



          <script type="text/javascript"> 

    (function (id) { 

        function append(scriptid, url, async) { 

            var d = document, sn = 'script', f = d.getElementsByTagName(sn)[0]; 

            if (!f) f = d.head; 

            var s = d.createElement(sn); 

            s.async = async; 

            s.id = scriptid; 

            s.src=url; 

            s.charset = 'utf-8'; 

            f.parentNode.insertBefore(s, f); 

        } 



        function is2parttld(value) { 

            var tldindicators = ['co', 'com', 'info', 'web', 'info', 'gov', 'edu', 'biz', 'net', 'org']; 

            var countryindicators = ['uk', 'us', 'fr', 'es', 'de', 'at', 'au', 'ae', 'be', 'br', 'ca', 'ch', 'cn', 'co', 'cz', 'dk', 'eg', 'eu', 'fi', 'gb', 'gr', 'hk', 'hr', 'hu', 'ie', 'in', 'jp', 'mx', 'nl', 'no', 'nz', 'pl', 'ro', 'ru', 'se']; 

            return (tldindicators.indexOf(value) !== -1 || countryindicators.indexOf(value) !== -1); 

        } 



        function getRootDomain() { 

            var parts = window.location.hostname.split('.'); 

            if (parts.length === 2) rootDomain = parts[0]; 

            else if (parts.length > 2) { 

              // see if the next to last value is a common tld 

              var part = parts[parts.length - 2]; 

              if (is2parttld(part)) { 

                rootDomain = parts[parts.length - 3]; // go back one more 

              } 

              else { 

                rootDomain = part; 

              } 

            } 



          return rootDomain; 

        } 



        window.evidon = {}; 

        window.evidon.id = id; 

        window.evidon.test = false;  // set to true for non-production testing. 

        //window.evidon.userid = ''; 

         

        var cdn = '//c.evidon.com/', rootDomain = getRootDomain(), noticecdn = cdn + 'sitenotice/'; 

        append('evidon-notice', noticecdn + 'evidon-sitenotice-tag.js', false); 

        append('evidon-location', cdn + 'geo/country.js', true); 

        append('evidon-themes', noticecdn + id + '/snthemes.js', true); 

        if (rootDomain) append('evidon-settings', noticecdn + id + '/' + rootDomain + '/settingsV2.js', true); 



        window.evidon.priorConsentCallback = function (categories, vendors, cookies) { 

            // add the tags which need to wait for prior consent 

            // here.  This should be all your advertising tags and 

            // probably most of your social and tracking tags. 

        } 



        window.evidon.closeCallback = function () { 

            // this is executed if the user closed a UI element without either Accepting (providing consent) 

            // or Declining (declining to provide consent). 

        } 



        window.evidon.consentWithdrawnCallback = function () { 

            // this is exeucted if the user withdraws consent and elects to 

            // no longer allow technologies to run on the site. 

        } 



        window.evidon.consentDeclinedCallback = function () { 

            // this is executed if the user explicitly declines giving consent by 

            // using a Decline button 

        } 

    })(xxx); 

</script> 



        /* End Tag Sending Code */ 

Now that is almost ready, we just need to clean up a little to make it work and take out stuff that isn’t needed. 

Near the beginning and end you will see the following text:  <script>  and </script>.   You need to remove those or the script will not function properly.  Those markers are necessary if you are going to place the script on your site pages, but in Tealium they will cause issues. 

Finally, you can remove the “callback” functions.  There are 4 of them and they all start with “window.evidon.”.  Again, these are useful for running code on your website but not very useful when deployed through Tealium.  Leaving these in will not hurt anything, they are just unnecessary. 

The final code should look like this: 

/* Start Tag Sending Code */ 



    (function (id) { 

        function append(scriptid, url, async) { 

            var d = document, sn = 'script', f = d.getElementsByTagName(sn)[0]; 

            if (!f) f = d.head; 

            var s = d.createElement(sn); 

            s.async = async; 

            s.id = scriptid; 

            s.src=url; 

            s.charset = 'utf-8'; 

            f.parentNode.insertBefore(s, f); 

        } 



        function is2parttld(value) { 

            var tldindicators = ['co', 'com', 'info', 'web', 'info', 'gov', 'edu', 'biz', 'net', 'org']; 

            var countryindicators = ['uk', 'us', 'fr', 'es', 'de', 'at', 'au', 'ae', 'be', 'br', 'ca', 'ch', 'cn', 'co', 'cz', 'dk', 'eg', 'eu', 'fi', 'gb', 'gr', 'hk', 'hr', 'hu', 'ie', 'in', 'jp', 'mx', 'nl', 'no', 'nz', 'pl', 'ro', 'ru', 'se']; 

            return (tldindicators.indexOf(value) !== -1 || countryindicators.indexOf(value) !== -1); 

        } 



        function getRootDomain() { 

            var parts = window.location.hostname.split('.'); 

            if (parts.length === 2) rootDomain = parts[0]; 

            else if (parts.length > 2) { 

              // see if the next to last value is a common tld 

              var part = parts[parts.length - 2]; 

              if (is2parttld(part)) { 

                rootDomain = parts[parts.length - 3]; // go back one more 

              } 

              else { 

                rootDomain = part; 

              } 

            } 



          return rootDomain; 

        } 



        window.evidon = {}; 

        window.evidon.id = id; 

        window.evidon.test = false;  // set to true for non-production testing. 

        //window.evidon.userid = ''; 

         

        var cdn = '//c.evidon.com/', rootDomain = getRootDomain(), noticecdn = cdn + 'sitenotice/'; 

        append('evidon-notice', noticecdn + 'evidon-sitenotice-tag.js', false); 

        append('evidon-location', cdn + 'geo/country.js', true); 

        append('evidon-themes', noticecdn + id + '/snthemes.js', true); 

        if (rootDomain) append('evidon-settings', noticecdn + id + '/' + rootDomain + '/settingsV2.js', true); 

    })(xxx); 



        /* End Tag Sending Code */ 

Once that is all set up, click on the Save Version button at the bottom of the template editor.  Then close the template editor.  Click on the Apply button in the configuration dialog and then Save the whole Tealium configuration. 

Setup the Consent Variables

The information needed for Granular Consent is passed in through variables on the event call.  You need to capture these variables so you can set rules based on them.  This section walks you through the process of creating these variables.  There are only 2 so it isn’t too bad. 

Create the Categories Variable 

The list of categories the user consents to are passed in so you can set up Category Consent.  To create a variable to hold this information do the following: 

1. Log into Tealium
2. Open the IQ Tag Management section
3. Click the “Data Layer” item
4. Click “Add Variable”
5. Leave the Type set to “UDO Variable”
6. Set the Source to “consent_categories” (no quotes)
7. Optionally set the Alias to something helpful like “consentCategories” (again, no quotes)
8. Click “Apply”

Create the Vendors Variable 

The list of vendors the user consents to are passed in so you can set up Vendor Consent.  To create a variable to hold this information do the following: 

1. Log into Tealium
2. Open the IQ Tag Management section
3. Click the “Data Layer” item
4. Click “Add Variable”
5. Leave the Type set to “UDO Variable”
6. Set the Source to “consent_vendors” (no quotes)
7. Optionally set the Alias to something helpful like “consentVendors” (again, no quotes)
8. Click “Apply”

Build the Load Rules

You will need to set up Load Rules based on the type of consent (Global, Category, or Vendor).  These load rules will be applied to tags, telling them when they can load. 

Configuring Load Rules can be a bit challenging since there can be a lot of them, especially if you are using Vendor-level consent.  But this process will walk you through creating one Category rule and one Vendor rule so you can see how it is done. 

One important thing about Rules is the naming convention.  It is important you are able to recognize the rule you want from what may end up being a very large list of rules.  Our recommendation is to be very specific.  For example the rule for Advertiser Consent could be “Advertiser Consent Load Rule”. 

For each of our rules you will need to have 2 sets of conditions.  The first will cover the “All” possibility, which will happen if a user simply Accepts and does not apply granular consent selections.  The other is the rule for the specific category, for the case where a user does make specific selections. 

To make use of the event_name variable we must has the Tealium extension installed. 

To install the Tealium "event_name" data layer variable: 

• Navigate to the "Extensions" tab
• Click "Add Extension"
• When the modal appears click the "Events" tab or type in "Tealium Events" in the search bar.
• Add "Tealium Events"
• To verify that it has been added navigate to the Data Layer tab
• Search for "event_name" and now it should exist

Set up a Category Consent Load Rule 

To set up a Category Consent Load Rule do the following steps: 

1. Log into Tealium
2. Open the IQ Tag Management section
3. Click the “Load Rules” item
4. Click on “Add Load Rule”
5. Set the title to:  <name of category> Consent Load Rule (or something similar)
6. Click on “Select a variable” to show the variable list
7. Select the “event_name” variable (this is native to Tealium)
8. Change “contains” to “equals” by clicking on the list and selecting “equals”
9. Put the following into the final input “evidonConsentGiven” (no quotes)
10. Click the + (plus) sign next to the final input to open another input row.
11. Click on the Select a variable to show the variable list
12. Select the “consent_categories” variable (set up in the last section)
13. Change “contains” to “equals” again
14. In the last input put in “all” (no quotes)
15. Click on the “Add OR Condition” button
16. Repeat steps 6 – 12
17. This time, in the 2^ndrow, leave the “contains” option selected 
18. In the final input put in the name of the category (lower-case).  Ex:  advertising
19. Click Apply to set the Rule

Set up a Vendor Consent Load Rule 

To set up a Vendor Consent Load Rule perform the following steps: 

1. Log into Tealium
2. Open the IQ Tag Management section
3. Click the “Load Rules” item
4. Click on “Add Load Rule”
5. Set the title to:  <name of vendor> Consent Load Rule (or something similar)
6. Click on “Select a variable” to show the variable list
7. Select the “event_name” variable (this is native to Tealium)
8. Change “contains” to “equals” by clicking on the list and selecting “equals”
9. Put the following into the final input “evidonConsentGiven” (no quotes)
10. Click the + (plus) sign next to the final input to open another input row.
11. Click on the Select a variable to show the variable list
12. Select the “consent_vendors” variable (set up in the last section)
13. Change “contains” to “equals” again
14. In the last input put in “all” (no quotes)
15. Click on the “Add OR Condition” button
16. Repeat steps 6 – 12
17. This time, in the 2^ndrow, leave the “contains” option selected 
18. In the final input put in the name of the vendor (lower-case).  Ex:  media_math
19. Click Apply to set the Rule

Set up the Global Consent Load Rule 

To set up the global consent load rule perform the following steps: 

1. Log into Tealium
2. Open the IQ Tag Management section
3. Click the “Load Rules” item
4. Click on “Add Load Rule”
5. Set the title to:  Global Consent Load Rule (or something similar)
6. Click on “Select a variable” to show the variable list
7. Select the “event_name” variable (this is native to Tealium)
8. Change “contains” to “equals” by clicking on the list and selecting “equals”
9. Put the following into the final input “evidonConsentGiven” (no quotes)
10. Click Apply to set the Rule

Apply the Load Rules to your Tags