Dynamic Free-Value Key Values allow publishers to pass custom values in incoming Source or Traffic Router requests and automatically forward those values to advertisers using campaign macros.
This functionality enables users to create new request parameters and matching campaign macros without requiring platform changes or development work. Any Free-Value key created in a Key Value List immediately becomes available as:
- a dynamic parameter in Source and Traffic Router tags;
- a campaign macro with the same name;
- a mechanism for passing custom publisher-provided values directly to demand.
Unlike standard Key Value Lists used for targeting and filtering, Free-Value Key Values act as dynamic request parameters that are resolved during request processing.
How It Works
The feature uses the existing Key Value Lists infrastructure.
Flow:
- Create a Free-Value Key Value List.
- Attach the list to a Source or Traffic Router.
- Add the desired key(s) to the generated Source or Router tag.
- Share the updated tag with the publisher.
- Use the corresponding macro in the campaign tag.
- The platform automatically replaces the macro with the incoming value.
Step 1. Create a Free-Value Key Value List
Navigate to: Tools → Global Lists → Key Value Lists
Create a new list.
Select Value Type: Free Values
Enter one or more keys.
Example: uid2_token
Each key is treated as an independent dynamic parameter.
Key Validation
The Key field supports:
- letters (A–Z, a–z)
- numbers (0–9)
- underscore (_)
- hyphen (-)
Multiple keys should be separated by commas.
Valid Examples: ttd_uid2,uid2,user_id
If an invalid value is entered, the following validation message is displayed:
Only letters and numbers and "_" and "-" are allowed in the Key field. Special characters and symbols are not permitted.
Step 2. Attach the List
The Free-Value Key Value List can be attached to:
- Source
- Traffic Router
Navigate to: Source → Advanced Settings → Key Values or Traffic Router → Key Values
Select the Free-Value Key Value List.
Note: Only Free-Value lists become available in the Tag Constructor. Standard Key Value Lists continue to be used only for targeting and filtering.
Step 3. Generate the Source or Router Tag
Navigate to: Source → Tag Constructor or Traffic Router → Router Tag
A new section named Custom Key Values is available.
Select the desired key(s).
The Tag Constructor automatically adds them as request parameters.
Step 4. Share the Tag
Provide the updated Source or Router tag to the publisher.
The publisher replaces: [replace_me] with actual values.
Example: uid2_token=abc123
Step 5. Configure the Campaign
Navigate to: Campaign → Basic Settings
Use the matching macro inside the campaign tag.
Example: {uid2_token}
The macro name always matches the key name.