Track when an ad is rendered or visible to a user.
Impression tracking is fundamental for measuring ad visibility in VTEX Ads. This guide explains how to properly send impression events when your application displays advertisements to users.
Impression event rules
- Impression events should be sent when an ad is rendered in the viewport.
- Each impression is deduplicated within a 1-minute window per user, per device, per ad.
- Impression events require both
user_idandsession_idfor proper attribution. - Impression URLs are unique to each ad and should be obtained from the Get ads response.
🚧 Don't construct event URLs manually. Always use the URL provided from the
POSTGet 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 an impression event
Use the POST Track ad impressions endpoint to send impression events. Check the endpoint documentation for detailed information about all available fields.
Request example:
_10POST https://events.newtail-media.newtail.com.br/v1/beacon/impression/4a94bc6e-7db1-425f-8430-cb4d17488b3b?pos=1 HTTP/1.1_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}
Successful response example:
A successful response will have HTTP code 202.
_10{_10 "messages": [_10 "impression will be processed soon"_10 ]_10}
Failed response example:
A failed response will have HTTP code 422. The error message follows the RFC 8927 format
_23[_23 {_23 "instancePath": "",_23 "keyword": "required",_23 "message": "must have required property 'user_id'",_23 "params": { "missingProperty": "user_id" },_23 "schemaPath": "#/anyOf/0/required"_23 },_23 {_23 "instancePath": "",_23 "keyword": "required",_23 "message": "must have required property 'session_id'",_23 "params": { "missingProperty": "session_id" },_23 "schemaPath": "#/anyOf/1/required"_23 },_23 {_23 "instancePath": "",_23 "keyword": "anyOf",_23 "message": "must match a schema in anyOf",_23 "params": {},_23 "schemaPath": "#/anyOf"_23 }_23]