Tracking & Attribution Integration

This guide provides a technical overview for integrating event tracking and attribution on the GoWit retail media platform. It covers how to report ad impressions, clicks, and sales (conversions) using server-to-server APIs (the preferred method), with details on required data fields, payload formats, and best practices for session and user identifiers. By following this guide, developers can ensure that GoWit properly attributes conversions to ad interactions – GoWit handles the attribution logic on the backend; your job is to send clean, timely event data.

Before You Start

Before implementing event tracking, familiarize yourself with the Data Source Management console. This interface provides visibility into event logs and helps you debug issues related to impression, click, and conversion submissions. By using the assigned Data Source UUID, you can trace requests end-to-end and confirm that all tracking events are being recorded correctly. This step is essential to validate attribution accuracy during QA and live operations.

ℹ️ For more details, see Data Source Management

Overview: Server-to-Server Event Tracking

GoWit strongly recommends handling tracking events via server-to-server calls for maximum reliability and accuracy. In practice, this means your backend should capture and forward events (ad rendered, clicked, purchased) to GoWit’s API rather than relying solely on client-side scripts. Key events to integrate include:

• Impression – when an ad is rendered/displayed on the user’s screen.
• Click – when the user clicks an ad.
• Sale (Conversion) – when a user completes a purchase (order confirmation).

For each ad delivered, your backend will receive a unique ad_id in the ad response. Use this ad_id to log an impression when the ad is shown, and include it again if the ad is clicked. Every sale (order) should also be reported, regardless of whether you think it came from an ad, and tagged with the same session context – GoWit’s attribution engine will determine which orders are ad-influenced vs. organic.

In summary, your system emits the events, and GoWit “handles the rest” by performing attribution server-side.

Why Server-to-Server?

Sending events from your backend ensures tracking is not blocked by ad blockers, and guarantees events are recorded even if the user’s browser drops a request or navigates away quickly. It also centralizes logging in your system (you can reliably know an event was sent). While GoWit provides client-side SDK tools for certain cases, those come with risks of tracking loss or session mismatches – for example, if a user has scripts blocked or if the client isn’t using the exact same session identifier, the event may not link up correctly. Thus, the server approach is the source of truth for critical events.

Event Types and Payload Examples

All tracking events are sent as HTTP POST requests to GoWit’s tracking API (e.g., a /events endpoint). Each event payload includes a few common fields plus event-specific data. All events must include your session_id and marketplace_id (your platform’s ID in GoWit). Events that involve a particular ad must include the ad_id as well. Below are the primary event types with their JSON structure and required fields:

Impression Event (Ad Rendered)

An impression event should be sent when an ad is successfully rendered on the user’s page (i.e., in view to the user). This can be triggered by your backend as soon as you deliver an ad to the front-end for display.
(Note: If your integration uses GoWit’s auto-impression feature, you do not need to manually send impressions – see Auto-Impression below.)

Required fields

• event_type = "impression"
• session_id
• ad_id
• typically placement_id (the placement or ad slot ID where the ad was shown)
• marketplace_id to identify your platform

Example Payload

{
  "event_type": "impression",
  "marketplace_id": "YOUR_MARKETPLACE_ID",
  "placement_id": "PLACEMENT_ID",
  "session_id": "SESSION_UUID",
  "ad_id": "AD_UUID"
}

In this example, an ad impression is logged with the unique IDs for the marketplace, placement, session, and ad. GoWit will record that this ad_id was shown to the user identified by session_id in the given placement.

If your marketplace is configured with auto_impression = true, GoWit’s servers will automatically record impression events whenever an ad is delivered to you. In that case, the session_id from your ad request is used to log the impression internally, and you should not send duplicate impression events. Auto-impression simplifies integration (fewer API calls for you), but it only covers impressions – you will still need to send click and sale events yourself.

Click Event (Ad Clicked)

A click event is sent every time a user clicks on a sponsored ad on your site/app. This is crucial for performance metrics (CTR) and for starting the post-click attribution window.

Required fields:

• event_type = "click"
• session_id
• ad_id
• typically placement_id (the placement or ad slot ID where the ad was shown)
• marketplace_id to identify your platform

