Ad Preview & Debug Mode

Ad Preview Mode lets advertisers and campaign managers inspect a live campaign on a real publisher page before launch or after changes. A client paying for a campaign can share a single URL — with the right query parameters appended — and anyone opening that link will see the exact creative that will run in production, no special tools or access required.

❗️

Query parameters are the only supported mechanism for ad preview.

Do not implement preview logic through cookies, session storage, JavaScript flags, or server-side feature switches. Query parameters ensure the preview link is self-contained, shareable, and works correctly across devices, browsers, and CDN layers.

In backend (SSR) integrations, the Bidder request originates from the server — not the browser — so the DL API SDK cannot forward debug parameters to the Bidder the way it does in client-side integrations. Instead, Ring DAS supports a set of query string parameters that your backend reads from the page URL and forwards directly to the Bidder. This lets you preview specific creatives, override targeting context, and trace the full ad event pipeline — all without running a live campaign.

Applies to all backend (SSR) formats: Sponsored Single Tile, Sponsored Product Slider, Brand Store, Branded Products. The mechanism is identical across all formats — only the adbeta slot name differs per format.

sequenceDiagram
    participant QA as QA / Ad Ops
    participant FE as Website Frontend
    participant BE as Website Backend
    participant Bidder as Ring DAS Bidder

    QA->>FE: 1. Open page with debug params
    Note over QA,FE: ?adbeta=l1234567!slot.sponsored&test_area=SEARCH
    FE->>BE: 2. Forward query params + headers
    Note over BE: 3. Extract: adbeta, test_area, test_site,<br/>test_kwrd, test_tid from query string<br/>x-adp-event-track-id from header
    BE->>Bidder: 4. Bidder request with ext.adbeta,<br/>overridden site/area,<br/>X-ADP-EVENT-TRACK-ID header
    Bidder-->>BE: 5. Preview creative / debug response
    BE-->>FE: 6. Rendered preview tile
    Note over QA: Preview creative visible<br/>in production layout

Query String Parameters

Add these parameters to the page URL. Your backend reads them and forwards them to the bidder request.

Backend Implementation

Extract the debug parameters from the incoming page URL and apply them to the bidder request:

function buildBidderRequest(pageContext, debugParams = {}) {
    // Base site/area/network from page context
    let siteId    = pageContext.siteId;     // e.g., 'DEMO_PAGE'
    let area      = pageContext.area;       // e.g., 'SEARCH'
    let networkId = pageContext.networkId;  // e.g., '7012768'

    // Override with debug params if present in page URL
    if (debugParams.test_site) siteId    = debugParams.test_site;
    if (debugParams.test_area) area      = debugParams.test_area;
    if (debugParams.test_tid)  networkId = debugParams.test_tid;

    const requestBody = {
        id: crypto.randomUUID(),
        imp: [ /* ... standard imp entries ... */ ],
        site: {
            id: siteId,
            ext: {
                area: area,
                // Inject test keywords if present
                ...(debugParams.test_kwrd && { kwrd: debugParams.test_kwrd }),
            }
        },
        user: { /* ... standard user params ... */ },
        ext: {
            network: networkId,
            /* ... standard ext params ... */
            // Force specific creative for preview
            ...(debugParams.adbeta && { adbeta: debugParams.adbeta }),
        },
        regs: { /* ... standard regs ... */ },
        tmax: 1000
    };

    return requestBody;
}

Extracting debug params from the page URL:

// Read from incoming request (e.g., Express.js)
const debugParams = {
    adbeta:    req.query.adbeta    || null,
    test_area: req.query.test_area || null,
    test_site: req.query.test_site || null,
    test_kwrd: req.query.test_kwrd || null,
    test_tid:  req.query.test_tid  || null,
};

const requestBody = buildBidderRequest(pageContext, debugParams);

Debug Tracking: x-adp-event-track-id

The X-ADP-EVENT-TRACK-ID HTTP header enables end-to-end tracking of the entire ad event pipeline — from the initial bid request, through impression and click, all the way to conversion. Pass a unique value per debug session to trace all related events in Ring DAS systems.

async function fetchAd(requestBody, incomingHeaders = {}) {
    const encodedData = encodeURIComponent(JSON.stringify(requestBody));
    const bidderHeaders = {};

    // Forward tracking header if present in the incoming page request
    const trackId = incomingHeaders['x-adp-event-track-id'];
    if (trackId) {
        bidderHeaders['X-ADP-EVENT-TRACK-ID'] = trackId;
    }

    const response = await fetch(
        `${BIDDER_URL}?data=${encodedData}`,
        { headers: bidderHeaders }
    );

    if (response.status === 204) return null;
    return response.json();
}

Usage: Set a unique, descriptive value when debugging a specific request flow:

x-adp-event-track-id: debug-search-tile-2025-02-16-ticket-1234

Use this ID to trace all related events across Ring DAS systems.

Injecting Bidder URL into HTML Response

When the x-adp-event-track-id header is present, inject the full Bidder request URL as an HTML comment into the response body. This allows anyone investigating a missing ad to inspect the exact request sent to the Bidder directly from the page source — without needing access to server logs.

// When x-adp-event-track-id is present, inject full Bidder URL into HTML response
// (visible in browser View Source — use during debugging only)
if (incomingHeaders['x-adp-event-track-id']) {
    const bidderUrl = `${BIDDER_URL}?data=${encodedData}`;
    res.write(`<!-- Ring DAS Bidder request: ${bidderUrl} -->\n`);
}

Preview URL Examples

Preview a specific creative:

https://your-shop.com/search?q=smartphones&adbeta=l1234567!slot.product-tile

Override area and site for testing:

https://your-shop.com/search?q=smartphones&test_site=DEMO_PAGE&test_area=SEARCH

Combine creative preview with keyword testing:

https://your-shop.com/search?q=smartphones&adbeta=l1234567!slot.product-tile&test_kwrd=smartphone+samsung

Override network for testing against a different network:

https://your-shop.com/search?q=smartphones&test_tid=7012768

Full debug session with tracking:

curl -H "x-adp-event-track-id: debug-session-42" \
  "https://your-shop.com/search?q=smartphones&adbeta=l1234567!slot.product-tile"

Related

• Sponsored Single Tile - Backend SSR integration for search and category pages
• Sponsored Product Slider - Backend SSR integration for product sliders
• Brand Store (Web) - Backend SSR integration for product detail pages
• Branded Products - Backend SSR integration for homepage banners