Server-Side Beacons

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.

⚠️

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:

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).

Recommended Header

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 developers

Make 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"