Skip to main content

Key/Value Pairs

C
Written by Caitlyn Lei
Updated over 6 months ago

Key/Value Pairs is a targeting feature that allows publishers to use custom metadata on their sites to deliver direct sold campaigns.

Example case study on a publisher's successful use of Key/Value Pairs.

Getting Started

Using key/value targeting requires a two step set up on Nativo Admin and publisher’s website.

Define key/value pairs on Nativo Admin

  1. Sign in on Nativo Admin.

  2. Navigate to Monetization tab and click Key-Values.

  3. Click Create Key.

  4. Add a key name.
    Key name cannot contain spaces and cannot be prefixed with a number.
    ​Read more limitations on characters allowed.

  5. Add a display name.

  6. Check the Allow Free-Form Values box to allow additional values to be added for targeting at Budget level.
    ​Read more details on Free-Form values.

  7. Click Create.

  8. Add corresponding values under Values input box on the next page.
    Value format restrictions include a max of 40 characters per value, a max of 20,000 active values per key. Read more limitations on characters allowed.

  9. Click Save.

Applying Key Value Pair Targeting to Campaign Budgets

  1. Navigate to the targeting tab within the budget object, select “Key Value Pairs” from left rail of the targeting tab.

1305

  1. Select a key from the drop down

1548

  1. Toggle to add a new value, and enter value into the field. Click "Add value".

1542

  1. Validate the key value present in the targeting summary and save the budget.

1532

Adding multiple values by uploading a file

  1. On the Edit Key page, click on Upload File radio button.

  2. Select CSV file and it will be uploaded automatically.
    Accepted file format is a single column CSV file with no header.

Define key/value attribute on publisher website

Setting key/value attribute on publisher’s website is supported by HTML meta tag and JavaScript tag.

HTML meta tag

Key/value attribute may be set on HTML meta tag with custom metadata name ntv-kv. One or more tags can be placed in a single HTML page to define multiple key-value attributes.

Each tag should contain a key and its corresponding values. Multiple values separated by a comma is supported per key.

HTML

<!-- One Key One Value --> <meta name="ntv-kv" key="name" values="value1"> <!-- One Key Multiple Values --> <meta name="ntv-kv" key="name" values="value1,value2,value3,value4"> <!-- Multiple Keys One Value Per Key --> <meta name="ntv-kv" key="name_a" values="value"> <meta name="ntv-kv" key="name_b" values="value"> <!-- Multiple Keys Multiple Values Per Key --> <meta name="ntv-kv" key="name_a" values="value1,value2,value3,value4"> <meta name="ntv-kv" key="name_b" values="value5,value6,value7,value8">

🚧

The HTML meta tag should be rendered before Nativo’s load.js is executed.

JavaScript Implementation

Key/value attribute may be set in the JavaScript object ntvConfig under keyValues property. One or more keys can be placed in a single HTML page to define multiple key-value attributes.

JavaScript

// Initiate an empty object var kvpMap = {}; // To set one key one value pair kvpMap["name1"]= "value1"; // To set one key, multiple values pair kvpMap["name2"]= "value2,value3,value4"; // define "ntvConfig" object if it is not already defined window.ntvConfig = window.ntvConfig || {} ; // Assign the defined key value pairs to "keyValues" property window.ntvConfig.keyValues=kvpMap;

🚧

The JavaScript code should be executed before Nativo’s load.js is loaded.

Limitations

Characters

There is a maximum of 20 characters per key and a maximum of 40 characters per value. Both keys and values are not case-sensitive. Key cannot be a prefixed number and cannot contain spaces.

Publisher can choose to set as many key-value attribute on the page as they like.

However, the number of key/value sent to Nativo’s adserver is limited to the browser’s URL character limit for GET requests. A common restriction is 2,048 characters, minus the number of characters in hostname and path.

Following characters are not allowed on key and value;

" (double quotes) ' (apostrophe) = (equal sign) ! (exclamation point) + (plus sign) # (pound sign) * (asterisk) ~ (tilde) ; (semicolon) ^ (caret) () (parentheses) < > (angle brackets) [ ] (square brackets) , (comma) & (ampersand)

PII

Publishers are responsible to restrict PII (personal identifiable information) from being sent to Nativo.

Predefined and free-form key/values

Predefine a key and its values or create a free-form key-value. Free-form key-values use a defined key but take dynamic values based on user attributes or behavior.

Predefined key/values

Use predefined key/values when you know the possible range of values. For example, if you're targeting a budget to users age 18-34, create the predefined key age, and enter ranges as values (such as, "18-34" or "35-49"). When you create the budget, select age as the key and "18-34" as the value. When you target a budget to a predefined key-value, you choose from a list of values in defined in the Nativo Admin. When a value is removed, it no longer appears as a targeting option.

Free-form key/values

Free-form key/values let you pass targeting values dynamically based on information you collect. For example, you can use free-form key/values to target ads based on DMP audience information on your site.

Did this answer your question?