Accessing the Utiq Passes

The Utiq passes and metadata you can access, are the following:

• mtid → martechpass (mobile start with 'mt1-' while fixed start with 'mt2-')

• atid → adtechpass

• attrid → attributionpass

• category → 'mobile' or 'fixed', to differentiate if Utiq IDs are generated based the mobile connection, or the fixed (household) connection

• ttl → The TTL (Time To Live) of when the martechpass expires

• domain → The domain for which the consent has been granted for

These passes are enabled based on agreement with Utiq - please contact onboard@utiq.com

Multi-Connection Utiq Passes

Utiq supports multi-connection identification, which means that after initial successful identification, either being mobile or fixed, Utiq SDK will keep doing re-identification retrials every 10' to potentially identify user on the other connection (fixed or mobile).

If successfully done so, both passes will be stored in user’s utiqPass localStorage key and can be retrieved by Utiq API, by asking for entries in onIdsAvailable event listener or providing an array param [] in getIdGraphEntry method. Utiq API will be providing an array of passes, of which the first entry will be of the latest identified connection. Look at the example below to see how this is achieved.

If these methods are not used, even if utiqPass contains more than one connection, then Utiq API will be providing the pass of only the latest identified connection.

There are two ways to retrieve these values:

1a. Using the onIdsAvailable event listener (recommended) - asking for a single / latest identified connection

Example using Utiq configuration, if you are the one invoking utiqLoader.js

window.Utiq ||= {};
window.Utiq.config = {
  listeners: {
    onIdsAvailable: ({ mtid, atid, attrid, category, ttl, domain }) => {
      // Single callback action
    }
  }
};

Example using the addEventListener API, if you are a third party, ensuring you can interact with Utiq SDK, regardless of which script gets loaded first, avoiding race conditioning issues:

window.Utiq ||= {};
window.Utiq.queue ||= [];

const handleIdsAvailable = ({ mtid, atid, attrid, category, ttl, domain }) => {
  // Callback action for onIdsAvailable
};

window.Utiq.queue.push(() => {
  window.Utiq.API.addEventListener('onIdsAvailable', handleIdsAvailable);
});

1b. Using the onIdsAvailable event listener (recommended) - asking for a multi-connection identification

Example using Utiq configuration, if you are the one invoking utiqLoader.js

window.Utiq ||= {};
window.Utiq.config = {
  listeners: {
    onIdsAvailable: ({ entries }) => {
      // Single callback action
    }
  }
};

entries will return an array such as [{ mtid: 'mtid1', atid: 'atid1' ... }, { mtid: 'mtid2', atid: 'atid2' ... }, ...]

Example using the addEventListener API, if you are a third party, ensuring you can interact with Utiq SDK, regardless of which script gets loaded first, avoiding race conditioning issues:

window.Utiq ||= {};
window.Utiq.queue ||= [];

const handleIdsAvailable = ({ entries }) => {
  // Callback action for onIdsAvailable
};

window.Utiq.queue.push(() => {
  window.Utiq.API.addEventListener('onIdsAvailable', handleIdsAvailable);
});

entries will return an array such as [{ mtid: 'mtid1', atid: 'atid1' ... }, { mtid: 'mtid2', atid: 'atid2' ... }, ...]

2a. Using the getIdGraphEntry API method - asking for a single / latest identified connection

Example:

try {
  const martechpass = window.Utiq.API.getIdGraphEntry('mtid')
  console.log(`Utiq martechpass: ${martechpass}`)
  const adtechpass = window.Utiq.API.getIdGraphEntry('atid')
  console.log(`Utiq adtechpass: ${adtechpass}`)
  const attributionpass = window.Utiq.API.getIdGraphEntry('attrid')
  console.log(`Utiq attributionpass: ${attributionpass}`)
  const category = window.Utiq.API.getIdGraphEntry('category')
  console.log(`Utiq category: ${category}`)
  const ttl = window.Utiq.API.getIdGraphEntry('ttl')
  console.log(`Utiq category: ${ttl}`)
  const domain = window.Utiq.API.getIdGraphEntry('domain')
  console.log(`Utiq category: ${domain}`)
} catch (err) {
  console.error(`getIdGraphEntry API call failed. Reason: ${err.message}`)
}

2b. Using the getIdGraphEntry API method - asking for a multi-connection identification

Example:

try {
  const martechpass = window.Utiq.API.getIdGraphEntry(['mtid'])
  console.log(`Utiq martechpass: ${martechpass}`)
  const adtechpass = window.Utiq.API.getIdGraphEntry(['atid'])
  console.log(`Utiq adtechpass: ${adtechpass}`)
  const attributionpass = window.Utiq.API.getIdGraphEntry(['attrid'])
  console.log(`Utiq attributionpass: ${attributionpass}`)
  const category = window.Utiq.API.getIdGraphEntry(['category'])
  console.log(`Utiq category: ${category}`)
  const ttl = window.Utiq.API.getIdGraphEntry(['ttl'])
  console.log(`Utiq category: ${ttl}`)
  const domain = window.Utiq.API.getIdGraphEntry(['domain'])
  console.log(`Utiq category: ${domain}`)
} catch (err) {
  console.error(`getIdGraphEntry API call failed. Reason: ${err.message}`)
}

Note that string(s) in array parameters will returns the specific field(s) from all connections. You can use window.Utiq.API.getIdGraphEntry([]) to get all passes with all their fields as an object

First Page Utiq Passes Optimization

If you want to optimize the Utiq Passes timing on the first page of your website, and be available on those bid requests and/or other marketing platform integrations, and not from second page only, so that you can get more value out of Utiq, then you could consider using our event listener onFlowCompleted, with the below logic.

Don't call Prebid and/or other marketing platform integrations after CMP acceptance but wait to call them when this event listener fires.

This event is dispatched when Utiq has completed its flow, either user was eligible and accepted/rejected, user had accepted/rejected on previous session, or user was not eligible.