The Configuration Service

The Surfside platform allows publishers to configure their advertising experience through the Configuration Service. This service allows you to enable/disable features, set product card templates with handlebars, and design clickthrough URL templates. These features are not required for headless ads, but may be used if you wish.

Initializing

The configuration service is returned by initSurfsideCore, similar to the bidder:

const { config } = initSurfsideCore();

Your particular configuration is found using a combination of your account and site IDs:

const { config } = initSurfsideCore();
const configuration = await config.getConfiguration(accountId, siteId);

Templates

All handlebars templates from the configuration are precompiled and ready to use in your application:

const { config } = initSurfsideCore();
const configuration = await config.getConfiguration(accountId, siteId);

/* In this example, the product card template is:

    <h1>{{product.title}}</h1>

*/
const productCard = document.createElement('div');

/* configuration.productCardTemplate is a precompiled handlebars template (i.e: a function that returns some HTML) */
productCard.innerHTML = configuration.productCardTemplate({
    product: {
        title: 'My Product'
    },
    window: window,    /* The current window location information. */
                       /* Useful for routing clickthrough URLS */
    publisher: config,
    catalog: {}        /* Used for another feature */
});

The resulting card will be:

<div>
    <h1>My Product</h1>
</div>

All templates take an IProductContext object with the following parameters:

• product: Partial<IProductInformation> : The product data to be displayed in the card. This is a partial object, so all fields in it are optional.
  • image: string | null: The URL of the product image.
  • price: string | null: The price of the product. This is a string because it can contain currency symbols such as $.
  • salePrice: string | null: The sale price of the product (as in a the price of the object after a discount has been applied) This is a string because it can contain currency symbols such as $.
  • name: string | null: The name of the product.
  • brandName: string | null: The brand name of the product, i.e: the name of the advertiser.
  • details: string | null: A short description of the product.
  • cta: string | null: The call to action text for a product card. i.e "Add to Cart" or "Click Here"
  • clickthroughUrl: string | null: The URL to navigate to when the ad is clicked. This is a hardcoded URL and not a template, so it is often used to navigate to a product page on a different website, unless the ad showing on the page is part of a direct deal.
  • winUrl: string | null: The URL of a to call when the product is displayed

The following templates are available in the configuration:

Template	Description
productCardTemplate	The template for a product card. This is used to display product information in a native ad.
clickthroughUrlTemplate	The template for a clickthrough URL. This is used to navigate to a product page when a product card is clicked.

Additionally, these templates are styled using SASS-compiled stylesheets:

Stylesheet	Description
productCardStylesheet	The styles for a product card.
carouselStylesheet	The styles for a carousel.

Finally, a set of Javascript callbacks can be written to define interactions with the product card, but these are not required for headless ads. They are used primarily for the default Surfside Ads implementation. This field is called javascriptCallbacks and are compiled into UMD format.

Settings

Configuration objects have a settings field which contains feature flags and some values related to those features. For example, config.settings.reauctionEnabled controls whether or not ads should request a new bid after a certain amount of time. config.settings.reauctionIntervalMs is the time in milliseconds before a reauction should occur. The following settings are available in this table:

Setting	Type	Description
commerceMediaEnabled	Boolean (true/false)	Whether or not ads should use contextual metadata to build their clickthrough URLs
ipTargetingEnabled	Boolean	Whether or not ads should use the Surfside Geo/IP Service to retrieve an IP address and send that IP address to the Surfside bidder
geoTargetingEnabled	Boolean	Whether or not ads should use the Surfside Geo/IP Service to retrieve geolocation information and send that information to the Surfside bidder
reauctionEnabled	Boolean	Whether or not ads should request a new bid after a certain amount of time
reauctionIntervalMs	Number	The time, in milliseconds, before a reauction should occur
productFeedEnabled	Boolean	Whether or not product cards should build their product data from a product ID passed on the native bid response, or just use the raw asset fields from the bid response itself