Opera Ads

Appearance

OpenRTB NURL & LURL Guide for Demand/Supply Partners ​

1. Purpose of This Document ​

This document explains the role of NURL and LURL in OpenRTB for an RTB system integration, including:

  • When each URL is used
  • What each URL is expected to do
  • Commonly supported macros (placeholders) and how to encode them
  • Practical examples for Demand/Supply partners

Note: OpenRTB versions and fields vary slightly by spec and implementation. This guide describes the industry-standard intent and common integration expectations.

2. Definitions (What NURL and LURL Are) ​

2.1 NURL (Notification URL / Win Notice) ​

NURL is a URL provided by the bidder (typically the DSP) that the ADX/SSP calls when the bid wins the auction.

Primary goals:

  • Notify the bidder it won (auction result confirmation)
  • Support price- and auction-metadata passback (e.g., clearing price)

Typical timing:

  • Fired by the ADX or SSP immediately after the auction decision (win event)
  • Usually independent of whether the impression is ultimately rendered (implementation-dependent)

Expected behavior:

  • Must respond quickly (e.g., HTTP 200 OK)
  • Should not rely on cookies (usually server-to-server)

2.2 LURL (Loss Notification URL / Loss Notice) ​

LURL is a URL provided by the bidder that the ADX/SSP calls when the bid loses the auction.

Primary goals:

  • Provide loss feedback to help DSP optimization (bid shading, pacing, model training)
  • Indicate why the bid lost (e.g., outbid, filtered, timeout, invalid)

Typical timing:

  • Fired by the ADX or SSP immediately after the auction decision (loss event)

Expected behavior:

  • Must respond quickly (e.g., HTTP 200 OK)
  • Should not rely on cookies (usually server-to-server)

3. Where These Appear in OpenRTB ​

Depending on OpenRTB version and ad type, NURL/LURL are commonly found in:

  • seatbid[].bid[].nurl
  • seatbid[].bid[].lurl

They are returned by the bidder in the bid response, and the ADX/SSP invokes them after the auction.

4. Macro Basics ​

4.1 What Are Macros? ​

Macros are placeholders embedded in the URL that the ADX/SSP replaces at runtime with actual values (e.g., clearing price).

Example (unexpanded): https://dsp.example.com/win?aid=a123&price=${AUCTION_PRICE}

Expanded (illustrative): https://dsp.example.com/win?aid=a123&price=0.83

4.2 Encoding Guidance ​

  • Use URL encoding for macro values that may contain special characters
  • Keep URLs short; avoid excessive query parameters

4.3 GET vs POST ​

  • OperaAds use HTTP GET for NURL/LURL

5. Commonly Used Macros ​

Macro naming is not fully standardized across all exchanges. The following set reflects OperaAds industry practice.

5.1 Win Information (Primarily for NURL) ​

  • ${AUCTION_PRICE}: Clearing / settlement price (CPM)
  • ${AUCTION_MIN_TO_WIN}: Second Clearing / settlement price (CPM)

5.2 Loss Information (Primarily for LURL) ​

  • ${AUCTION_LOSS}: Loss reason code
  • ${AUCTION_MIN_TO_WIN}: Winning or clearing price (if policy allows)
  • ${AUCTION_BIDDER}: The bidder which wins this auction

6. OperaAds NURL&LURL Example Patterns ​

6.1 NURL ​

https://t-odx.op-mobile.opera.com/win?a=a123&amtw=${AUCTION_MIN_TO_WIN}&ap=${AUCTION_PRICE}

6.2 LURL ​

https://t-odx.op-mobile.opera.com/loss?a=a123&al=${AUCTION_LOSS}&amtw=${AUCTION_MIN_TO_WIN}&aucb=${AUCTION_BIDDER}

7. Recommended Integration Practices ​

7.1 Latency & Availability ​

  • Expect high QPS, especially for LURL
  • Respond quickly and avoid synchronous heavy dependencies

7.2 Security ​

  • Always use HTTPS
  • Avoid logging raw personal data

8. Validation Checklist ​

  • NURL endpoint returns HTTP 200 consistently
  • AUCTION_PRICE units and currency are correctly interpreted
  • Missing optional macros are handled safely
  • LURL ingestion can handle large volumes if enabled
  • Monitoring exists for latency, errors, and throughput

