> For the complete documentation index, see [llms.txt](https://docs.exads.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.exads.com/general/general-custom-targeting.md). # Custom Key-Value Pairs Define custom key-value pairs to extend targeting, statistics reporting, and token passing. Custom key-value pairs let Publishers pass additional data with their ad requests. These pairs serve three functions: * **Passing Tokens**: Publishers can send additional data to Advertisers via custom key-value pairs. * **Advertiser Targeting**: Advertisers can target campaigns based on these key-value pairs. * **Statistics Reporting**: Advertisers, Publishers, and Network Admin Users can break down reports by these pairs. ## Supported Data Types | Type | Description | | ---------------- | ------------------------------------------------------------------------------------------------------------- | | Predefined List | A fixed set of possible values (e.g., `fruit=apple`, `orange`, `pear`). | | Predefined Range | A range of predefined values (e.g., `credit_score=normal`) when a value of between `200` and `500` is passed. | | String | Any sequence of characters (e.g., `UUID=abc123`). | | Number | Whole numbers (e.g., `age=30`). | | Range | A numerical range (e.g., `income=50000-100000`). | ## Passing Tokens For each ad request, Publishers may pass one value associated with a key. For example, if a Publisher passes a custom key-value pair such as age=18, this information will be available for reporting and targeting. ### How to Enable Tokens To use this feature, contact your account manager with the required key-value pairs. Provide: * **Key Name** * **Type** (String, Number, Range, Predefined List, Predefined Range) * **Valid Values** (if applicable, e.g., predefined list options) Once enabled, Publishers can pass these values via ad requests, and Advertisers can see them in reporting and targeting options if enabled at Ad Server level. ### How to Pass Tokens The example below shows how to pass Unique User Identifier (UUID) data to an ad tag. The `data-ex-uuid="name"` attribute is the UUID tag. This tag sends the user's UUID ("name" in this example) to the ad server, which can then use this information to show targeted ads.
Ad tag with the data-ex-uuid attribute highlighted
```html ``` ## Advertiser Targeting Custom key-value pairs in targeting help Advertiser campaigns reach the right audience. Advertisers can target campaigns based on the custom key values provided by Publishers. For example: * If a Publisher passes `device_type=gaming_console`, Advertisers can target users based on this value. * If a Publisher passes `user_segment=premium_user`, Advertisers can focus their campaigns on premium users. The following examples show how each data type is used in targeting. The keys and values shown were configured for one network; each Ad Server has its own set of keys. ### Predefined List
Predefined list targeting with Car Brand values selected
Car brand is an example of a predefined list: a fixed set of values chosen when the key is configured. Predefined lists must be single-level; nested values are not supported. ### Predefined Range
Predefined range targeting with Credit Score values selected
Credit Score is an example of a predefined range: each named value maps to a range of numbers, defined when the key is configured. For example: * Low Credit Score: Values less than 200. * Normal Credit Score: Values between 200 and 500. * High Credit Score: Values above 500. ### String
String targeting with a UUID value entered
UUID is an example of a string key: its values are any sequence of characters. ### Number
Number targeting with a whole number entered
Numbers is an example of a number key: its values are whole numbers, which can be positive, negative, or zero. ### Range
Range targeting with a value range entered
A range key lets Advertisers target values between two limits, such as 1 and 100. The following table shows the syntax.
Input ValuesValues displayed in the chip
55
-10.5-10.5
-1000--5All values from -1000 to -5
1-10All values from 1 to 10
<1000Less than 1000
<=1000Less than or equal to 1000
>-1000Greater than -1000
>=-1000Greater than or equal to -1000
!=1000All values other than 1000
## Statistics Reporting Key-value pairs are available in reporting, allowing Advertisers, Publishers, and Network Admin Users to analyze data based on custom parameters. ### How It Works * When a Publisher passes a custom key-value pair, this data is logged alongside standard ad request data. * Advertisers, Publishers, and Network Admin Users can filter reports based on these custom values. {% hint style="info" %} For string-based key-value pairs (e.g. UUID) statistical data is available up to the last 7 days. {% endhint %} ### Example Use Cases * **Audience Insights**: Understand the distribution of key-value pairs (e.g., how many impressions were served to `user_segment=premium`). * **Performance Analysis**: Compare CTR or conversion rates across different custom values. * **Publisher Optimization**: Identify which key-value pairs contribute to higher revenue or engagement. ### Reporting Availability These key-value pairs are available in: * Dashboard Reports * API Data Feeds * Exportable CSV Files ## Restricting Custom Key-Value Pairs to Specific Accounts Custom key-value pairs can be restricted to specific accounts on an Ad Server. To enable this for particular accounts, contact your account manager with a list of the accounts and the relevant key-value pairs. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.exads.com/general/general-custom-targeting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.