DSP Integration

OpenRTB 2.5 -- First-Price Auction -- VAST/MRAID

1. Overview

Oprello operates as a mobile SSP and ad exchange. We send OpenRTB 2.5 compliant bid requests to registered DSP endpoints and run a first-price auction across all valid responses. Winning creatives are served to mobile app users via our native Android and iOS SDKs.

Supported Ad Formats

Banner -- standard display sizes (320x50, 300x250, 728x90, and more)
Interstitial -- full-screen static or video (VAST/MRAID)
Rewarded -- full-screen video with reward callback
Native -- OpenRTB Native 1.2 assets (title, image, CTA, data)
App Open -- full-screen ad on app launch (treated as interstitial in OpenRTB)

Protocols

VAST 2.0–4.x (with wrappers) for video creatives
MRAID 3.0 for rich media creatives
OpenRTB Native 1.2 for native ad assets

2. Endpoint

Oprello sends HTTP POST bid requests to your registered DSP endpoint. All communication is server-to-server over HTTPS.

POST https://your-dsp-endpoint.com/bid
Content-Type: application/json

Configure your endpoint URL, supported ad formats, and supported platforms in the Oprello dashboard under DSP Bidders. You will be assigned a bidder ID.

Timeout

The tmax field in the bid request indicates the maximum time (in milliseconds) Oprello will wait for your response. Responses received after tmax are discarded. Typical values range from 500ms to 1000ms.

3. Bid Request Format

Oprello sends a standard OpenRTB 2.5 bid request. Below is an example for a banner ad:

{
  "id": "1742000000000-abc123-def456",
  "imp": [
    {
      "id": "1",
      "tagid": "ad-unit-uuid",
      "bidfloor": 0.50,
      "bidfloorcur": "USD",
      "secure": 1,
      "banner": {
        "w": 320,
        "h": 50,
        "format": [{ "w": 320, "h": 50 }]
      }
    }
  ],
  "app": {
    "bundle": "com.example.myapp",
    "name": "My App",
    "ver": "2.1.0",
    "storeurl": "https://apps.apple.com/app/id123456789"
  },
  "device": {
    "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)...",
    "ip": "203.0.113.1",
    "devicetype": 4,
    "os": "iOS",
    "osv": "17.0",
    "make": "Apple",
    "model": "iPhone15,2",
    "w": 390,
    "h": 844,
    "pxratio": 3.0,
    "ifa": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "lmt": 0,
    "connectiontype": 2,
    "language": "en",
    "geo": {
      "country": "US",
      "type": 2
    },
    "ext": {
      "atts": 3
    }
  },
  "regs": {
    "coppa": 0,
    "ext": {
      "gdpr": 0,
      "us_privacy": "1YNN",
      "gpp": "...",
      "gpp_sid": [2, 6]
    }
  },
  "user": {
    "ext": {
      "consent": "TCF_CONSENT_STRING"
    }
  },
  "source": {
    "ext": {
      "schain": {
        "ver": "1.0",
        "complete": 1,
        "nodes": [
          {
            "asi": "oprello.com",
            "sid": "publisher-account-id",
            "hp": 1,
            "rid": "transaction-id",
            "name": "Oprello",
            "domain": "oprello.com"
          }
        ]
      }
    }
  },
  "tmax": 900,
  "at": 1,
  "bcat": ["IAB25-3"],
  "badv": ["blocked-advertiser.com"],
  "bapp": []
}

Interstitial / Rewarded / App Open

For full-screen ad formats, the impression object includes both video and instl fields:

{
  "id": "1",
  "tagid": "ad-unit-uuid",
  "bidfloor": 1.00,
  "bidfloorcur": "USD",
  "secure": 1,
  "instl": 1,
  "video": {
    "mimes": ["video/mp4", "video/webm", "video/3gpp"],
    "protocols": [2, 3, 5, 6],
    "w": 390,
    "h": 844,
    "linearity": 1,
    "minduration": 5,
    "maxduration": 30,
    "startdelay": 0,
    "placement": 5,
    "skip": 1,
    "api": [3, 5, 6],
    "companiontype": [1, 2]
  }
}

Rewarded ads additionally include "rwdd": 1 and "skip": 0 (non-skippable). Note: rwdd is an OpenRTB 2.6 extension placed at imp.rwdd. For OpenRTB 2.5 compatibility, rewarded status is also signaled via imp.video.ext.rewarded: 1.

Native

Native bid requests include the OpenRTB Native 1.2 request payload:

{
  "id": "1",
  "tagid": "ad-unit-uuid",
  "bidfloor": 0.30,
  "bidfloorcur": "USD",
  "secure": 1,
  "native": {
    "ver": "1.2",
    "request": "{"ver":"1.2","assets":[{"id":1,"required":1,"img":{"type":3,"wmin":300,"hmin":300}},{"id":2,"required":1,"title":{"len":90}},{"id":3,"required":1,"data":{"type":2,"len":140}},{"id":4,"required":0,"data":{"type":12,"len":20}},{"id":5,"required":0,"img":{"type":1,"wmin":80,"hmin":80}}]}"
  }
}

4. Bid Response Format

Return a standard OpenRTB 2.5 bid response. The adm field should contain your creative markup (HTML, VAST XML, MRAID, or native JSON).