9. Appendix: IAB-Defined Loss Reason Codes ​

The following loss reason codes are defined by IAB and are commonly used in OpenRTB LURL implementations. These codes allow DSPs to understand why a bid did not win an auction and to optimize bidding, creative selection, and deal configuration accordingly.

9.1 Auction Outcome & Technical Errors ​

  • 0 — Bid Won The bid won the auction (typically not sent via LURL, but included for completeness).

  • 1 — Internal Error An internal exchange error occurred during auction processing.

  • 2 — Impression Opportunity Expired The auction expired before a valid decision could be made (e.g., timeout).

9.2 Bid Response Validation Errors ​

These indicate issues with the bid response itself.

  • 3 — Invalid Bid Response The bid response was invalid or could not be parsed.

  • 4 — Invalid Deal ID The bid referenced a deal ID that is not recognized or not applicable.

  • 5 — Invalid Auction ID The auction ID in the bid response does not match the request.

  • 6 — Invalid (Malformed) Advertiser Domain The advertiser domain is missing or does not conform to required format.

  • 7 — Missing Markup The ad markup (adm) is missing.

  • 8 — Missing Creative ID The creative ID is missing from the bid response.

  • 9 — Missing Bid Price The bid price is missing or invalid.

  • 10 — Missing Minimum Creative Approval Data Required creative metadata for approval or policy checks is missing.

9.3 Price & Auction Competition ​

These indicate the bid was valid but not competitive in the auction.

  • 100 — Bid Below Auction Floor The bid price was below the exchange or placement floor price.

  • 101 — Bid Below Deal Floor The bid price was below the minimum price defined for the deal.

  • 102 — Lost to Higher Bid Another bid won the auction with a higher effective price.

  • 103 — Lost to a Bid for a PMP Deal A bid associated with a PMP (Private Marketplace) deal took precedence.

  • 104 — Buyer Seat Blocked The buyer seat was blocked by publisher or exchange configuration.

9.4 Creative Filtering (General) ​

These indicate the bid lost due to creative-level policy or compatibility issues.

  • 200 — Creative Filtered (General) Creative was filtered for an unspecified or unknown reason.

  • 201 — Creative Filtered: Pending Exchange Processing Creative is pending approval, review, or transcoding by the exchange.

  • 202 — Creative Filtered: Disapproved by Exchange Creative was explicitly disapproved.

  • 203 — Creative Filtered: Size Not Allowed Creative dimensions are not permitted for the placement.

  • 204 — Creative Filtered: Incorrect Creative Format Creative format does not match the required type (e.g., video vs banner).

  • 205 — Creative Filtered: Advertiser Exclusions Advertiser is excluded by publisher or exchange rules.

  • 206 — Creative Filtered: App Bundle Exclusions Creative is not allowed for the target app bundle.

  • 207 — Creative Filtered: Not Secure Creative or landing page does not meet security requirements (e.g., HTTPS).

  • 208 — Creative Filtered: Language Exclusions Creative language is not allowed for the inventory.

  • 209 — Creative Filtered: Category Exclusions Creative category is blocked (e.g., sensitive content).

  • 210 — Creative Filtered: Creative Attribute Exclusions Creative attributes (e.g., audio autoplay, flashing) are not allowed.

  • 211 — Creative Filtered: Ad Type Exclusions The ad type (e.g., interstitial, expandable) is not permitted.

  • 212 — Creative Filtered: Animation Too Long Creative animation exceeds maximum allowed duration.

  • 213 — Creative Filtered: Not Allowed in PMP Deal Creative does not comply with PMP deal constraints.

9.5 Exchange-Specific Codes ​

  • ≥ 1000 — Exchange-Specific Loss Codes Loss reasons defined by the exchange. These codes must be documented and communicated to bidders in advance, including semantics and any associated macro availability.

Implementation Note: Not all exchanges expose all loss reason codes, and some codes may be suppressed due to privacy, policy, or performance considerations. DSPs should treat loss reason reporting as best-effort and design systems to handle missing or unknown codes gracefully.