Clickthrough URLs

In order to dynamically route a commerce media creative to the correct product page after clicking on the creative, you can use the clickthrough URL template from the configuration service. This template is a handlebars template that can be used to generate a URL based on product information in the bid response.

Supported Creatives

Clickthroughs are available on all creative types, not just native ads. Banners and videos can encode metadata for the clickthrough URL to use in their ad markup.

Banners

For example, in order to make a commerce media enabled banner (a banner whose clickthrough URL redirects to the current ecommerce store and not the advertiser's website), you would add a <div> tag with data- attributes:

{rtb_click}
<img src="https://cdn.surfside.io/example.png">
{/rtb_click}
<div id="surf-product-info"          <!-- Required ID attribute -->
     data-name="Product Name"
     data-brandname="Brand Name"
     data-producttype="Product Type"
></div>

All fields are optional, but the more information you provide, the more likely the clickthrough URL will be able to route to the correct product page. The most common fields are data-producttype and data-brandname. These can route to a brand or product category page on the ecommerce store, but not an individual product. Including the data-name field will allow the clickthrough URL to route to a specific product page.

For example, if the clickthrough URL template is:

https://www.example.com/shop/{{slug product.productType}}/{{slug product.brandName}}/{{slug product.name}}

and the creative markup includes:

<div id="surf-product-info"
     data-brandname="Surfside Spices"
     data-producttype="Hot Sauces"
     data-name="Habanero Hellfire"
></div>

The clickthrough URL will be

https://www.example.com/shop/hot-sauces/surfside-spices/habanero-hellfire

(the slug helper converts spaces and other punctuation in a field into URL-safe characters and hyphens).

The BuildBanner helper will pull this product information out when constructing a banner from the adm:

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

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

const { element, product } = BuildBanner(response);
console.log(product);

Prints

{
     "brandName": "Surfside spices",
     "productType": "Hot Sauces",
     "name": "Habanero Hellfire"
}