Ads events notification

Learn how to send events like impressions, clicks, and conversions to VTEX Ads.

This guide explains how to send event notifications to VTEX Ads. You can send events in two ways:

Through a web browser using the sendBeacon() API
Server-side or through native apps using REST endpoints

🚧 Don't construct event URLs manually. Always use the URL provided from the POST Get ads request.

This is extremely important to ensure long-term stability of the integration, because the parameters of the event URL may change over time, but the integration itself does not.

Sending events via browser

For sending notifications in a web environment (browser), use the sendBeacon() method, as it is the most modern way to send data notifications. The advantage of using sendBeacon() is that the request is asynchronous, which means it doesn't block the loading of the current page nor the next page.

Response example from POST Get ads:


_17{
_17  "products": [
_17    {
_17      "ad_id": "4a94bc6e-7db1-425f-8430-cb4d17488b3b",
_17      "sku": "120210",
_17      "click_url": "https://events.newtail-media.newtail.com.br/v1/beacon/click/4a94bc6e-7db1-425f-8430-cb4d17488b3b?pos=1",
_17      "impression_url": "https://events.newtail-media.newtail.com.br/v1/beacon/impression/4a94bc6e-7db1-425f-8430-cb4d17488b3b?pos=1",
_17    },
_17    {
_17      "ad_id": "8c293205-52f4-45cf-9a01-37e7c26a5abc",
_17      "sku": "123123",
_17      "click_url": "https://events.newtail-media.newtail.com.br/v1/beacon/click/8c293205-52f4-45cf-9a01-37e7c26a5abc?pos=2",
_17      "impression_url": "https://events.newtail-media.newtail.com.br/v1/beacon/impression/8c293205-52f4-45cf-9a01-37e7c26a5abc?pos=2",
_17    }
_17  ],
_17  "banners": []
_17}

To send an impression event, for example, take the impression_url from the first ad and use it as follows:


_10let user_data = {
_10   user_id: "6f92d1e9-00b6-4f8b-9645-faeab321e1cc",
_10   session_id: "5898b8d1-c250-4bb5-931b-8b9d0ee7b499"
_10}
_10
_10let beacon_url =  "https://events.newtail-media.newtail.com.br/v1/beacon/impression/4a94bc6e-7db1-425f-8430-cb4d17488b3b?pos=1"
_10
_10var jsonBlob = new Blob([JSON.stringify(user_data)], { type: 'application/json' });
_10
_10navigator.sendBeacon(beacon_url, jsonBlob);

Sending events server-side or through a native app

In the cases that require sending via server-side or through a native app, make a POST request to the event URL, sending the user and session information in the payload.

You can use one of the following endpoints, depending on the event:

Request example:


_10POST https://events.newtail-media.newtail.com.br/v1/beacon/impression/4a94bc6e-7db1-425f-8430-cb4d17488b3b?pos=1 HTTP/1.1
_10user-agent: newtail
_10accept: application/json
_10content-type: application/json
_10
_10{
_10  "user_id": "6f92d1e9-00b6-4f8b-9645-faeab321e1cc",
_10  "session_id": "5898b8d1-c250-4bb5-931b-8b9d0ee7b499"
_10}

A successful response will return HTTP status code 202 with no body.