Proxy Tracking

Owned by Siamak Haschemi (Deactivated)
Last updated: Apr 22, 2021
3 min read

Introduction

Proxy tracking is one of multiple methods to do first-party tracking with the Ingenious platform.

To setup proxy tracking, you need to take care of the following things:

  • Tracking proxy configuration

  • Advertiser configuration

  • Platform configuration

Tracking proxy configuration

The tracking proxy is an intermediate server that listens to requests that clients such as browsers send to a public tracking domain such as fuchsia.example.com. The task of the tracking proxy is to forward requests to the Ingenious tracking server.

This document assumes that you have a tracking proxy provisioned. There are specific things that you need to consider when forwarding requests via a tracking proxy (in contrast to a setup in which you send requests directly to the Ingenious tracking server).

Request forwarding

This section describes how HTTP requests should be accepted and forwarded.

Upstream

The Ingenious tracking server domain (not the tracking proxy domain!) is the endpoint that the tracking proxy forwards requests to:

proxy.ingenious.cloud

The Ingenious tracking server domain must not be created in the platform, it is maintained by Ingenious so that the Ingenious tracking services are available under that domain.

Both HTTP and HTTPS protocols can be used with this domain, although we recommend to use HTTPS.

Requests

The tracking proxy must accept requests matching the following properties:

  • Request scheme: https

  • Request host: the request host must be equal to the proxy tracking domain.

Request header types

For proxy tracking setups we differentiate between three types of HTTP headers:

  • Common request headers (headers not specific to proxy situations)

  • Cookie header

  • Proxy headers

The following paragraphs describe how each type of headers should be handled.

Common request headers

The tracking proxy must forward all incoming HTTP headers through to the tracking server.

Cookie header

In HTTP, the HTTP header “Cookie” transmits cookies from clients to servers. You need to make sure that specific cookies are forwarded to the Ingenious tracking server.
The following cookies of incoming HTTP requests of the client must be forwarded to the tracking server.

  • tsc

  • tsv

  • tse

  • trackingoptout

  • trackingoptout_* (All cookies starting with trackingoptout_.)

Proxy headers

In HTTP, multiple HTTP headers exist that are specifically designed for situations in which proxies are in use. To enable accurate tracking, the tracking server requires specific proxy headers to be present in HTTP requests that are forwarded by a tracking proxy.
The following table lists the proxy headers that the proxy needs to include with a request that it forwards to the tracking server.

Key

Expected value

Proxy Behaviour

Key

Expected value

Proxy Behaviour

x-forwarded-for

IP Address list containing all IPs, including the IP address of the initial HTTP request.

Create or extend this header.

x-forwarded-host

Host of initial HTTP request.

Set to host of initial HTTP request.

x-forwarded-proto

Protocol of initial HTTP request.

Set to protocol of initial HTTP request.

Response forwarding

This section describes how HTTP responses of the tracking server should be forwarded back to the client.

Request header types

For proxy tracking setups we differentiate between two types of HTTP headers:

  • Common request headers (headers not specific to proxy situations)

  • Cookie header

Common request headers

All HTTP headers returned from the Ingenious tracking server should be forwarded through to the client.

Cookie header

In HTTP, the HTTP header “Set-Cookie” transmits cookies from clients to servers. You need to make sure that specific cookies are forwarded to the Ingenious tracking server.
The following cookies returned from the Ingenious tracking server must be forwarded back to the client.

  • tsc

  • tsv

  • tse

  • trackingoptout

  • trackingoptout_* (All cookies starting with trackingoptout_.)

Advertiser configuration

To enable proxy tracking, you need to adjust the tracking settings of the advertiser. The following table lists the tracking settings that you need to adjust.

 Advertiser tracking setting

Value

Example

Description

 Advertiser tracking setting

Value

Example

Description

Tracking domain

{tracking-subdomain}.{advertiser-domain}.{top-level domain}

fuchsia.example.com

The domain that is used to track events of your Advertiser.
The tracking domain of the advertiser must be the domain of the tracking proxy.The domain is used for generating tracking URLs in the platform,
and will be used to validate incoming tracking requests.

Cookie domain

.{advertiser-domain}.{top-level domain}

.example.com

The cookie domain is an advanced setting and can be changed by Ingenious Administrators only. 
Please contact your customer success manager. They will help to define the cookie domain and change the setting for you.

FAQ

Tracking opt-out links

The opt-out links for tracking in proxy tracking setups correspond to the public tracking domain (which is the proxy tracking domain).

The opt-out links have the following structure:

Out-out

https://{Advertiser tracking domain}/ts/{Advertiser external ID}/tsv?settrackingoptout=a

Opt-out reset

https://{Advertiser tracking domain}/ts/{Advertiser external ID}/tsv?resettrackingoptout=a


Opt-out link example

If your proxy tracking domain is fuchsia.example.com, then the opt-out link will be

https://fuchsia.example.com/ts/{Advertiser external ID}/tsv?settrackingoptout=a