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. We will also cover how to send martechpasses for data activation on SSPs that are not integrated with Utiq.

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 SSPs 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}

Sending martechpass to SSPs using Prebid

In case you want to do data activation on SSP, or want to do pre-targeting (deal ID), but the SSP is not yet integrated with Utiq (meaning it is not ready to decrypt adtechpass), you can send the martechpass, on top of the adtechpass, with the caveat that martechpass has a certain expiration.

If you decide to do so, you need to follow the whole above process, with the below different actions:

Ensure you use Prebid version 8.47 or higher
The module you need to install is the UtiqMtp ID, the martechpass alternative, from here.
On the Prebid configuration you need to initialize the utiqMtpId, as shown below.
Note that the source will be 'utiq-mtp.com' in this martechpass alternative.
You may like to consider limiting the SSPs that receive the martechpass by adding the bidders array, to make sure they are not forwarding this first party ID to DSPs. We are working with SSPs to blacklist the above source from being send to DSPs, please reach out to csm@utiq.com to verify which are these SSPs.

pbjs.setConfig({
  userSync: {
    userIds: [
      {
        name: "utiqMtpId",
        bidders: ["bidder1", "bidder2", ...]
      },
    ],
  },
});

Below is a diagram that shows the differences of using the adtechpass vs using the martechpass: programmatic-integration-martechpass-in-prebid