Sponsored Product SDK – Developer Guide

The SDK lets GoWit marketplaces show sponsored product ads on any website without a server-side integration.

The SDK requests the product ads from the browser, renders them as product cards inside your container, and tracks impressions and clicks for each card.

1. Quick Start

To use the SDK, add the following script and configuration to your site:

UUID: Your marketplace's unique identifier. You can find this in your GoWit dashboard.
Hostname: The URL of your GoWit dashboard or API endpoint. Your GoWit team will provide your hostname during integration setup.

<script>
  window.__rma__conf = {
    base_url: "YOUR_HOSTNAME_HERE",
    id: "YOUR_UUID_HERE",
    // optional: session_id, search_term, category_path, consent, customer_id
  };
</script>
<script
  defer
  id="retail-ads-library"
  src="https://sdk.gowit.com/gowit.js"
></script>

The configuration is shared with the Sponsored Display SDK. If the SDK is already on your page, keep the existing configuration and only push the product ad objects described below.

2. Search and Category Pages

Product ads are matched to the page the shopper is viewing. Set these fields in window.__rma__conf before the SDK loads:

Field	Page	Description
`search_term`	Search page	The text the shopper searched for, e.g. `"headphones"`.
`category_path`	Category page	The category the shopper is browsing, e.g. `"Electronics > Audio > Headphones"`.

Leave both fields empty on pages that are neither a search page nor a category page, such as the home page.

Use an ad placement whose type matches the page: a search results placement on the search page and a category placement on the category page.

3. Pushing Product Ads

Ad Placement ID:

Ad Placement ID: The identifier for the ad placement where the product ads will appear. You can find your Ad Placement IDs in the "Ad Placements" tab on the GoWit dashboard. The placement's ad format must be Sponsored Product.

<div id="recommended-products"></div>

<script>
  window.__rma__ads = window.__rma__ads || [];
  window.__rma__ads.push({
    format: "sponsored-product",
    container: "#recommended-products",
    placement_id: YOUR_PLACEMENT_ID, // Use your Ad Placement ID here
    max_ads: 4,
    currency: "TRY",
    locale: "tr-TR",
    onRender: (cfg, response, el) => console.log("Product ads loaded"),
    onError: (cfg) => console.log("No product ad"),
  });
</script>

Ad objects support:

Field	Description
`format`	Must be `"sponsored-product"`.
`placement_id`	Identifier of the Sponsored Product placement created in your dashboard.
`container`	Required. CSS selector, DOM element, or function returning an array of elements. The cards are rendered into the first matching element.
`max_ads`	(optional) Maximum number of products to request.
`currency`	(optional) ISO 4217 currency code used to format prices, e.g. `"TRY"`, `"EUR"`.
`locale`	(optional) Locale used to format prices, e.g. `"tr-TR"`. Defaults to the browser's language.
`hide_price`	(optional) Set to `true` to render the cards without prices.
Callbacks	`onBeforeRender`, `onRender`, `onError`.

Call window.__rma__ads.push() once per ad object. Arrays or multiple arguments are not supported.

4. Rendered Product Cards

Each product ad is rendered as a card that links to the product detail page. A card shows:

Product image
Sponsored label
Brand
Product name
Rating
Price (unless hide_price is set)

Products without an image, brand, rating, or price are still rendered; the missing parts are omitted.

Styling

The cards are styled through CSS variables. Set them on your container to match your site's design:

#recommended-products {
  --gowit-sp-card-min-width: 180px;
  --gowit-sp-gap: 16px;
  --gowit-sp-card-radius: 4px;
  --gowit-sp-price-color: #c2410c;
}

Variable	Default
`--gowit-sp-card-min-width`	`160px`
`--gowit-sp-gap`	`12px`
`--gowit-sp-font-family`	`inherit`
`--gowit-sp-text-color`	`#222`
`--gowit-sp-card-background`	`#fff`
`--gowit-sp-card-border`	`1px solid #e5e5e5`
`--gowit-sp-card-radius`	`8px`
`--gowit-sp-image-background`	`#f7f7f7`
`--gowit-sp-label-font-size`	`10px`
`--gowit-sp-label-color`	`#555`
`--gowit-sp-label-background`	`rgba(255, 255, 255, 0.85)`
`--gowit-sp-body-padding`	`8px 10px 12px`
`--gowit-sp-brand-color`	`#555`
`--gowit-sp-name-font-size`	`13px`
`--gowit-sp-rating-color`	`#f5a623`
`--gowit-sp-price-font-size`	`15px`
`--gowit-sp-price-color`	`#111`

Ad blockers

Ad blockers hide elements whose id or class contains words such as sponsored, ad, or banner. Use a neutral name for your container, for example #recommended-products, so the cards stay visible.

5. Impression and Click Tracking

The SDK tracks the cards it renders automatically:

Impression: Sent once per ad when at least 10% of the card is visible in the viewport.
Click: Sent once per ad, whichever part of the card is clicked. Repeated clicks on the same ad on the same page are not sent again.

If your marketplace records impressions on ad delivery, set auto_impression: true in window.__rma__conf. The SDK then sends only click events from the browser.

Tracking your own product cards

If you render the product cards yourself, use the tracking functions on window.gowit with the ad_id of each ad:

// Track impression and click for a card element
const untrack = window.gowit.trackProductAd(cardElement, adId);

// Or send the events manually
window.gowit.sendImpressionEvent(adId);
window.gowit.sendClickEvent(adId);

Function	Description
`trackProductAd(element, adId)`	Sends the impression when the element becomes visible and the click when it is clicked. Returns a function that stops tracking.
`sendImpressionEvent(adId)`	Sends an impression event. Skipped if `auto_impression` is enabled or the impression was already sent.
`sendClickEvent(adId)`	Sends a click event. Skipped if the click for this ad was already sent on the page.

6. Callbacks

onBeforeRender(config, ads, container) before the cards are inserted
onRender(config, response, container) after the cards are rendered
onError(config) when no product ad is returned or the container cannot be found

7. Debugging

Add #gowit_sdk_debug to the URL to enable debug and info logs.

8. CORS Configuration

Our SDK endpoints are protected by Cross-Origin Resource Sharing (CORS). If you encounter a CORS error, typically because your site's origin isn't yet on our allow-list, please let us know which URL you're calling from. We'll add it so your requests succeed without further changes on your end.

9. FAQ

Q: Can I show product ads and banners on the same page?
A: Yes. Push one ad object per placement, each with its own format, placement_id, and container.

Q: Why are no cards rendered?
A: Check that the placement's ad format is Sponsored Product, that search_term or category_path is set on search and category pages, and that the container exists. Add #gowit_sdk_debug to the URL to see the reason in the console.

Q: Is a click on the "add to cart" button inside the card counted?
A: Only for cards you render yourself and track with trackProductAd, since any click on the tracked element counts. Each ad is still counted once per page.

1. Quick Start​

2. Search and Category Pages​

3. Pushing Product Ads​

4. Rendered Product Cards​

Styling​

5. Impression and Click Tracking​

Tracking your own product cards​

6. Callbacks​

7. Debugging​

8. CORS Configuration​

9. FAQ​