Knowldege Hub
Start typing to search…

Ad Events Guide

Learn how to implement ad event tracking to measure the complete customer journey from ad exposure to conversion.

Ad Events Integration Guide

This guide explains how to implement ad event tracking with the Zitcha Collect API to measure the complete customer journey from ad exposure to conversion.

Overview

Ad events form the attribution chain that connects advertising exposure to business outcomes. By tracking impressions, clicks, and conversions, you can measure ad effectiveness and optimise campaign performance.

The Attribution Chain

Ad Impression → Ad Click → Ad Conversion

Each event builds on the previous one, using shared identifiers to link exposure to engagement to outcomes.

Common Concepts Across All Ad Events

Customer Identifiers

  • ⚠️ Must always be included to link impressions → clicks → conversions
  • ⚠️ This is an array field — send multiple identifiers if possible (e.g., session ID + CRM ID)
  • 💡 FAQ: Why more than one identifier? To connect anonymous (session) and logged-in (CRM) activity

Page View ID

  • ⚠️ Must be a UUID generated at page view time
  • ⚠️ All impressions and clicks on that page must reference the same ID
  • 💡 FAQ: When do I generate a new one? On every page load/reload

Page Location

  • ⚠️ Preferred: structured paths (e.g., home > category > product) for richer reporting
  • ✅ Acceptable fallback: full URL
  • 💡 FAQ: Can I just send a URL? Yes, but structured paths give better insights

Placement ID

  • ⚠️ Should identify the slot/placement, not a random hash
  • Sponsored product → slot_1, slot_2, etc.
  • Banner → placement value from Search API
  • 💡 FAQ: What should placement ID look like? A slot number or placement name

Ad Impressions

An ad impression event captures the moment an advertisement is displayed to a customer. It is the starting point of the attribution chain, allowing impressions to be connected with clicks and conversions using shared identifiers.

Industry Standard: What Counts as an Ad Impression?

According to the IAB/MRC Retail Media Measurement Guidelines:

  • Ad Impression: An impression is counted when an ad has been successfully delivered to a user's device and has begun to render (for display, video, or app) — even if the user doesn't scroll to see it.

  • Viewable Impression: A stricter measure that reflects whether the ad had the opportunity to be seen:

    • Display ads: at least 50% of pixels visible on screen for 1 continuous second.
    • Video ads: at least 50% of pixels visible for 2 continuous seconds

👉 Best Practice: We recommend aligning with the IAB/MRC "viewable impression" definition. In practice, this means triggering an impression when the ad enters the viewport and has been visible for at least one continuous second (for display) or two seconds (for video).

Why Ad Impressions Matter

Ad impressions provide the baseline for all measurement. Without impression data, clicks and conversions cannot be attributed back to exposure, making closed-loop reporting impossible.

Ad Clicks

An ad click event is logged when a customer actively interacts with an advertisement. Clicks bridge the gap between impressions and conversions, helping to measure ad engagement and effectiveness.

Industry Standard: What Counts as a Click?

According to the IAB/MRC Click Measurement Guidelines:

  • A valid click is user-initiated interaction with clickable ad content.
  • User activity outside of clickable content is not considered a valid click (e.g., tapping outside the ad frame, accidental swipes)
  • For mobile, measurement must account for accidental or incidental clicks (e.g., due to small screen navigation) and apply appropriate filtering.
  • Reporting should distinguish between raw clicks, resolved clicks (where a valid destination is reached), and post-click activity (such as conversions)

👉 Best Practice: We recommend aligning with IAB/MRC standards — log only clicks on valid ad creatives and filter accidental taps.

Implementation Notes

  • ⚠️ Must generate a UUID for click_id at click time
  • Each click should have its own unique ID
  • Same page_view_id and customer_identifiers as the impression

Why Ad Clicks Matter

  • Engagement Insight: Show how many people interacted with an ad relative to impressions.
  • Attribution: Connects the exposure (impression) to a potential conversion.
  • Optimisation: Identifies which placements, formats, and creatives drive the highest engagement.

Ad Conversions

An ad conversion event represents the moment when a customer completes a valuable action such as a purchase, checkout, signup, or add-to-cart. Conversions are the final step in the ad journey, enabling closed-loop reporting that ties ad exposure to real business outcomes.

Important Notes & Common Questions

Conversion Type

  • ⚠️ Valid values are sale, checkout, signup, add_to_cart.
  • ❌ Values like purchase or lead will be rejected.
  • 💡 FAQ: Why was my conversion rejected? Likely due to sending an unsupported type.

Basket Object

  • ⚠️ Must always include currency, value, and product details.
  • 💡 FAQ: Why is my order not showing correctly? The basket object may be missing or misformatted.

Availability

  • ⚠️ Always include product availability. Defaults to in stock if omitted.
  • 💡 FAQ: Why isn't my ad showing? The product may have been marked out_of_stock.

Expiration Date

  • ⚠️ Only way to remove a product from the platform/Search API.
  • 💡 FAQ: How do I remove a product? Set expiration_date to now or a past date.

Why Ad Conversions Matter

  • Proof of Value: Show which ads drive revenue and signups.
  • Attribution Accuracy: Connect impressions and clicks to outcomes.
  • Optimisation: Inform bidding, targeting, and creative strategies based on real results.

Page Views

A page view event captures when a customer loads or reloads a page on your site. It provides the anchor point for impressions and clicks that happen during that browsing session.

How Page View Works

  • A new page_view_id must be generated each time a page loads or reloads.
  • Any impressions or clicks that happen on that page must reference the same page_view_id.
  • This ensures that all ad activity can be tied back to the page where it occurred.

👉 Best Practice: Generate a UUID on the client side whenever a page view is created.

Important Notes

  • ⚠️ Must be created at page load/reload time, not impression time.
  • ⚠️ All impressions and clicks on the same page must reference the same ID.
  • 💡 FAQ: When do I generate a new page_view_id? Every time the page reloads or a new page is loaded.

Why Page View Matters

  • Attribution: Groups impressions and clicks under a single session context.
  • Reporting: Enables accurate analysis of ad performance by page.
  • Data Quality: Prevents mismatches between impressions, clicks, and conversions.

Related Resources

Updated about 1 month ago