Events
Carrot Ads API events occur when a user sees or engages with an ad, such as viewing an ad, clicking an ad, or adding an advertised product to a cart. Whenever an event occurs, your e-commerce site sends the event to Instacart. The events are used for billing, generating ads metrics, training machine learning models, and auditing purposes.
Types of events
The following table describes the types of events that can be sent for an ad. For the detailed list of event enums for each type of ad, see Track ads events.
| Event type | Description |
|---|---|
| Click | The user clicks an ad. |
| Add to cart | The user adds the advertised product to their cart. |
| Begin to render viewport (BTR) | The ad renders on the web or app. |
| 1px in viewport | The user views a single pixel of the ad. |
| Viewable in viewport | At least 50% of the ad is visible to the user for more than 1 second. |
When to send ad events
Whenever an ad is displayed to a user or a user successfully engages with an ad, send the ad event immediately. Timely and accurate events are critical for billing purposes and for returning recommendations.
For example, the following table describes the types of activities that trigger events for sponsored products and when to send the event:
| Activity | Implementation logic | Event type enum |
|---|---|---|
| User clicks an ad | Send the event after the backend has returned a 200 response to the frontend. | ian.sponsored_product.clickedian.display.click_creative ian.display.click_creative_item |
| User adds an advertised item to a cart | Send the event after the backend has returned a 200 response to the frontend. | ian.sponsored_product.added_to_cartian.display.add_creative_item |
| User increases the quantity of an added item using the "+" button | Send the event after the backend has returned a 200 response to the frontend. Send each time the quantity is incremented. For example, if the user clicks the add button twice, send the event twice. | ian.sponsored_product.added_to_cartian.display.add_creative_item |
| Ad begins to render on user's device | Send the event for each ad loaded on the user app or website. Send once per page load. If the server side sends four pages of results that are going to be paginated, send events for whichever pages are rendered. For example, if page 1 is rendered and displayed on screen, page 2 is rendered in the background, and page 3 and 4 are cached on the backend, then pages 1 and 2 send the event, but pages 3 and 4 don't send the event until rendered. | ian.sponsored_product.begin_to_render_viewportian.display.viewport_viewable_begin_to_render_creativeian.display.viewport_viewable_begin_to_render_creative_asset |
| Creative begins to load on user's device | Send the event after the client receives ad asset URLs and before downloading the assets. | ian.display.viewport_load_creative |
| User views 1px of the ad | Send the event for each ad when any portion of the ad is viewed. Send once per page load. If the ad is blocked by a modal, don't send this event. | ian.sponsored_product.1px_in_viewportian.display.viewport_1px_creativeian.display.viewport_1px_creative_item |
| User views more than 50% of the ad for more than 1s | Send the event for each ad when half of the ad is viewed for > 1s. Send once per page load. If the ad is blocked by a modal, don't send this event. | ian.sponsored_product.viewable_in_viewportian.display.viewport_viewable_creativeian.display.viewport_viewable_creative_asset |
When not to send ad events
Don't send events when the user performs the following actions:
- Decreases the quantity of an advertised item by using "-" button on the item card.
- Adds the same item to the cart after landing on the product detail page for an advertised item.
- Increases or decreases the item quantity from the checkout cart.
- Clicks or adds to cart from the retailer's organic ad on the same surface or another surface.
If you experience downtime, send the events as soon as service is restored. You might want to use a separate process for the backlogged events to avoid interference with sending new events.
Ad Event Sequence Diagram
The sequence diagram walks through the events that are sent when a page or carousel is rendered with Carrot Ads in it. To avoid ad blockers, the events are routed from the retailer's backend system. On the Instacart side, the requests are received through the Instacart Connect platform and routed to the Carrot Ad services. For more information about Instacart Connect, see the Connect documentation.
Optionally, retailers can decide to send the events to a customer data platform (CDP), such as Segment, and then send the events to Instacart.
To view the sequence diagram, see Ad Event Sequence Diagram.