Simple Example

Headless Ads is surfside's frontend services for sending bid requests and rendering bid responses. You can tailor the advertising experience to your specific needs.

Getting Started

Add the relevant packages to your project. In yarn:

yarn add @surfside/ads-core

or npm:

npm install @surfside/ads-core

In order to send a bid request, initialize surfside core and send a standard OpenRTB 2.6 request to the bidder:

const { bidder } = initSurfsideCore();

const request = {
    id: '12345',
    imp: [{
        id: 'my-banner-1',
        banner: {
            w: 2, /* Using aspect ratios instead of raw pixels */
            h: 1
        }
    }]
};

let response;
try {
    response = await bidder.requestBids(request);
} catch(e) {
    console.error(e); /* Bidder will throw 204 if there are no bids available */
}

The bid response is a standard OpenRTB 2.6 bid response:

const ad = document.createElement('div');
ad.innerHTML = response.seatBid[0].bid[0].adm; /* adm is the HTML for the banner */

Helpers

If your use cases are simple enough that they don't require every field in OpenRTB 2.6, you can use some of the request helpers:

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

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

Which is equivalent request to the first example. Responses also have their own helpers to make sure win pixels are attached:

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

/* ... */

const { element } = BuildBanner(response);

/* Element is null if the response was incorrectly formed */
if (element !== null) {
    document.body.appendChild(element);
}

More helpers are documented under their pages. Go to the next page for information on the Request Builder.