Link Search Menu Expand Document


Custom Variables in Ad Requests


Last updated on August 21, 2015

You can include custom variables to provide additional information about your ad space if available ad request parameters do not meet your needs.

Each custom variable is expressed as a key-value pair (KVP) and must meet the following requirements:

  • To distinguish it from other types of ad request parameters, custom KVPs must be prefixed with the c. namespace. For example: c.topic=sports (where topic is the key and sports is the value)

  • Expressed using the following characters: a-z, 0-9, _ (underscore), or . (period) If you need to use reserved characters in your values, you can use percent-encoding (express them as a pair of hexadecimal digits derived from the character’s ASCII byte value and prefixed with %). For example, to include an exclamation point (!), use %21 instead.


    Uppercase letters in KVPs do not result in an error, but OpenX converts them to lowercase values. Therefore, only KVPs passed as lowercase characters will match line item targeting—even if entered with uppercase letters via the UI.

  • Multiple values for a single key must be separated by a comma (,). For example: c.age=30,40,50. Alternatively, specify multiple instances, such as: c.age=30&c.age=40&c.age=50

  • Multiple KVPs must be separated by an ampersand (&). For example: c.gender=m&c.age=40&c.topic=sports

  • Keys are limited to 20 characters.

  • Values are limited to 255 characters for each value. For multiple values of a single key, the sum of all of the values cannot exceed the 255 characters.

  • To include a custom variable in JavaScript ad tags, use the addVariable method before the fetchAds or requestAd methods.

  • If you use a standalone JavaScript tag format, you must pass in a vars object in the JSON structure to include custom KVPs in the ad tag. For example: "vars":{"*key1*":"*value1*"," key2":"*value2*"}