Skip to main content

Closing the Loop: ProductABC + ProductXYZ

Info/Context

Type: End-user documentation
Audience: CompanyName users and employees
Purpose: A conceptual guide that describes how (and why) to use ProductABC and ProductXYZ together. Both products are tools that assess the quality of ad inventory, but they do their respective jobs at different times: ProductABC analyzes ad inventory while it's being auctioned off (pre-bid), whereas ProductXYZ analyzes that same ad inventory after the auction has ended (post-bid).
Note: Some words and phrases are enclosed in [brackets] to represent hyperlinks to other docs not included in this sample library.

[ProductABC] and [ProductXYZ] are designed to work together. By comparing ProductABC's pre-bid predictions with ProductXYZ's post-bid detection and analysis, CompanyName can create a "closed-loop" ecosystem with data that's richer than the sum of its parts.

The benefits of closing the loop are twofold: not only does this ecosystem provide you with a more complete picture of the ad inventory that you bid on and the impressions that you serve, it also helps us here at CompanyName verify that ProductABC's predictions are accurate and lets us continuously refine our detection models to identify sophisticated invalid traffic.

Components​

A combined ProductABC + ProductXYZ integration has three distinct components. All three of these components work together: ProductABC's pre-bid component helps you decide whether to bid on the ad inventory offered in a particular bid request, and ProductXYZ's two post-bid components provide you with more information about the ad impressions that follow.

  • A ProductABC integration (pre-bid): Every time you receive a bid request, you should send the details of this bid request to ProductABC. ProductABC will return our prediction of whether the bid request is a form of invalid traffic. Based on this response, you can then choose to bid (or not bid) on the ad inventory being sold.
  • ProductXYZ's [detection tag] (post-bid): If you make a bid on the ad inventory and win, you'll need to serve a detection tag alongside the ensuing ad impression. This detection tag is a lightweight code snippet that collects the signals that power ProductXYZ's post-bid IVT analysis.
  • An [OptionalFeature] integration (post-bid): Optionally, for every detection tag you serve, you can either make a separate postback call to CompanyName or share information about the associated impressions via Snowflake. This OptionalFeature data helps us identify any fraudsters who try to evade our detection tags.
NOTE

Since you may not bid on (or win) every bid request you receive, not every prediction returned by ProductABC will have a corresponding ad impression. In these cases, you won't need to serve a detection tag or make an OptionalFeature call, which also means you won't need to close the loop for those bid requests—you can't close the loop if ProductXYZ never recorded an impression in the first place!

How to close the loop​

After you've set up the necessary components, you'll still need to create a link between your ProductABC and ProductXYZ integrations. This link is what enables us to join your pre-bid ProductABC data and your post-bid ProductXYZ data.

NOTE

ProductABC and ProductXYZ won't automatically share data with each other. To close the loop between them, you must follow the instructions outlined here.

Loop ID (ld)​

Whenever you send the details of a bid request to ProductABC (either via the [ProductABC API] or the ProductABC SDK), ProductABC's response will include a field called callID. Since ProductABC assigns a unique callID value to each incoming bid request, we can use this field to close the loop between ProductABC data and ProductXYZ data.

To link a bid request with its corresponding ad impression, you'll need to take the value of ProductABC's callID field and feed it back through ProductXYZ's detection tag as the [Loop ID (ld)] tag parameter.

NOTE

If your ProductABC integration is built on the ProductABC API, callID will return a UUID string, which you can pass to ProductXYZ's detection tag without any additional steps.

If your ProductABC integration is built on the ProductABC SDK, callID will return a base64-encoded raw byte value. You must convert this raw byte value to a UUID string, then pass the resulting UUID string to ProductXYZ's detection tag.

For example, if the ProductABC API returns "callID": "d2260bd4-4d81-11e8-88da-600308952712" for a particular bid request, you must include ld=d2260bd4-4d81-11e8-88da-600308952712 in the detection tag served alongside the ensuing ad impression. If the ProductABC SDK returns "callID": "gUpKy2IcRPyqzwAApkz3xA" for a particular bid request, you must convert this value to a UUID string, then include ld=814a4acb-621c-44fc-aacf-a64cf7c4 in the detection tag served alongside the ensuing ad impression.

Call Response (cr)​

Additionally, you'll need to send information about ProductABC's behavior to ProductXYZ via the [Call Response (cr)] detection tag parameter. This field helps us measure and troubleshoot ProductABC's performance.

Call Response is an integer with possible values between 0 and 4. For each ad impression you serve, you must configure the Call Response tag parameter to match the value that describes how ProductABC interacted with the impression's corresponding bid request:

  • (0) N/A: You did not send the impression's corresponding bid request to ProductABC, so ProductABC did not have an opportunity to make an IVT prediction.
  • (1) Timeout: You sent the impression's corresponding bid request to ProductABC, but ProductABC timed out before it could respond.
  • (2) Error: You sent the impression's corresponding bid request to ProductABC, but ProductABC responded with an error.
  • (3) Success: You sent the impression's corresponding bid request to ProductABC and ProductABC successfully returned an IVT prediction. (Note that the IVT decision itself is irrelevant; both a successful IVT=true response and a successful IVT=false response would warrant a value of 3.)
  • (4) Other: Any other scenario, like a partial response that included an IVT prediction but was missing a list of IVT categories.

For example, if the ProductABC API returns an ERROR: 400 response for a particular bid request, you must include cr=2 in the detection tag served alongside the ensuing ad impression.