Skip to main content

​
Overview

In most cases, client-side beacons (from the browser or app) are the preferred and recommended method for tracking ad events. However, in cases where this is not possible — such as on the server side, inside a mobile app, or within privacy-constrained environments, a server-side beacon can be used as a fallback.

Header

Required

Purpose

X-Forwarded-For

Yes

Includes original user IP

User-Agent

Yes

Identifies client device/browser

Referer

Recommended

Provides page context

Server-side beacons should be treated as a last resort. The IAB guidelines state that tracking should happen “as close as possible to the final delivery of an ad to the client.” We follow this best practice.

​
Required HTTP Headers

To ensure server-side beacons are valid and accepted by our systems, specific HTTP headers must be included in the request.

​
X-Forwarded-For format

The X-Forwarded-For header is a comma-separated list of IP addresses that tracks the path of the request through proxies.
  • If the header is already present, append the client IP to the list: X-Forwarded-For: ip-address-1, ip-address-2, client-ip-address
  • If the header is not present, create it with just the client IP: X-Forwarded-For: client-ip-address
Read more on X-Forwarded-For here (Mozilla Developer documentation).

​
User-Agent format

Provide the actual user agent string from the browser or app where the event originated. Example:
HTTP
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36
Read more on User-Agent here (Mozilla Developer documentation).
Referer is recommended. It indicates the URL where the beacon event occurred and is helpful for attribution.
Read more on Referer here (Mozilla Developer documentation)

​
Alignment with Ad Delivery API Requirements

These header requirements are consistent with those enforced by Criteo’s Retail Media Ad Delivery API. In both cases, proper client metadata (IP, User-Agent, Referer) must be preserved in server-side requests to ensure accurate attribution and filter out invalid traffic. If you’re implementing both ad delivery and beacon tracking server-side, ensure that your integration includes:
  • A realistic and IAB-compliant User-Agent,
  • A well-formed X-Forwarded-For header including the end-user IP,
  • A valid Referer indicating the origin page or context.
Mobile developersMake sure to avoid using default agents like okhttp/x.y.z, as these are considered invalid under IAB rules. Customize your User-Agent string to include OS and app version, e.g. app_android 1.2.3.

​
Example

Here is an API call example including the X-Forwarded-For, a User-Agent and a Referer in the header. 
curl -X POST \
  "https://b.us5.us.criteo.com/rm?rm_e=Gd_ceALPvoRY3bVY9-28TDhyVYwW5MUBgE8qBLTqDRORt4q1N7hHDiVm8KO4W-qG2bdCV9GvhNO1wySddekW7j7CF6Z8qIE3ihszU3ZJjFkfKxnmD7_8fhkzmLnZMmjFALzDlUgAyrXYhHx1tArrrLxMuzgOjBdk84q1VXthksSJufRof3a4cj1zqUY9c4PF2pF4kkDfqrOD1Z91UnzdaeLLzI_Hm7Zw47iL8p3_SEcDxCOD9Q4MBpjbE7YTRbNEt1Tr5fbLpY4v-raBDn33yQQzJS3F7tl5cedSJ0XK07f_iQHA2I_XGlVGPvubbmGQqDKlkT2USrc2BwqYb4kImQ&ev=4" \
  -H "X-Forwarded-For: 185.235.84.0,187.44.99.113" \
  -H "User-Agent: Mozilla/5.0 (iPhone; CPU iPhone OS 13_2_3 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.0.3 Mobile/15E148 Safari/604.1" \
  -H "Referer: https://www.example.com"
50978b61305298ed04b303dbf7aef9d3455e1c8ce2687d6a85592d9f1463b97b image

​
What’s next