AdButler's User DB is a great targeting option if you have access to your customers' data. A User DB is a set of attributes that are based on actual user information. Once you've uploaded and configured a user DB, you can create sets of targeting filters based on that database. A set of targeting filters is called an Audience.

Audiences look for your particular set of customers and other visitors with similar attributes, making them more likely to tailor and match ads to actual people.

It might help you to read our interface guide on User DB so you can see how User DBs and Audiences are created using AdButler's UI.

Audiences can be used on their own or with other targeting methods to make your target audience as specific as needed.

In this guide, you will learn about:

1. Creating User DBs.
2. Creating Audiences.
3. Passing Audiences via GET.
4. Passing Audiences via POST.
5. Passing Audiences via a tracking pixel.

How to create a User DB

User DBs are based on a CSV file that contains your customers' information.

1. Name the User DB and identify the id_field_name, which is the column in the CSV file that contains the primary identifier of your customers. The primary ID is important because it's what you will pass in your ad requests to implement Audience targeting.

Example

POST https://api.adbutler.com/v2/user-dbs

{
  "name": "customer_data",
  "id_field_name": "contact_email"
}

The response will contain the User DB's ID.

2. Upload the relevant CSV file, linking it to the User DB by adding the User DB ID to your request.

Example

POST https://api.adbutler.com/v2/user-dbs/10032/bulk-upload-replace

{
  "id": "10032",
  "file": "e8aBtMMxD/customer_data.csv"
}

3. Create user attributes. You do this by labeling each column in the CSV that you wish to use as a user attribute and identifying its attribute type ("number", "phone_number", "email", "text", "date_time", or "timestamp"). As with the CSV file, you must link these attributes to the User DB by adding the User DB ID to your request.

Example

POST https://api.adbutler.com/v2/user-dbs/10032/user-attributes

{
  "id": "contact_email",
  "label": "customer email",
  "type": "email"
}

How to create an Audience

An Audience let you filter targets by comparing the values of user attributes to your target values. Each Audience is based on a User DB, which you will reference by adding its ID in your request.

1. Name the Audience.
2. Identify the user attributes that will be used, then use operators and operands in each attribute to specify your target.

Example

POST https://api.adbutler.com/v2/user-dbs/10032/audiences

{
  "name": "Adult Males",
  "attributes": {
    "gender": {
      "operator": "=",
      "operand": "male"
    },
    "age": {
      "operator": ">=",
      "operand": "18"
    }
  }
}

Here are the operators that can be used per attribute type:

How to pass Audiences via GET

Add udb_uid to your request, with its value being the primary ID of the user whose attributes you want to use in targeting.

Example:

https://ads.domain.com/adserve/;ID=171230;size=300x250;setID=373469;type=json;udb_uid=123456;click=CLICK_MACRO_PLACEHOLDER

How to pass Audiences via POST

You can also implement Audience targeting via POST:

Example:

POST https://ads.domain.com/adserve
{
"ID": 171230,
"size" : "300x250",
"setID": 373469,
"type" : "json",
"udb_uid" : "123456"
}

How to pass Audiences via a tracking pixel

Alternatively, you can manually sync users using a tracking pixel, which will add a cookie that marks future ad requests to use the same primary ID for the User DB you're going to invoke.

Example:

<img src="https://servedbyadbutler.com/adserve/usync?id=108678&db=10000&uid=123456"/>

Where id is your AdButler ID, udb is the User DB ID, and uid is the primary ID of the user whose attributes you want to target (same as udb_uid in GET and POST requests).

Ideally, you would place the pixel on the page where users are taken after they log in so that you can retrieve their primary ID. However you decide to implement this, you don't have to include this pixel on every ad request. Having it once per page is enough.