Sponsored Display SDK – Developer Guide

The SDK allows GoWit marketplaces to display banner advertisements on any website.

Define a global configuration, load the script, and push ad objects describing where and how to render each ad.

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. If you used self-service onboarding, this will be cloud.gowit.com.

<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>

2. Global Configuration (`rmaconf`)

The SDK reads window.__rma__conf on load. At minimum provide base_url and id.

Optional fields include session_id, customer_id, search_term, category_path, and consent. If session_id is omitted, a new one is created automatically. These fields are validated inside the init function.

3. Pushing Ads

Ad Placement ID:

To properly configure the SDK for displaying ads, you'll need:

Ad Placement ID: The identifier for the specific ad placement where the ads will appear on your website. You can find your Ad Placement IDs in the "Ad Placements" tab on the GoWit dashboard. Use this value for the placement_id field in your ad configuration.

<script>
  window.__rma__ads = window.__rma__ads || [];
  window.__rma__ads.push({
    format: "sponsored-banner",
    placement_id: YOUR_PLACEMENT_ID, // Use your Ad Placement ID here
    container: ".banner-container", // omit for auto-placement
    page_number: 1,
    onBeforeRender: (cfg, ad, el) => {
      /* optional hook */
    },
    onRender: (cfg, ad, el) => console.log("Ad Loaded"),
    onError: (cfg) => console.log("Ad Failed"),
  });
</script>

window.__rma__ads must contain one ad configuration per .push() call.
Arrays or multiple arguments are not supported; the overwritten push handler only expects a single object.

Ad objects require:

Field	Description
`format`	Only `"sponsored-banner"` is implemented.
`placement_id`	Identifier of the placement created in your dashboard.
`container`	(optional) CSS selector, DOM element, function, or array of these.
`page_number`	(optional) Number for paged lists.
Callbacks	`onBeforeRender`, `onRender`, `onError`.

If container is omitted, the ad is inserted at the top of the page via the auto‑placement banner.

4. Containers & Retry Logic

getContainers resolves each provided container. CSS selectors, DOM nodes, or arrays are accepted; invalid values trigger onError and a log entry.

When no container is found the SDK retries twice before giving up, logging each attempt and calling onError if still missing.

5. Callbacks

During rendering, the SDK invokes optional callbacks:

onBeforeRender(config, ad, container) before HTML is inserted
onRender(config, ad, container) after rendering completes
onError(config) when an ad cannot be loaded or rendered.

Other callback names (e.g., onPreRender) are ignored.

6. Debugging and Pixel Sync

Add #gowit_sdk_debug to the URL to enable debug and info logs. The helper isDebugMode checks this hash.

If the optional consent flag is set and the hostname matches a known marketplace, a TradeDesk pixel is injected for audience sync.

7. Example: Dynamic Initialization

The following script loads the SDK lazily, creates a container if needed, and requests two banners (one directly in a container, one in multiple carousel slots):

<script>
  (function () {
    function getCookieValue(name) {
      var match = document.cookie.match(
        new RegExp("(^|;\s*)" + name + "\s*=\s*([^;]*)")
      );
      return match ? decodeURIComponent(match[2]) : null;
    }

    function parseConsent() {
      try {
        var consentData = JSON.parse(
          getCookieValue("cookiespool_consent") || "{}"
        );
        return consentData.choices && consentData.choices.marketing ? 1 : 0;
      } catch (e) {
        return 0;
      }
    }

    window.__rma__conf = {
      base_url: "YOUR_HOSTNAME_HERE",
      id: "YOUR_UUID_HERE",
      session_id: getCookieValue("device_id"),
      search_term: new URLSearchParams(location.search).get("text"),
      category_path:
        Array.from(document.querySelectorAll(".breadcrumb > li:not(.active)"))
          .map((x) => x.innerText.trim())
          .join(" > ") || null,
      consent: parseConsent(),
    };

    function createContainer() {
      var cont = document.querySelector(".gowit-product-component");
      if (cont) return cont;
      cont = document.createElement("div");
      cont.className = "gowit-product-component";
      document.body.prepend(cont);
      return cont;
    }

    function load() {
      var container = createContainer();

      window.__rma__ads = window.__rma__ads || [];
      window.__rma__ads.push({
        format: "sponsored-banner",
        container,
        placement_id: document.documentElement.clientWidth < 751 ? 19 : 16,
        onBeforeRender: (cfg, ad, el) => {
          el.classList.add("gowit-ad-banner");
        },
      });

      window.__rma__ads.push({
        format: "sponsored-banner",
        container: () => [
          document.querySelectorAll(
            ".gowit-product-component .owl-item:not(.cloned)"
          )[1],
          document.querySelectorAll(
            ".gowit-product-component .owl-item:not(.cloned)"
          )[2],
          document.querySelectorAll(
            ".gowit-product-component .owl-item:not(.cloned)"
          )[3],
        ],
        placement_id: document.documentElement.clientWidth < 751 ? 17 : 14,
      });

      var s = document.createElement("script");
      s.src = "https://sdk.gowit.com/gowit.js";
      s.defer = true;
      document.head.appendChild(s);
    }

    if ("requestIdleCallback" in window) {
      requestIdleCallback(load);
    } else {
      setTimeout(load, 200);
    }
  })();
</script>

8. Where to Place the Script

Once you've customized the SDK configuration and ad request scripts, add them to the bottom of the <body> tag on any page where you want to display banner ads. This ensures that your ad containers and other page elements are loaded before the SDK runs, preventing rendering issues.

Example:

<body>
  <!-- Your website content here -->

  <!-- Place the SDK and ad scripts just before the closing body tag -->
  <script>
    // ...your __rma__conf and __rma__ads code here...
  </script>
  <script
    defer
    id="retail-ads-library"
    src="https://sdk.gowit.com/gowit.js"
  ></script>
</body>

9. CORS Configuration

Our SDK endpoints are protected by Cross-Origin Resource Sharing (CORS). By default, we automatically allow requests from the origin that your application is running on. 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 promptly add it so your requests succeed without further changes on your end.

10. FAQ

Q: Can I push multiple ad objects at once?
A: No. Call window.__rma__ads.push() separately for each object.
The overridden push function only handles one configuration at a time.

Q: What happens if no container is provided?
A: A banner is automatically inserted at the top of the page.

Q: How do I enable verbose logging?
A: Add #gowit_sdk_debug to the URL.

Use this guide to configure the SDK with your marketplace ID and ad placements, load the script once per page, and push ad objects for each location where you want a banner to appear. The SDK resolves containers, retries if necessary, and calls your callbacks when rendering completes.

1. Quick Start​

2. Global Configuration (__rma__conf)​

3. Pushing Ads​

4. Containers & Retry Logic​

5. Callbacks​

6. Debugging and Pixel Sync​

7. Example: Dynamic Initialization​

8. Where to Place the Script​

9. CORS Configuration​

10. FAQ​