Utiq Tech Docs Home > Utiq Service > Programmatic Integration

Programmatic Integration

Here we go through the process of how Publishers can send adtechpasses to DSPs via their SSP, allowing use cases such as targeting and frequency capping. Below are the integration steps for passing the adtechpass using Prebid.js, with support for other potential integrations.

Prerequisites

The Publisher has implemented the Utiq loader script on their website.
The user has given consent for the Utiq service and is accessing the website via an eligible Telco network connection.
The adtechpass is available in local storage under the utiqPass key.

To confirm that the adtechpass is available you can run the following command in your browser console:

> Utiq.API.getIdGraphEntry("atid")
-> 'gB4jvq2Jwm5X5+EN4IccBuK+N251EKix6lnMs8XyL4O/tr95G7fi5cuoOT3RwjzDi0eTUdvKR9nn6gyqwoswvw==-ndye'

If an adtechpass is returned, then your integration is ready to go.

To send the adtechpass via an SSP using Prebid, you need to:

Ensure you use Prebid version 8.2 or higher.

To check your Prebid version, run the following command in your browser console:
```
> pbjs.version
-> 'v8.9.0'
```

Ensure you enabled the “Utiq” user id module in your prebid version

To check if the Utiq user id module is enabled, run the following command in your browser console:

> pbjs.installedModules
-> ['appnexusBidAdapter', 'consentManagement', 'consentManagementGpp', 'consentManagementUsp', 'enrichmentFpdModule', 'gdprEnforcement', 'gppControl_usnat', 'gptPreAuction', 'pubProvidedIdSystem', 'rubiconBidAdapter', 'userId', 'utiqSystem']

If any of the two requirements are not fulfilled, please make sure to update your Prebid version and enable the Utiq user id module here.

Sending adtechpass via the SSP using Prebid

Prebid Configuration Update

If all prerequisites have been fulfilled, you can now update your prebid configuration to start sending the Utiq passes to your SSPs.

To do that, simply add the below lines to your prebid configuration:

		pbjs.setConfig({
  userSync: {
    userIds: [{
      name: "utiq"
    }]
  }
});

Full documentation about the Utiq Prebid user id module is available here.

TCF configuration

If you use the Prebid GDPR Enforcement Module, which prevents access to local storage for non consented vendors, you may need to add a vendor exception for the Utiq user id module to work, as Utiq is not a TCF vendor and will be automatically blocked by Prebid when GDPR Enforcement is enabled. Utiq performs its own consent check, outside TCF, to ensure that there is no device storage access in the absence of consent.

To do that, you can use below configuration:

pbjs.setConfig({
  consentManagement: {
    gdpr: {
      cmpApi: 'iab',   // activates the enforcement module
      rules: [{        // these are the default values
        purpose: "storage",
        enforcePurpose: true, // block localStorage based on purpose 1 of TCF
        enforceVendor: true,  // block localStorage for non consented / non TCF vendors
        vendorExceptions: ["utiq"] // configuration line to add to make utiq exception
      }]
    }
  }
});

Validation

To confirm that the implementation is correct, you can type the below command in your browser console:

> pbjs.getUserIdsAsEidBySource("utiq.com")
-> {source: 'utiq.com', uids: Array(1)}

if the eid object with source "utiq.com" is returned, you are all set!

You can also confirm the adtechpass is sent as part of the payload from the SSPs. This check however, will depend on each SSP. For example, for Appnexus SSP, you can check that "utiq.com" is present as part of the eids object in the appnexus prebid call as per below example:

Example OpenRTB Bid Request

Here is an example of an OpenRTB bid request with the utiq user id:

https://adtech.com/xxx/bids 

Content:

{"site": {"id": "123456", "domain": "domain.com", "page": "domain.com", "publisher": {"id": "1234", "name": "Domain.com"}}, "device": {"ip": "172.31.1.0", "geo": {"country": "GBR"}, "language": "en", "devicetype": 2, "ext": {"truncated_ip": 1}, "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.69 Safari/537.36"}, "user": {"id": "37801268-60e0-491b-a4fd-17c416a6d99c", "data": [{"id": "123456"}],
    "ext": {
      "eids": [
        {
          "source": "utiq.com",
          "uids": [
            {
              "id": "fH6cXAjRWrVKqvH9bE/jriedN1JX3v0VyFOSPR9yQbqCHTSnR6/BEB41mln4fuyla9DtCDnehmC4m2DnhRpbBg==-xxxx"
            }
          ]
        }
      ]
    }
  }, "wseat": ["5515"], "cur": ["EUR"], "regs": {"ext": {"gdpr": 0}}, "ext": {}, "source": {"ext": {"schain": {"ver": "1.0", "complete": 1, "nodes": [{"asi": "domain.com", "sid": "1234", "hp": 1}]}}}, "id": "65424020-4e69-4096-973a-2212a64a58cb", "imp": [{"id": "1", "banner": {"id": "1", "pos": 1, "format": [{"w": 728, "h": 90}], "w": 728, "h": 90}, "bidfloor": 0.01, "bidfloorcur": "EUR", "secure": 0, "pmp": {"deals": [{"id": "12345678", "bidfloor": 0.01, "bidfloorcur": "EUR", "wseat": ["1234"], "at": 3}], "private_auction": 1}, "tagid": "123456"}], "at": 1}