Skip to main content

Tracking Event Schema

Purpose​

Tracking events are crucial for measuring campaign performance and correctly attributing conversions to ad interactions. By logging impressions (ad views), clicks, and sales events, the GoWit platform can tie user actions back to the ads that influenced them.

This enables accurate calculation of metrics like click-through rate (CTR) and return on ad spend (ROAS), while GoWit’s attribution engine automatically determines which ads get credit for a purchase – so you simply send the events and the platform “handles the rest” on the backend.

General Implementation Notes​

  • Required identifiers:
    Every tracking event must include your GoWit marketplace_id and a persistent session_id for the user’s session.
    The session_id should remain consistent across all ad requests and events for that user, so that impressions, clicks, and conversions can be linked together for attribution.

  • Ad identifiers:
    Include the ad’s unique ID with each event that relates to a specific ad.
    Use the ad_id (for a single ad) or an array of ad_ids (if the event covers multiple ads shown at once) to identify which ad(s) the event pertains to.

  • Optional user context:
    You may include a customer_id (if available) to represent a logged-in user’s unique ID.
    This is not required, but it enables cross-session and cross-device attribution by tying events to the same user across different sessions (e.g., matching a click on web to a purchase in the app).

  • Optional location context:
    If your integration supports multiple fulfillment locations or stores, you can provide a location_id in events to indicate the user’s current store/fulfillment context.
    This should match the location identifiers used in your product feed, and is only needed if location-specific stock or analytics are relevant.
    (If you do not have multi-location inventory, you can ignore this field.)

Event Types and Schemas​

Below are the main tracking event types supported, with their trigger conditions and data schemas. Each event payload includes the fields listed (in addition to the common fields noted above):

Impression​

The Impression event is recorded whenever an ad is displayed (rendered in view) to the user.
This event is required in a standard integration – it marks that an ad was shown for attribution and analytics purposes.
(If your marketplace is using GoWit’s auto-impression feature, the platform will automatically log impressions server-side, so you do not send them manually – see Auto-Impression note below.)

Fields:​

  • session_id (string, required):
    The session identifier for the user viewing the ad (must be the same ID used in the ad request and maintained across the user’s journey).

  • ad_id or ad_ids (string or string[], required):
    The unique identifier of the ad that was shown.
    If multiple ads are rendered at once (e.g. two sponsored products in one page view), you can send an array of IDs in one impression event. Otherwise, provide the single ad_id for the ad displayed.

  • location_id (string, optional):
    The store or location code where the ad was shown, if applicable.
    Include this only if you track ads at specific physical locations or fulfillment centers (matches the location_id used in your product data).

Auto-Impression​

If auto_impression = true is enabled for your integration, GoWit will automatically record impression events on your behalf when an ad is delivered.
In this case, do not send duplicate impression events from your side.

The ad response from GoWit will already trigger an internal impression log using the provided session and ad IDs.
You will still be responsible for implementing Click and Sale events as described below.

Viewable Impression (Optional)​

A Viewable Impression event is an optional tracking event used to measure ad viewability – i.e., whether the ad actually became visible to the user for a sufficient amount of time (as opposed to just being delivered but possibly never seen).

This is not required for basic attribution or billing – it serves only as a diagnostic metric to analyze the quality of ad placements (for example, to calculate what percentage of impressions were truly viewable).

Implementing viewable impressions typically requires a client-side script or GoWit’s JavaScript SDK to detect when an ad meets the viewability criteria (for example, at least 50% of the ad’s pixels in view for 1 second).

Fields:​

  • session_id (string, required):
    The same session identifier for the user, to tie the viewable impression to the original impression event.

  • ad_id (string, required):
    The unique ad ID for the ad that became viewable. This should be the same ad_id that was used when logging the impression for that ad.

  • location_id (string, optional):
    Location context (store/fulfillment location) if relevant, as with the impression event. Optional and used only if applicable.

