Website Integration: "Utiq Separate pop-up Model"

Integration with the Utiq service is achieved by including the Utiq loader script (utiqLoader.js).

Utiq Loader Script

The loader script is made available at the Utiq subdomain of your website, e.g. if your website’s domain is example.com then the loader script will be hosted at https://utiq.example.com/utiqLoader.js.

The loader script is responsible for:

Checking if consent has been given for the Utiq service.
Checking if the user is accessing the website via an eligible Telco network connection.
Loading and displaying the Utiq Consent Manager popup (utiqConsentManager.js).
Setting and removing the martechpass (mtid) and adtechpass (atid) tokens in Local Storage.
Providing JS API methods and event listeners.

How to integrate the Utiq Script

The tag can be integrated using a Tag Manager such as GTM, Adobe or Tealium IQ using custom HTML or a script wrapper function that calls for the utiqLoader.js script.

To incorporate the Utiq script into your website, various integration methods are available, ensuring compatibility with diverse setups. Whether utilizing a Tag Manager like GTM, Adobe, or Tealium IQ, or directly embedding the script through custom HTML or a script wrapper function, the following examples illustrate straightforward implementation.

Using ES6 or greater JavaScript Version

For Tag Manager integration, create a new custom HTML tag and inject the Utiq loader script using a script wrapper function. The example below demonstrates how to achieve this using JavaScript

JS

window.Utiq = window.Utiq || {};
window.Utiq.config = {
  customizationOptions: {
    websiteLogoUrl: "https://www.example.com/images/logo.svg",
    buttons: {
      bodyColor: '#ff0066',
      textColor: '#000000',
      radius: 5,
    },
    contentTextColor: '#000000'
  },
};
(() => {
  const s = document.createElement("script")
  s.type = 'text/javascript';
  s.src = "https://utiq.example.com/utiqLoader.js"
  s.async = true;
  document.head.appendChild(s)
})();

Make sure that no other element (like ads delivered as overlays) exceeds z-index of 9999999999, so that Utiq separate pop-up is always visible to the user.

Using up to ES5 JavaScript Version (Google Tag Manager)

JS

<script>
  window.Utiq = window.Utiq || {};
  window.Utiq.config = {
    customizationOptions: {
      websiteLogoUrl: "https://www.example.com/images/logo.svg",
      buttons: {
        bodyColor: '#ff0066',
        textColor: '#000000',
        radius: 5,
      },
      contentTextColor: '#000000'
    },
  };
  (function () {
    var s = document.createElement("script");
    s.type = 'text/javascript';
    s.src = "https://utiq.example.com/utiqLoader.js";
    s.async = true;
    document.head.appendChild(s);
  })();
</script>

Direct Script Embedding

Alternatively, you can directly embed the Utiq loader script within your HTML code. Add the following line to your HTML file to initiate the integration:

HTML

<script src="https://utiq.example.com/utiqLoader.js" async></script>

Additional configuration options are available via Utiq.config object. Setting the configuration entries and their descriptions are explained in the Configuration Options section.

Utiq Script for the WebViews

You can interact with Utiq by using it within the webviews. To interact with Utiq events, you need to add the listeners for the Utiq events, as you would do with a regular implementation. To be able to send the information you get from the events to iOS or Android system, you also need to add handlers for the respective system, inside the event callbacks.

For mobile apps, if you want to send the information about consent change from Utiq, whenever the consent is updated, you need to use a proper, so called, “contracts” you have set up in the mobile application. For the mobile code requirement, see Mobile SDK implementation section for WebViews.

For the iOS apps, you need to use the postMessage from the window.webkit’s handler. For example:

JS

window.Utiq ||= {};
window.Utiq.config = {
  listeners: {
    onConsentUpdateFinished: ({ isConsentGranted }) => {
      if (window.webkit?.messageHandlers?.iOSUtiq) {
        window.webkit.messageHandlers.iOSUtiq.postMessage({
          isConsentGranted: isConsentGranted,
        });
      } else {
        console.warn('No Webkit available in the window object');
      }
    },
  },
};
(() => {
  const a = document.createElement('script');
  a.type = 'text/javascript';
  a.src = 'https://utiq.example.com/utiqLoader.js';
  s.async = true;
  document.head.appendChild(a);
})();

iOSUtiq is just an example name for the iOS contract.

For the Android apps, you need to use the Android function directly from the window object:

JS

