AdButler’s Data Keys are key-value pairs that offer more ways to target your audience. For example, you can create a key age with type NUMBER to hold age values.

Data keys don't do anything on their own. They must be used in tandem with Data key targets, which combine data keys with conditional operators and options, such as AND, OR, >, starts-with, and is-after.

Going back to our previous example, you can use the data key age to create a data key target that lets you serve ads only to audiences of a certain age (=) or age range (>=).

You can also incorporate multiple data key targets into one target. For instance, you can further restrict audiences by both age and gender, or by name or location.

It might help you to read our interface guide on Data Keys so you can see how data keys and data key targets are created using AdButler's UI.

Data key targeting can be used on its own or with other targeting methods to make your target audience as specific as needed.

In this guide, you will learn about:

1. Creating Data keys.
2. Passing Data keys via GET.
3. Passing Data keys via POST.
4. Creating Data key targets.
5. Data key target operators and options.

How to create Data keys

To create a Data Key, provide its name and type. name must be a string, while type must be one of the following: STRING, NUMBER, DATE, DATETIME, or TIME.

Example:

{
"name": "age",
"type": "NUMBER"
}

As their names suggest, each key type can hold only certain values, but the Data Key itself is actually a string. For example, in a Data Key target, the value of age is assigned as follows:

{"age" : {">" : "25"}}

How to pass Data keys via GET

Use the _abdk[] query parameter in your ad request to pass your Data Keys to AdButler.

Example:

https://ads.domain.com/adserve/;ID=171230;size=300x250;setID=373469;type=json;_abdk[bird]=duck;_abdk[bug]=ant;click=CLICK_MACRO_PLACEHOLDER

How to pass Data keys via POST

You can also pass Data Keys via POST. In this case, you will use the _abdk_json field.

Example:

POST https://ads.domain.com/adserve
{
"ID": 171230,
"size" : "300x250",
"setID": 373469,
"type" : "json",
"_abdk_json" : {
        "bird" : "duck",
        "bug" : "ant"
    }
}

How to create data key targets

As stated in the introduction, before creating a data key target, you must first create the Data key(s) that you will reference in the target.

To create a data key target, provide its name (optional) and target. The latter is a JSON blob formatted as a Lisp S-expression. This is where you enter comparative values for your data keys and add the logic operators and options that will flesh out your targeting criteria.

Let's say you want to target male audiences over the age of 25. You create data keys age and gender. You can then write your data key target as

["AND",
        {"age" : {">" : "25"}},
        {"gender" : {"=" : "male"}}
    ]

When passing the data key target to AdButler, the JSON must be in a string, i.e. they must have escape characters.

{
"name": "Data key target 1",
"target": "[\"AND\",
        {\"age\" : {\">\" : \"25\"}},
        {\"gender\" : {\"=\" : \"male\"}}
    ],"
}

As shown in the example, a data key target has a logical grouping that consists of an array beginning in either AND or OR, followed by a comma-separated list of data key comparators.

Just like in the AdButler interface, you can also make data key targets that consist of multiple logical groupings.

Going back to the previous example, let's say your target can now be male audiences over the age of 25, or audiences over the age of 50 who are either female and own iPhones, or living in the United States. You then create a third data key device and a fourth data key location. You can then expand your data key target as

{
"name": "Data key target 1",
"target": "[\"OR\",
    [\"AND\",
        {\"age\" : {\">\" : \"25\"}},
        {\"gender\" : {\"=\" : \"male\"}}
    ],
    ["\AND\", 
        {\"age\" : {\">\" : \"50\"}},
        [\"OR\", 
            [\"AND\", 
                {\"gender\" : {\"=\" : \"female\"}},
                {\"device\" : {\"=\" : \"iphone\"}}
            ],
            {\"location\": {\"=\" : \"USA\"}}
        ]
     ]
  ]"
}

Data key target logic operators and options

Logical Grouping

STRING Operators

NUMBER Operators

Date and Time Operators

There are three date and time formats:

1. Date: mm/dd/YYYY - 2 digit month, 2 digit day, and 4 digit year IE May 11, 2023 is 05/11/2023
2. Time: gg:ii AP - 2 digit hour in 12 hour format, 2 digit minute and AM or PM, IE 09:30 AM or 11:30 PM
3. DateTime: mm/dd/YYYY gg:ii AP - a combination of both Date and Time IE 05/11/2023 09:30 AM

DATE Operators

If we assume the request is passed the following:

{
...
    "_abdk_json" : {
        "gender" : "male",
        "registration-date" : "01/17/2023"
    },
...
}

TIME Operators

If we assume the request is passed the following:

{
...
    "_abdk_json" : {
        "gender" : "male",
        "registration-time" : "11:30 AM"
    },
...
}

DATETIME Operators

If we assume the request is passed the following:

{
...
    "_abdk_json" : {
        "gender" : "male",
        "registration-datetime" : "01/17/2023 12::00 PM"
    },
...
}

ARRAY Operators

Use ARRAY operators when the _abdk or _abdk_json data key sent with the request is an array. There are 2 groups of operators you can use depending on what is going into the data key target: either a single string in the target or a comma delimited list of strings in the target.

Value in data key target is a single string

If we assume the request is passed the following:

{
...
    "_abdk_json" : {
        "gender" : "male",
        "fruits" : ["apple", "plum", "orange"]
    },
...
}

Value in data key target is a comma delimited list of strings

If we assume the request is passed the following:

{
...
    "_abdk_json" : {
        "gender" : "male",
        "fruits" : ["apple", "orange"]
    },
...
}