Notes:​

  • Viewable impressions are recorded separately and do not replace or count as regular impressions for attribution.
  • They have no impact on conversion attribution or billing – even if you track viewability, the attribution logic still relies on the standard impression and click events.
  • Because this event must be triggered from the client side (browser), factors like ad blockers or network interruptions might prevent some viewable impressions from being sent, which is acceptable since they are supplementary metrics.
  • If implementing this, ensure your front-end captures the event (using an IntersectionObserver or GoWit’s viewability SDK) and calls the tracking endpoint with event_type = "viewable_impression", using the same session_id and ad_id values as the original impression.

Click​

The Click event is recorded whenever a user clicks on a sponsored ad.
This event is required for all integrations, as it signals direct engagement with the ad and kicks off the conversion attribution window (essential for measuring click-through rate and post-click conversions).

Click events should be sent in real-time (immediately when the click occurs) so that GoWit can log the interaction and begin tracking any resulting conversions from that point.

Fields:​

  • session_id (string, required):
    The session identifier for the user who clicked the ad (same ID used in the impression and ad request).

  • ad_id (string, required):
    The unique identifier of the ad that was clicked. Your ad delivery response will include an ad_id for each ad; make sure to retain this ID and pass it in the click event so GoWit knows exactly which ad was interacted with.

  • location_id (string, optional):
    The store or location context, if applicable (optional, analogous to its use in impression events).

Implementation Tip:​

Typically, your front-end will capture the user’s click (for example, via an onClick handler or a tracking link redirect) and notify your backend.

The backend can then call GoWit’s tracking API to register the click event, including the ad_id from the original ad response.

This ensures the click is recorded with the correct session and ad details, allowing GoWit to attribute any subsequent purchase to this click within the allowed time window.

Sale / Conversion​

A Sale (conversion) event is fired whenever an order or transaction is completed on your platform.
Every transaction should be reported via a sale event – not just those you suspect were ad-driven – so that GoWit has a complete picture of purchases and can determine which ones resulted from ad exposure.

The GoWit backend will handle attribution: it looks at each sale and checks if there were prior ad clicks or impressions in the same session (or associated with the same customer) that qualify for credit.

This means your job is simply to send all sales data; you do not include any specific ad reference in the sale event payload (no ad_id needed) – the system will automatically link the sale to the correct ad/campaign if applicable.

Fields:​

  • session_id (string, required):
    The session identifier for the user who made the purchase. This ties the conversion back to that user’s ad impressions/clicks during the session.

  • sales (array of objects, required):
    A list of one or more items/products that were purchased in the transaction.
    Each item in the array is an object with the following fields:

    • advertiser_id (string, required):
      The ID of the advertiser (seller) whose product was sold.
      This should match the advertiser or merchant ID used in your GoWit product feed for that item.

    • product_id (string, required):
      The identifier of the product that was purchased (as known in GoWit’s system, usually your internal product ID from the feed).

    • unit_price (number, required):
      The price per unit of the product that the user paid (e.g., the item’s sale price).

    • quantity (integer, required):
      The quantity of that product that was purchased in this order.

    • retailer_taxonomy (string, optional):
      A category or classification for the product (e.g., the category name or code in your catalog). This is optional metadata but can be included for richer reporting.

    • brand (string, optional):
      The brand name of the product, if available. This is optional and used for analytics (e.g., to report which brands are selling via ads).

If an order contains multiple different products (possibly from different advertisers), include all of them in the same sale event by adding multiple objects to the sales array.

The sale event represents an entire order, so you do not need to split it by item or advertiser – GoWit will evaluate each item in the array for attribution.

As noted above, you should omit any ad_id in a sale event; just provide the transaction details, and GoWit will credit the appropriate ad if the purchase is attributable to an earlier impression or click.

Even purely organic purchases (with no ad influence) should be sent, as they will simply not be attributed to any ad.
This ensures that performance reports capture both attributed and non-attributed sales for completeness.