Publisher Integration Guide

Overview

One <script> tag with data-* attributes handles: lazy-loading video.js + IMA + Prebid (≈ 250 KB), running the auction, stitching hb_pb / hb_bidder / hb_uuid / hb_size / hb_format / hb_adid into GAM's cust_params, and rendering the cached creative via IMA.

Engine hosted at versioned, immutable jsDelivr URLs. Pin to a tag (e.g. @v2.5.1) — the bytes cannot silently change.

How it works

Prerequisites

• Google Ad Manager account with video inventory; a GAM Master Ad Tag URL ending in correlator=.
• Limelight Digital publisher ID + ad unit ID.
• Domain allowlisted by Limelight (1–3 business days). Without this, every auction returns no-bid.
• HTTPS publisher pages; content video URL (.mp4 / .m3u8) on your CDN.

Quick start

1. Generate the tag

   Open the Tag Generator, fill in version, GAM tag, Limelight pub/ad-unit IDs, content URL → copy the <script>.

2. Set up GAM

   Create the key-values, the VAST wrapper creative, and one line item per $0.10 bucket (one-time setup — see GAM setup).

3. Embed

   Paste the snippet where the player should render. The engine auto-creates a mount <div>.

4. Verify

   Open with ?debug=true — see testing checklist.

5. Monitor

   GAM Reports → filter by hb_bidder=limelightDigital for impressions / eCPM / fill.

Embed code reference

The v2 tag shape uses data-bidders — a JSON array of every SSP that should bid in this auction. The Prebid bundle at data-prebid-url must include adapters for every bidder listed.

<script src="https://cdn.jsdelivr.net/gh/shashwatsilverpush/bidding-player@v2.5.1/engine/player.js"
        id="adtech-player-core"
        data-bidders='[
          {"bidder":"limelightDigital","params":{"host":"ads-jbi003.rtba.bidsxchange.com","publisherId":"649658371","adUnitId":972556929,"adUnitType":"video"}},
          {"bidder":"appnexus","params":{"placementId":12345678}}
        ]'
        data-tag="https://pubads.g.doubleclick.net/gampad/ads?iu=/…&sz=640x480&output=vast&correlator="
        data-video="https://your-cdn.example.com/content.mp4"
        data-prebid-url="https://cdn.jsdelivr.net/gh/shashwatsilverpush/bidding-player@v2.5.1/prebid/prebid-limelight-appnexus.js"
        data-timeout="1200"  data-bias="0.10"
        data-autoplay="true"  data-muted="true"  data-fluid="true"
        async></script>

Attribute reference

Placement & sticky

Instream (default) plays the ad as pre-roll against your data-video content. Outstream (data-placement="outstream") needs no content video — drop it into a text article and the slot stays collapsed until it scrolls ≥50% into view, autoplays muted, then collapses when the ad finishes.

For instream, add data-sticky="true" to keep the player visible while the reader scrolls: it floats to the bottom-right corner (still playing, × to dismiss) and snaps back inline on scroll-up, with the original layout space preserved. This raises viewability and completed-view rates — off by default, opt in per placement.

Adding a new SSP / Prebid bundle

The prebid/ directory holds pre-built Prebid.js bundles. Each data-prebid-url points at one of these. To add a new bundle (e.g. when onboarding a publisher that uses a different SSP), trigger the "Build Prebid bundle" workflow in the Actions tab — supply the comma-separated module list and a filename, the workflow runs gulp build and commits the result. Full instructions in prebid/README.md.

GAM setup

One-time setup: key-values, a VAST wrapper creative, and price-bucket line items.

1. Custom key-values

GAM → Inventory → Key-values → New key-value:

2. VAST wrapper creative

GAM → Delivery → Creatives → New → Video → VAST 3.0 ad tag. Paste:

https://prebid.adnxs.com/pbc/v1/cache?uuid=%%PATTERN:hb_uuid%%

Duration: 0:00 (wrapper resolves real duration). Substitute your own cache URL if not using the AppNexus public cache.

3. Price-bucket line items

One line item per $0.10 bucket (200 total for $0–$20). Use Prebid's Line Item Generator to bulk-create via CSV.

4. House fallback + order

Add a low-priority line item targeting hb_pb=0.00 with your house creative or AdSense passback. Wrap all line items in one Order (e.g. "Prebid Header Bidding") for one-click pause/activate.

Limelight onboarding

1. Apply for a Limelight account via your CSM.
2. Receive credentials: publisherId → data-pub-id; adUnitId → data-adunit-id; host → data-host.
3. Submit publisher domain(s) for allowlist approval (1–3 business days).
4. Verify bidding using the testing checklist.

Consent management

Defaults are tuned for non-EU traffic. EU and US-state-privacy publishers override.

EU — enable TCF v2

Place a registered CMP (OneTrust, Sourcepoint, Quantcast, Didomi…). Add this script before the engine tag:

<script>
window.pbjs = window.pbjs || { que: [] };
pbjs.que.push(function() {
  pbjs.setConfig({
    consentManagement: {
      gdpr: { cmpApi: 'iab', timeout: 8000, defaultGdprScope: true }
    }
  });
});
</script>

US state privacy — enable GPP

pbjs.setConfig({ consentManagement: { gpp: { cmpApi: 'iab', timeout: 3000 } } });

Testing & verification

Append ?debug=true to your URL.

Console (filter for STEP)

• STEP 1 Auction Initialized · Target: limelightDigital · Timeout: 1200ms
• STEP 1.5 Requesting from Limelight. Player size: WxH
• WINNER <bidder> · Raw CPM: $X.XX, or NO MARKET DEMAND
• STEP 6 Dispatching VAST Request

Network

Visual

• Pre-roll plays before content; Video.js controls (play / pause / mute / volume / progress / fullscreen) respond.

Troubleshooting

FAQ