{
  "id": "1742000000000-abc123-def456",
  "seatbid": [
    {
      "seat": "your-seat-id",
      "bid": [
        {
          "id": "bid-001",
          "impid": "1",
          "price": 2.50,
          "adm": "<VAST version=\"3.0\">...</VAST>",
          "adomain": ["advertiser.com"],
          "crid": "creative-123",
          "cid": "campaign-456",
          "w": 320,
          "h": 480,
          "cat": ["IAB1"],
          "nurl": "https://your-dsp.com/win?price=${AUCTION_PRICE}",
          "skadn": {
            "version": "4.0",
            "network": "your-skadnetwork-id.skadnetwork",
            "campaign": "42",
            "itunesitem": "123456789",
            "nonce": "unique-nonce",
            "signature": "base64-signature",
            "timestamp": "1700000000",
            "sourceidentifier": "1234"
          }
        }
      ]
    }
  ],
  "cur": "USD"
}

No-Bid Response

If you do not wish to bid, return an empty seatbid array or HTTP 204:

{
  "id": "1742000000000-abc123-def456",
  "seatbid": [],
  "cur": "USD"
}

5. Auction Mechanics

First-Price Auction

Oprello runs a first-price auction ("at": 1). The highest valid bid wins, and the winner pays their bid price.

Deal Bids

Deal bids take priority over open-auction bids. Oprello supports three deal types:

Preferred Deal -- fixed-price deal; bid must meet the agreed price.
Programmatic Guaranteed -- guaranteed fixed-price deal.
Private Auction -- deal bids compete among themselves on price.

Include your deal ID in the bid response using the dealid field.

Blocklists

Publishers can configure blocklists for advertiser domains (badv), IAB categories (bcat), and app bundles (bapp). These are included in the bid request. Bids that match a blocklist entry are rejected.

Bid Floor

The bidfloor in the impression object is the minimum CPM. Bids below the floor are rejected. Floors are set per ad unit and may use dynamic floor pricing.

6. Event Tracking

Oprello fires the following event URLs from your bid response:

Field	When Fired	Description
`nurl`	Auction win	Win notice URL. Fired when your bid wins the auction.
`lurl`	Auction loss	Loss notice URL. Fired when your bid loses the auction.
`burl`	Billing	Billing notice URL. Fired when the impression is confirmed billable.

Additionally, VAST tracking events (impression, start, firstQuartile, midpoint, thirdQuartile, complete, click) are fired from within the SDK's video player for video creatives.

7. Macros

Oprello supports the following OpenRTB macros in your nurl, lurl, burl, and adm fields:

Macro	Replacement
`${AUCTION_PRICE}`	The winning bid price in CPM (USD)
`${AUCTION_ID}`	The auction/transaction ID
`${AUCTION_BID_ID}`	The bid ID from your response
`${AUCTION_IMP_ID}`	The impression ID
`${AUCTION_SEAT_ID}`	Your seat ID
`${AUCTION_CURRENCY}`	The auction currency (USD)

8. Privacy Signals

Oprello passes the following privacy signals in bid requests when available:

GDPR: regs.ext.gdpr (0 or 1) and user.ext.consent (IAB TCF v2 consent string).
CCPA: regs.ext.us_privacy (IAB US Privacy string, e.g. "1YNN").
GPP: regs.ext.gpp (GPP consent string) and regs.ext.gpp_sid (section IDs).
COPPA: regs.coppa (0 or 1). When COPPA is enabled, device IDs are stripped and lmt is set to 1.
ATT (iOS): device.ext.atts (0=not determined, 1=restricted, 2=denied, 3=authorized).
LMT: device.lmt (0 or 1) indicates if the user has limited ad tracking.

DSPs must comply with all applicable privacy regulations. Do not use device IDs for personalized advertising when consent has not been granted or when LMT is set.

9. Supply Chain (schain)

Oprello includes a source.ext.schain object in all bid requests per the IAB SupplyChain specification. The Oprello node is always present:

{
  "ver": "1.0",
  "complete": 1,
  "nodes": [
    {
      "asi": "oprello.com",
      "sid": "publisher-account-id",
      "hp": 1,
      "rid": "transaction-id",
      "name": "Oprello",
      "domain": "oprello.com"
    }
  ]
}

When Oprello receives traffic via mediation partners, their nodes are included earlier in the chain and complete reflects the upstream value.

10. SKAdNetwork (iOS Attribution)

To participate in Apple's SKAdNetwork attribution, include a skadn object in your bid response. The SDK handles impression tracking via SKAdNetwork.startImpression() on iOS 16.1+. AdAttributionKit support is in development. Currently, SKAdNetwork is used for attribution.

"skadn": {
  "version": "4.0",
  "network": "your-network-id.skadnetwork",
  "campaign": "42",
  "itunesitem": "123456789",
  "nonce": "unique-nonce-uuid",
  "signature": "base64-encoded-signature",
  "timestamp": "1700000000",
  "sourceidentifier": "1234",
  "fidelity": "1"
}

11. Reporting & Reconciliation

Oprello provides monthly invoices with impression-level breakdowns. For reporting reconciliation, discrepancy resolution, or to request detailed impression logs for a billing period, contact Oprello's billing team at billing@oprello.com. Discrepancies should be reported within 30 days of the invoice date per the DSP Integration Agreement.

12. Getting Started

To connect as a demand partner:

Contact us at partnerships@oprello.com to request access.
Provide your bid endpoint URL, supported ad formats, and supported platforms.
We will register your DSP and provide a bidder ID.
Implement the OpenRTB 2.5 bid request/response protocol as described above.
We will send test traffic to validate your integration before going live.