Documentation: X-Forwarded-For Header for Ad Requests

This document outlines the implementation and behavior of the X-Forwarded-For header when making ad requests to the Hivestack VAST endpoint.

Overview

While the X-Forwarded-For (XFF) header is optional, it is recommended that publishers include it in their ad request network calls. It will be shared with the DSPs that cannot perform targeting using the geo object.

Key Features

1. Multi-IP Evaluation (Array Support)

The header accepts a single IP address or a comma-separated list (effectively an array) of IP addresses. Unlike standard systems that may only look at the first or last IP, Hivestack evaluates every public IP provided in the request.

• Logic: We check each IP against its geo-location data to find the one closest to the expected screen location (provided the IP is determined as originating from the same country the screen is in).

2. Automatic Port Handling

Publishers do not need to manually clean or format the IP strings to remove port numbers.

• Behavior: If an IP is passed with a port (e.g., 203.0.113.195:8080), our system automatically excludes the port before performing the geo-evaluation.

3. Fallback Behavior

If the X-Forwarded-For header is missing from the request:

• Default: The system will default to the IP address of the incoming network request.
• Risk: This is a fallback and can be unreliable, as the request IP often represents a centralized proxy or a data center rather than the actual screen location.

Implementation Samples (/schedulevast)

Note: The described X-Forwarded-For header handling and geo-evaluation logic apply to both the /schedulevast and /schedulejson endpoints. You can use the same header and IP formatting when making ad requests to either endpoint.

cURL (Command Line)

You can pass multiple IPs, including those with port numbers.

curl --request GET \
     --url 'https://demo.hivestack.com/v1/ads/getvast?screen_id=YOUR_SCREEN_ID&apikey=YOUR_API_KEY' \
     --header 'X-Forwarded-For: 203.0.113.195:8080, 70.41.3.18' \
     --header 'accept: application/xml'

Python (Requests)

import requests

url = "https://demo.hivestack.com/v1/ads/getvast"
# List of IPs to be passed
ips = ["203.0.113.195:5000", "70.41.3.18"]

headers = {
    "X-Forwarded-For": ", ".join(ips),
    "Accept": "application/xml"
}

params = {
    "screen_id": "YOUR_SCREEN_ID",
    "apikey": "YOUR_API_KEY"
}

response = requests.get(url, params=params, headers=headers)
print(response.status_code)

Node.js (Axios)

const axios = require('axios');

const getAd = async () => {
  const ipArray = ['203.0.113.195:8080', '70.41.3.18'];

  try {
    const response = await axios.get('https://demo.hivestack.com/v1/ads/getvast', {
      params: {
        screen_id: 'YOUR_SCREEN_ID',
        apikey: 'YOUR_API_KEY'
      },
      headers: {
        'X-Forwarded-For': ipArray.join(', '),
        'Accept': 'application/xml'
      }
    });
    console.log(response.data);
  } catch (error) {
    console.error('Error fetching ad:', error);
  }
};

getAd();

Additional Resources

For more information on how the X-Forwarded-For header works in standard web traffic, please refer to the MDN Web Docs.