window.Utiq ||= {};
window.Utiq.config = {
  listeners: {
    onConsentUpdateFinished: ({ isConsentGranted }) => {
      if (window.AndroidUtiq) {
        AndroidUtiq.onConsentChange(isConsentGranted);
      } else {
        console.warn('No AndroidUtiq function available in the window object');
      }
    },
  },
};
(() => {
  const a = document.createElement('script');
  a.type = 'text/javascript';
  a.src = 'https://utiq.example.com/utiqLoader.js';
  s.async = true;
  document.head.appendChild(a);
})();

AndroidUtiq is just an example name for the Android contract.

Snippets above serve as an example on how to send information to your mobile app from the Utiq environment for the consent change, but you can use any Utiq event for that purpose.

When to fire the Utiq Script

The utiqLoader.js JavaScript should be loaded if and only if there is explicit consent given by the user for all purposes on the website’s main CMP popup, i.e., user clicks the “Accept All” button on the CMP (see 1B. Consent Experience: "Utiq Separate pop-up model" (Utiq’s out-of-the-box dedicated consent pop-up)).

Utiq Integration with TCF Compliant CMP

This guide provides instructions on integrating Utiq with a Consent Management Platform (CMP) compliant with Transparency and Consent Framework (TCF 2.0 or greater version). The integration ensures that the Utiq script runs seamlessly based on user consent within the specified purposes defined by the TCF framework. To validate if your CMP is compliant with the Transparency and Consent Framework visit the (dedicated IAB page).

Note: In this document, various examples of user CMP permissions are provided. Brand/Publisher is responsible to determine the appropriate condition(s) (purposes, vendors, etc.) to fire Utiq script.

This scenario assumes that your website is utilizing a TCF compliant CMP. The provided code snippets below demonstrates how to integrate the Utiq script to run as soon as the user consents to the first and second purpose of TCF.

JS

__tcfapi("addEventListener", null, function (e) {
  var purposes = Object.keys(e.purpose.consents);
  if (e.eventStatus != "cmpuishown" && purposes.indexOf("1") > -1 && purposes.indexOf("2") > -1 && ...)  { // Select appropriate User Purposes to fire Utiq Script
    (() => {
      const s = document.createElement("script");
      s.type = 'text/javascript';
      s.src = "https://utiq.example.com/utiqLoader.js"; // Replace with the corresponding subdomain
      s.async = true;
      document.head.appendChild(s);
    })();
  }
});

The provided snippets leverage the TCF API to listen for consent changes within the CMP. The script dynamically loads the Utiq script into the web page when the user consents to the defined purposes. These integrations enable a seamless and privacy-compliant execution of Utiq, respecting user preferences and privacy regulations.

Utiq Integration with Custom CMP

For instances where a custom CMP solution is utilized, this integration approach provides a flexible and adaptable method to activate the Utiq script.

JS

(function() {
  var isUtiqInitialized = false;

  var triggerUtiq = function() {
    (() => {
      if (!isUtiqInitialized) {
        isUtiqInitialized = true;
        const s = document.createElement("script");
        s.type = "text/javascript";
        // Replace with the corresponding subdomain
        s.src = "https://utiq.example.com/utiqLoader.js";
        s.async = true;
        document.head.appendChild(s);
      }
    })();

    // Stop checking for the cookie
    clearInterval(cookieCheckInterval);
    // Remove event listener
    btn && btn.removeEventListener("click", triggerUtiq);
  };

  // Checking if the cookie exists
  var cookieCheckInterval = window.setInterval(function() {
    // Replace the cookie name "all_cmp_accepted" and the cookie value "true" with the
    // corresponding cookie name and value that represent that a user has accepted all cookies
    if (document.cookie.indexOf("all_cmp_accepted=true") !== -1) {
      triggerUtiq();
    }
    // You might want to adjust this interval time as needed
  }, 100);

  // Attaching event to button if it exists
  // Replace the Element Selector "_some_element_selector" with the Element Selector representing the "Accept All" call to action (button) of your CMP.
  var btn = document.getElementById("_some_element_selector");

  if (btn) {
    btn.addEventListener("click", triggerUtiq);
  }
})();

The provided code snippet offers a customizable script that, when integrated into the CMP workflow, dynamically loads the Utiq script only when the user explicitly accepts all cookies. The script includes functionalities to check for the existence of a relevant consent cookie, ensuring that Utiq fires on all relevant pages once consent is granted. Additionally, it offers the capability to attach an event listener to a designated CMP button, enabling the seamless integration of Utiq into the user consent experience.