Example Payload

{
  "event_type": "click",
  "marketplace_id": "YOUR_MARKETPLACE_ID",
  "placement_id": "PLACEMENT_ID",
  "session_id": "SESSION_UUID",
  "ad_id": "AD_UUID"
}

This payload indicates the ad identified by ad_id was clicked by the user in the given session. Send click events in real time (as soon as the click happens) so that GoWit can log them and initiate attribution timing for conversions. Typically, your front-end can capture the click (e.g., via an onClick handler or by directing to a tracking URL) and notify your backend, which then calls the GoWit event API.

Sale Event (Conversion)

A sale event should be sent whenever an order (purchase) is completed on your platform. This allows GoWit to attribute conversions (revenue, order count) back to ad impressions or clicks. It is important to send every sale (not just those you think are ad-related) to give a full picture — GoWit will decide which sales qualify for attribution credit.

Required fields:

• event_type = "sale"
• session_id

Instead of an ad_id, provide a list of one or more sold items in a sales array. Each item in sales should include:

• advertiser_id – the seller or advertiser who sold the product (this should correspond to the one provided in your product feed to GoWit).
• product_id – the identifier of the product that was purchased.
• unit_price – the price per unit (each) that the item sold for.
• quantity – the quantity of that item purchased.

You may also include optional fields per item such as brand or retailer_taxonomy (category name) if available, but the above are the key fields. If the order contains multiple items (from potentially different advertisers), include them all in the sales list in the same event.

Example Payload

{
  "event_type": "sale",
  "marketplace_id": "YOUR_MARKETPLACE_ID",
  "session_id": "SESSION_UUID",
  "customer_id": "CUSTOMER_ID",       // optional, if known
  "sales": [
    {
      "advertiser_id": "ADVERTISER_ID",
      "product_id":    "PRODUCT_ID",
      "unit_price":    99.99,
      "quantity":      1,
      "brand":         "BRAND_NAME",   // optional
      "retailer_taxonomy": "CATEGORY" // optional
    }
  ]
}

In this example, a sale of one unit of PRODUCT_ID (sold by advertiser_id) for $99.99 is reported. If a single order contains multiple different products, you can include multiple objects in the sales array. The session_id ties this order to any prior ad interactions by the same user session. If you have a customer_id for the buyer, it’s good practice to include it at the top level as shown (for analytics and cross-session attribution).

Attribution Logic

Once GoWit receives a sale event, it will automatically attempt to match each sold item to prior ad events from that session (or customer) within the allowed lookback windows. The platform checks if there was a recent click on an ad for the same product or by the same advertiser (depending on campaign settings), or a view without a click (view-through attribution), etc. All such rules are handled internally:

• If a conversion is attributable to an ad impression or click, GoWit records the conversion under that ad/campaign for reporting.
• If no matching ad interaction is found (e.g., truly organic purchase), the sale is simply not attributed to any ad – it will count as organic revenue.

You do not need to send any ad reference in the sale event (no need for ad_id or campaign info) – just provide the clean purchase data, and the system will link it to the appropriate ad touchpoint if one exists.

By sending all sales, you ensure GoWit’s attribution models (both post-click and post-view) have complete data to work with. The attribution results (which ads drove how many sales, revenue, ROAS, etc.) will be visible in the GoWit dashboard and reports automatically once events flow through.

Viewable Impression (Optional)

A viewable impression event is an optional metric to track whether an ad was actually in-view to the user (as opposed to just delivered). This is used for viewability analytics and to optimize placement quality, but is not required for core attribution or billing.

Implementing viewable impressions usually requires a client-side component (since the browser needs to detect if the ad element is within the visible viewport per industry standards, e.g., 50% of pixels in view for at least 1 second for display ads). GoWit might provide a JavaScript Viewability SDK that can be integrated into your front-end to fire these events.

Key points:

