Skip to main content

Ad Serving

Ad serving is the process of selecting, delivering, and tracking digital advertisements on your site or app. Integrating GoWit’s ad serving into your platform allows you to monetize your traffic by displaying relevant ads in real time. The ad server considers context (what the user is viewing, where the ad will go) and targeting criteria (who the user is, location, etc.) to decide which ad to show. It ensures that ads meet the placement’s requirements and uses performance metrics to optimize delivery.

Understanding Ad Formats and Placements​

  • Where they appear: On product detail pages, category pages, and search results.
  • Visual style: Look like organic product cards—image, price, brand, and CTA.
  • Usage: Inserted into existing product grids or carousels.

Send contextual info like current category or search query to get ads aligned with user intent.

  • Where they appear: Static banner slots (e.g. homepage hero, mid-content rectangles).
  • Visual style: Image-based banners tailored to the slot.
  • Usage: Load using GoWit Display SDK or embed via script with placement ID.

The SDK handles visibility detection and impression tracking.

  • Where they appear: In video feeds or as content units.
  • Visual style: Video + thumbnail + CTA.
  • Usage: Load inside your player or use GoWit’s wrapper for autoplay, mute-on-scroll.

Ensure impressions fire on video start and route clicks through provided tracking URLs.

Building a Meaningful Ad Request​

The quality of ads returned depends on the depth of context provided. Here’s what matters:

1. Organic Product Context​

Provide details about the organic products shown on the page:

  • id (required)
  • category (optional but recommended)
  • categories (optional — use when a product belongs to multiple categories)
  • category_id_structures (optional — category ID paths corresponding to categories)

Helps match ads to similar or complementary products—especially useful on category/search pages. When a product belongs to multiple categories, providing the categories array ensures all relevant categories are considered for ad matching.

2. Customer Context​

If available, include demographic or behavioral signals:

  • customer_id
  • gender, age, city, device_type
  • environment_type
  • country, language, device, platform, os, browser, consent

Enables demographic filtering and relevance scoring. For example, surfacing ads meant for a particular gender or city.

Visitor fields​

The customer object of the ad request (POST /ads, /v2/ads and the SDK endpoint /v2/sdk/ads) accepts the following optional visitor fields in addition to id, customer_id, gender, age, city, device_type, ip, user_agent and segments:

FieldTypeAccepted valuesDescription
countrystringISO 3166-1 alpha-2, uppercase (e.g. TR, DE, SA)The visitor's country. Used for campaign country targeting (see below).
languagestringISO 639-1, lowercase (e.g. tr, en, de)The visitor's language.
devicestringMOBILE, TABLET, DESKTOP, TV, OTHERThe visitor's device category.
platformstringWEB, APPWhether the visitor is on your website or your app. Recommended for new integrations instead of environment_type.
osstringANDROID, IOS, WINDOWS, MACOS, LINUX, OTHERThe visitor's operating system.
browserstringCHROME, SAFARI, FIREFOX, EDGE, OTHERThe visitor's browser.
consentbooleantrue, falsetrue if the visitor has consented to personalized ads. Defaults to true when not sent; non-boolean values are treated as true.
environment_typestringe.g. App, WebSupported for existing integrations. If platform is not sent, platform is derived from environment_type.
  • All fields are optional, and a request is never rejected because of them. A value with the wrong type, an unknown value or a malformed value is ignored as if the field was not sent.
  • country normalization: leading and trailing spaces are trimmed and letters are uppercased (e.g. " tr " becomes TR). No other correction is applied: values such as TUR or UK are not converted and count as invalid.
  • Country targeting: a campaign restricted to specific countries is only shown when the request's country is in the campaign's country list. If country is missing, empty or invalid, such campaigns are not shown. Campaigns without a country restriction are served as before.
  • platform and environment_type: if platform is not sent (or is invalid), it is derived from environment_type: App becomes APP and Web becomes WEB (case- and whitespace-insensitive); any other value leaves platform empty.
  • device_type is unchanged and can still be sent alongside device.

Note: Video ad (/video-ads) and in-store ad (/instore-ads) requests do not carry country, so campaigns with country targeting are never shown on these paths. Other campaigns are served as before.

3. Placement Context​

Each ad slot must use a valid placement_id:

  • Tells the server what kind of ad fits (size, format)
  • Connects the request to configured inventory

Also include the marketplace_id if your site spans multiple markets. It ensures region-specific ads are served.

4. Session and Location Info​

A stable session_id is vital for attribution:

  • Tracks which session saw which ad, for reporting

Include location_id or region_id:

  • Allows filtering of ads by store region, city, or market

Especially important for campaigns tied to physical locations.

5. Optional Controls​

Use these to fine-tune ad delivery:

  • max_ads: Limit the number of ads returned for a placement
  • filters: Exclude certain brands, products, or categories to avoid repetition

Useful for avoiding conflicts with current page content or enforcing business rules.

Behind the Scenes: What the Ad Server Does​

When an ad request is received, the server:

  1. Evaluates available inventory based on placement_id
  2. Applies targeting filters based on customer/location data
  3. Scores eligible ads based on context and historical performance
  4. Returns the most relevant creative(s) for that placement

Each returned ad includes everything you need to display and track it properly.

Rendering and Tracking​

Always render the creative returned in the ad response. Each ad includes an ad_id for click and impression tracking. Ensure impressions fire once the creative is visible (handled automatically when using the SDK).