DSP prebid integration

Novatiq enables buyers to access audiences of their choice in real-time, using the network verified Hyper ID to enable addressability.

The Hyper ID is an anonymous, unique and transient ad request ‘label’ that is generated by the buy-side and delivered to the buyer via the RTB bid request.

A DSP integration requires access to the Novatiq Hyper ID and the completion of two integration functions:

1. Access to the Novatiq Hyper ID

The DSP uses Hyper IDs to retrieve audiences for real-time activation. Hyper IDs are located in the bidstream managed by prebid. For more information about prebid see https://docs.prebid.org/

The Hyper ID is located within the EIDS source value under “novatiq.com”.

If needed, more about Extended Identifiers (EIDS) can be found in the IAB’s OpenRTB 2.6 spec.

2. ConsumOR audience retrieval

The Novatiq Fusion ConsumOR delivers the audience codes for each DSP’s matched campaigns in real-time. The audience codes are available in ConsumOR when the DSP receives an Open RTB request.

ConsumOR is cloud-based and makes the audience codes available via a standardised interface. Novatiq will provision a Fusion account, including ConsumOR, and provide the endpoint and credential ID for DSP API queries.

Once the Hyper ID has been received by the DSP advertising platform(s) both it and other user IDs contained within the oRTB request must be extracted and utilised as a query within an API call to the Novatiq ConsumOR for retrieval of audience codes that match active campaigns.

Sample API call code for this function can be found in the Appendix – Section 2 – Making a ConsumOR call

The ConsumOR will return json audience ID responses that the user is part of and that have been requested by the DSP for a campaign, to enable the response to form part of the DSP campaign decisioning.

[Note: if the Hyper ID is not recognised or there are no audience codes matching the Hyper ID, an HTTP 204 status is returned.]

3. Audience usage reporting for billing

To ensure Novatiq bills the DSP, accurately the DSP needs to provide Novatiq with near real-time audience usage reports – i.e. impressions delivered using a Hyper ID audience.

A report may be either CSV or json format and should be delivered to a Novatiq Amazon S3 bucket/input folder from between every 5 mins to every hour. Each report file should include:

• Filename – identifying the DSP and the date/time range for the report batch
• Usage report – one line per impression.

Audience usage report fields:

Sample WinLog code for this function can be found in the Appendix – Section 3 – sample winlog formats

Novatiq will supply the S3 bucket name and access credentials for reporting when the DSP registers as a partner.

4. Audience creation – Fusion web UI or API

Novatiq Fusion is a web UI for audience creation and campaign activation, including edit, pause, re-start and extension. It can be utilised as a UI interface accessed from within the DSP environment or provisioned as an API into the DSP UI.

If using the Novatiq UI, access is granted by Novatiq provisioning an admin user within the DSP who can then provision additional users to create and manage audiences and campaigns as needed.

If using the Fusion API integration to the DSP platform for audience and campaign management via the DSP interface a rest API is used.
Creating audiences and launching campaigns via the web UI or API, results in campaign specific audience codes being generated and made available in the expanded campaign dashboard.

The 11 digit audience codes appear, in brackets, under the audience name, e.g. “10000000611”. and must be either copied and pasted into the corresponding campaigns in the DSP campaign management platform or will be automatically added if a full API integration is in place.

To understand more about Fusion please email laura.brennan@novatiq.com for a comprehensive demo.

Appendix – sample code for integration functions

async function fetchSegments(region, dataPartnerId, hyperId, altId) {

    const url = `https://${region}.consumor.io/segments/v1/${dataPartnerId}/${hyperId}/${altId}?v=2`;

    try {

        const response = await fetch(url);

        if (response.status === 404) {

      	    console.log("No segments found");

    	} else if (response.status === 200) {

      	    const data = await response.json();

      	    console.log("Segments:", data);

    	} else {

      	    console.log("Unexpected status code:", response.status);

    	}

    } catch (error) {

        console.error("Error fetching segments:", error);

    }

}

// Example usage

const region = "";

const dataPartnerId = "";

const hyperId = "";

const altId = "";

fetchSegments(region, dataPartnerId, hyperId, altId);

Novatiq provides a test ConsumOR for integration and debugging purposes accessed here:

https://novademo.consumor.io/segments/v1/novademo/f8b2d5ae-02f8-40fd-b2d3-5e26930bf2149999?v=2

This will return a test audience code.