• Not required. You can launch without viewability tracking; if needed, it can be added later for additional insights.
• No impact on attribution. Viewable impressions do not replace or count as regular impressions; they are recorded separately for analytics. They also do not influence conversion attribution logic (they’re mainly to report metrics like “% of impressions that were viewable”).
• Client-side capture. Typically, you’d use GoWit’s viewability library or your own IntersectionObserver logic in the browser. When an ad becomes viewable, call the tracking endpoint with event_type = "viewable_impression", including the same session_id and ad_id as the original impression.

Example Payload

{
  "event_type": "viewable_impression",
  "marketplace_id": "YOUR_MARKETPLACE_ID",
  "placement_id": "PLACEMENT_ID",
  "session_id": "SESSION_UUID",
  "ad_id": "AD_UUID"
}

Because viewable impressions require executing code on the client, ad blockers or network issues can prevent these events from reaching GoWit. This is acceptable since they are supplemental – just be aware that viewability metrics might be undercounted if the user has blocking software. Always ensure the same session_id is used when firing a viewable impression from the client; one common method is to have your backend inject the session_id and ad_id into the page so the client knows what values to use.

Auto-Impression Feature

As mentioned earlier, GoWit offers an auto-impression feature for partners to simplify integration. When auto_impression is enabled for your marketplace, you do not need to explicitly send impression events for ads – GoWit will log them on your behalf as soon as an ad is delivered to your system.

Here’s how it works:

• Your ad request (to the GoWit /ads API) includes a session_id and placement. When GoWit returns an ad (with an ad_id), it simultaneously records an impression event internally using that ad_id, session_id, and placement details.
• This means by the time your backend receives the ad response, the impression is already tracked. Do not double-send an impression for the same ad if auto-impression is on.
• You should still maintain the ad_id in memory or state because you’ll need it for click events (and for any client-side viewability tracking if used). GoWit’s response includes the ad_id for each ad unit, so retain it.

Remember that auto-impression only covers the initial impression. Your integration must still handle:

• Click events: Send a click event when the ad is clicked (auto-impression doesn’t cover clicks).
• Sale events: Send conversions as usual.
• Viewable impressions: If you’re tracking viewability, that still needs to happen client-side.

If you choose not to use auto-impression (or if it’s not enabled), then you are responsible for calling the impression tracking endpoint whenever an ad is rendered. The logic is straightforward – right after your backend injects an ad into the page (or returns it to the frontend), trigger the impression event to GoWit with the relevant IDs.

End-to-End Event Flow

To put it all together, below is the end-to-end flow of a user interaction and how events are generated and processed:

1. Ad Request: Your backend calls GoWit’s ad API (with session_id and context). Outcome: you get an ad in response (containing ad_id etc.), and (if auto-impression is on) GoWit logs an impression internally.
2. Impression: The ad is rendered to the user. Trigger: Log an impression event (server-to-server) with the ad_id and session_id if you are not using auto-impression.
3. Click: The user clicks the ad. Trigger: Log a click event with the same ad_id and session_id (real-time).
4. Sale: The user completes a purchase on your site. Trigger: Once the order is confirmed, send a sale event with the session_id and details of what was purchased (product IDs, prices, quantities, etc.).
5. Attribution Result: GoWit’s platform processes the events. If the sale is attributable to the earlier ad click or impression (within the attribution window), it will credit that ad/advertiser with the conversion. These results are then visible in reporting (e.g., the advertiser’s campaign performance metrics will show a conversion, and you can see attribution logs in your dashboard).

Recap Table

Below is a summary of the four event types, their requirement status, trigger conditions, and important notes:

Event Type	Required?	Trigger Condition	Notes
Impression	Yes*	Ad is displayed to the user	Required unless using auto-impression. If auto-tracking is enabled, the system logs impressions for you, but you still handle clicks & sales.
Viewable Impression	No	Ad visible X% for Y seconds	Diagnostic only (for viewability metrics). Has no effect on billing or attribution.
Click	Yes	User clicks the ad	Always implement – measures engagement. Use the ad_id from the ad response when sending this event.
Sale / Conversion	Yes	Transaction completes (order placed)	Must be sent for all purchases. Include all sold items in one event; GoWit will attribute the sale to any relevant prior ad interactions.

* Yes for Impression events indicates they are required for normal integrations. If the auto-impression feature is enabled, manual impression events are not needed.