Tracking URLs and tag traffic

Adzen records impressions and clicks through URLs under https://api.adzen.ai/dea/. None of them takes an API key.

URLs your integration fires

The UGC API and the AI API return these URLs on each matched ad. Your client fires them from the viewer’s device.

Surface	Event	Response field	Method	Response
UGC	Impression	The `ads[].pixel_trackers[]` entry with `vendor` `adzen` and `tracker_type` `impression`	`GET` or `POST`	`204`, empty body
UGC	Click	`ads[].click_through_url`	`GET`	`302` to the landing page
AI	Render	`ads[].render_impression_url`	`GET`	`204`, empty body
AI	View	`ads[].view_impression_url`	`GET`	`204`, empty body
AI	Click	`ads[].click_through_url`	`GET`	`302` to the landing page

URL shapes:


https://api.adzen.ai/dea/ugc/impression?tid={SESSION_ID}&experiment={EXPERIMENT}&treatment={TREATMENT}&...
https://api.adzen.ai/dea/ugc/redirect/<slug>?tid={SESSION_ID}&experiment={EXPERIMENT}&treatment={TREATMENT}
https://api.adzen.ai/dea/ai/impressions/render?ad_id=...&message_id=...
https://api.adzen.ai/dea/ai/impressions/view?ad_id=...&message_id=...&viewability_ms=1000
https://api.adzen.ai/dea/ai/redirect/<slug>

Rules

Fire each URL exactly as returned. Do not rebuild it, reorder its parameters or drop any of them.
UGC URLs carry three macros. Replace each one before you fire or link the URL. See Tracking macros.
Fire each impression URL once per ad view.
Link the ad to the click URL. The viewer’s browser follows the 302 to the advertiser’s landing page.
Every matched AI ad carries both render_impression_url and view_impression_url. For when to fire them, see Impression beacons.
Tracking URLs accept requests from US IP addresses. A request from another country gets 403. A viewer outside the US who opens a click URL gets the 403 and does not reach the landing page.

UGC macros

Macro	Replace with
`{SESSION_ID}`	A value that is new for each ad view. Put the same value in that ad view’s impression URL and click URL.
`{EXPERIMENT}`	The id of the A/B test the viewer is in. An empty string when the viewer is in no test.
`{TREATMENT}`	The test arm the viewer is in. An empty string when the viewer is in no test.

A second impression with the same {SESSION_ID} value from the same device within 5 minutes counts as invalid, even for a different ad.
{EXPERIMENT} and {TREATMENT} take up to 128 characters from A to Z, a to z, 0 to 9, _, -, ., : and /. Adzen ignores a value outside these rules, and the values undefined and null. The impression and click still count.

AI beacons

A second render beacon, or a second view beacon, for the same ad in the same message from the same device within 5 minutes counts as invalid.

Responses

Status	When	Retry?
`204`	Impression URLs, including requests Adzen records as invalid.	No. Do not fire the same impression again.
`302`	Click URLs. The `Location` header is the advertiser’s landing page.	No
`400`	An AI beacon whose `ad_id` or `message_id` is missing or empty, or a view beacon without an integer `viewability_ms`. The body is `{"error": "..."}`.	No. Fire the URL exactly as returned.
`403`	The request came from an IP address outside the US.	No
`404`	A click URL that Adzen does not recognize.	No
`502`	A temporary error on an AI click URL. The body is empty.	No

Fire from the viewer’s device

Adzen validates each impression and click against the viewer’s IP address and user agent. Fire impression URLs and open click URLs from the viewer’s browser or app. A request with no user agent, or with the user agent of an automation tool, is recorded as invalid.

Tag traffic

The Adzen tag on publisher pages sends these requests from the viewer’s browser. You do not call them.

Endpoint	Method	What it does
`/dea/url/keywords`	`POST`	Fetches the ads to place on the current page
`/dea/url/placements`	`POST`	Confirms that a placement rendered on the page
`/dea/url/placements/failures`	`POST`	Reports a placement that failed to render
`/dea/url/impression`	`POST`	Records a display ad impression
`/dea/url/hover`	`POST`	Records a hover on an ad
`/dea/url/safety-sample`	`POST`	Sends up to 4,000 characters of the page’s article text for content-safety review, when the keywords response asks for it
`/dea/redirect/<slug>`	`GET`	Display ad click. Redirects with `302` to the landing page.

Paths under /dea/url/ accept requests from any country.
/dea/redirect/ accepts requests from US IP addresses.

Content Security Policy

If your pages set a Content Security Policy, allow these sources:

Directive	Source	Why
`script-src`	`https://widget.adzen.ai`	The tag loader and its script bundle
`style-src`	`https://widget.adzen.ai` and `'unsafe-inline'`	The tag’s stylesheet, and the inline styles on each ad unit. A narrower `style-src-attr 'unsafe-inline'` also works.
`connect-src`	`https://api.adzen.ai`	Every tag request to `/dea/url/`
`img-src`	`https:`	The tag loads advertisers’ impression trackers as images. It loads only `https://` tracker URLs, and the hosts vary by advertiser.

The tag sends each POST with Content-Type: application/json;charset=utf-8, so the browser sends an OPTIONS preflight first. Do not block OPTIONS requests to api.adzen.ai in a proxy or firewall. If the preflight fails, the browser does not send the request.