Banners

To request a banner with headless ads, you can use the request builder and some pre-defined banner request types.

Simple Banners

To handle the simplest use cases, banners can be requested with the SimpleBannerRequest class. Provide the width and height of the banner, and then use the BuildBanner function to get an HTML element back:

import { initSurfsideCore, SimpleBannerRequest, BuildBanner } from '@surfside/ads-core';

const { bidder } = initSurfsideCore();

try {
    const response = await bidder.requestBids(
        new SimpleBannerRequest('my-banner-1', 2, 1)
    );

    const { element } = BuildBanner(response);
    document.body.appendChild(element);
} catch(e) {
    console.error("Failed to get bids!") // Bidder throws an error if no bids are returned
}

Other banners

For more complicated or details banners, you can use the RequestBuilder:

import { initSurfsideCore, RequestBuilder, BuildBanner } from '@surfside/ads-core';

const { bidder } = initSurfsideCore();

try {
    const response = await bidder.requestBids(
        (new RequestBuilder())
            .withSurfContext({ /* Surfside client specific information */
                accountId: '00000',
                siteId: 'iddqd',
                locationId: 'ecf0f1',
                zoneId: '6502'
            })
            .withBanner(2, 1, {
                mimes: ["image/jpeg", "image/png"], /* OpenRTB 2.6 Banner object fields */
                pos: 1
            })
            .build()
    );

    const { element } = BuildBanner(response);
    document.body.appendChild(element);
} catch(e) {
    console.error("Failed to get bids!") // Bidder throws an error if no bids are returned
}

The request builder allows you to add any OpenRTB 2.6 Banner field onto your request, such as MIME types or blocked attribute lists. Additionally, it allows you to add your Surfside context (account ID, site ID, etc) for site-specific targeting.

Retail Media

If your site has a publisher configurations et up to render retail media banners, you can provide the configuration service to BuildBanner to render clickthrough URLs when available:

import { initSurfsideCore, RequestBuilder, BuildBanner } from '@surfside/ads-core';

const { bidder, configuration } = initSurfsideCore();

try {
    const response = await bidder.requestBids(
        (new RequestBuilder())
            .withSurfContext({ /* Surfside client specific information */
                accountId: '00000',
                siteId: 'iddqd',
                locationId: 'ecf0f1',
                zoneId: '6502'
            })
            .withBanner(2, 1, {
                mimes: ["image/jpeg", "image/png"], /* OpenRTB 2.6 Banner object fields */
                pos: 1
            })
            .build()
    );

    /* Use account and Site ID to get the publisher configuration */
    const { element } = BuildBanner(
        response,
        await configuration.getConfiguration('00000', 'iddqd')
    );
    document.body.appendChild(element);
} catch(e) {
    console.error("Failed to get bids!") // Bidder throws an error if no bids are returned
}

If the banner contains retail media information, BuildBanner will automatically render the clickthrough URL where appropriate. For more information, see clickthroughs.