## Initial Reading  
Here are some overviews about our taxonomy and terminology:

* [Kevel Glossary](https://dev.kevel.co/v1.0/docs/kevel-glossary)
* [Intro to Ad Tech](https://www.kevel.com/blog/advertising-terms/)
* [Ad Decision Engine Overview](https://dev.kevel.co/v1.0/docs/delivery-basics)
* [Campaigns Overview](https://dev.kevel.co/v1.0/docs/overview)
* [Inventory Overview](https://dev.kevel.co/v1.0/docs/inventory-overview)
* [Ad Servers: The Definitive Guide](/content/blog/what-is-an-ad-server/index.html)

Second, we recommend doing some test requests on the APIs with our quickstart guides:

* [Decision API Quickstart](https://dev.kevel.co/v1.0/docs/native-ads-api-quickstart)
* [Decision API (Advanced)](https://dev.kevel.co/v1.0/docs/native-ads-api-advanced)
* [Management API Tutorial](https://dev.kevel.co/v1.0/docs/management-api-tutorial)
* [UserDB Tutorial](https://dev.kevel.co/v1.0/docs/userdb-tutorial)

## Understanding Inventory  
[Inventory](https://dev.kevel.co/v1.0/docs/inventory-overview) is the Kevel term for what properties (sites/apps) the ad will appear on. Most of these are pre-created for you.

## Understanding Campaign Hierarchy  
[Campaign](https://dev.kevel.co/v1.0/docs/overview) refers to information about who is advertising, what their targeting is, and what the ad looks like. It consists of four "levels": [Advertisers](https://dev.kevel.co/v1.0/docs/advertisers) -> [Campaigns](https://dev.kevel.co/v1.0/docs/campaigns) -> [Flights](https://dev.kevel.co/v1.0/docs/flights) -> [Ads](https://dev.kevel.co/v1.0/docs/ads).

## Building The Ad Unit  
Before showing an ad, you'll have to configure your Custom Ad Unit. This can be done with the [UI](https://dev.kevel.co/v1.0/docs/ad-sizes#section-adding-custom-ad-sizes-with-ui) or [API](https://dev.kevel.co/v1.0/reference/ad-type).

Additionally, you could use our [Creative Templates](https://dev.kevel.co/v1.0/docs/creative-templates) option. Speak to your Kevel rep to learn more.

Some additional information about ads are:

* [Creatives](https://dev.kevel.co/docs/creatives)
* [Ads](https://dev.kevel.co/docs/ads)
* [Create Creative API Endpoint](https://dev.kevel.co/v1.0/reference/creative#creative-creative)
* [Create Ads API Endpoint](https://dev.kevel.co/v1.0/reference/creative-flight-map)
* [Ad Sizes / Types](https://dev.kevel.co/v1.0/docs/ad-sizes)

> 📘  
> ### Note  
> In Kevel terminology, 'creative' refers to information about what's being shown, such as the image, the source URL, and metadata. 'Ad' refers to a creative that's tied to a Flight and now eligible to serve (targeting is thus tied to an 'ad' not a 'creative'). We break it down because you could have the same 'creative' across multiple Flights.

## Understanding Priorities  
[Priorities](https://dev.kevel.co/v1.0/docs/priorities) are the business rules for determining what ads have precedence over others. For instance, see the below chart:

The default priorities are:

| Priority Name | Priority Number |
| --- | --- |
| Sponsorship | 1 |
| Premium | 5 |
| Networks | 10 |
| House | 20 |

1 is the highest priority; 100 is the lowest. You can add up to 96 more beyond the defaults.

Some ideas around how to structure priorities are:

| Scenario | Advice |
| --- | --- |
| You want to sell every available impression to an advertiser | Use default "Sponsorship" (#1) for that Advertiser's Flight. |
| You want all advertisers to bid on each ad slot | Use default "Premium" (#5) for all those advertisers. They are all equally eligible. |
| You want to have high-CPM advertisers eligible for slots, but if those aren't all filled, you'll open it up to lower CPM advertisers | Use default "Premium" (#5) for high CPMs. Create a new Priority (say, "Remnant"), with Priority of 8, for the low CPMs. |
| You want to show house ads if there are no advertisers for a given ad slot | Use default "House" (#20), alongside higher Priorities. |

## Understanding Business Logic  
With Kevel, you can [sell](https://dev.kevel.co/docs/sales-models), [pace](https://dev.kevel.co/docs/ad-pacing-goals), and [cap](https://dev.kevel.co/docs/ad-capping) by any metric, including:

| Metric | Examples |
| --- | --- |
| Flat rate (fixed amount) | $100K over 30 days. |
| CPM<br>_(cost per thousand impressions)_ | $5.00 CPMs for 100K impressions. |
| CPC<br>_(cost per click)_ | $1.00 CPC for 10K clicks. |
| CPA<br>_(cost per action)_ | $20 CPA for 500 actions. Here, "actions' can be whatever event you want. |

Additionally, you can optimize revenue through [bidding strategies](https://dev.kevel.co/docs/delivery-basics#section-selection-methods):

| How Winner Is Selected | Example | Use Cases |
| --- | --- | --- |
| Lottery (proportional selection of eligible ads) | Both Dunkin Donuts and Starbucks are eligible to show an ad. The Ad Decision Engine picks Starbucks because it is under-pacing. | If you are focused on guaranteeing a certain number of impressions, clicks, spend, etc. |
| [Auctions](https://dev.kevel.co/docs/optimization) (highest bidder wins) | Both Dunkin Donuts (with a $20 CPM bid) and Starbucks (with a $10 CPM) are eligible to appear. Dunkin Donuts is picked because it has higher bid and pays $20. | If you want to maximize revenue. Since every ad is an auction, it is difficult to guarantee to the advertiser how many impressions/clicks will be seen. |
| [2nd Price Auctions](https://dev.kevel.co/docs/second-price-auctions) (highest bidder wins, pays $0.01 more than 2nd highest bidder) | Both Dunkin Donuts (with a $20 CPM bid) and Starbucks (with a $10 CPM) are eligible to appear. Dunkin Donuts is picked and pays $10.01. | This helps to maximize revenue while selling the ad at "true market value". Advertisers generally pay less, but it also provides better performance to the advertiser, increasing stickiness. |
| [Relevancy Score](https://dev.kevel.co/docs/relevancy-score) | Dunkin Donuts and Starbucks have the same bid, but Starbucks's relevancy score is higher and is selected. | If you'd like to incorporate a relevance metric (that you create and send) for the Ad Decision Engine. This can be useful for identifying ads that users may not like. |

You set up these rules by a combination of [Priorities / Waterfall](https://dev.kevel.co/v1.0/docs/priorities) and [Flights](https://dev.kevel.co/v1.0/docs/flights). Refer to our documents for more details.

## Tracking Custom Events  
Kevel enables you to track impressions, clicks, actions, and any [custom metric](https://dev.kevel.co/docs/custom-event-tracking). For the latter, you request custom event URLs and then ping Kevel server-side when they happen (or add the pixel endpoint to the page).

For each [Event ID](https://dev.kevel.co/docs/custom-event-tracking#section-event-id-mapping-named-events) you request, you'll receive separate URLs to hit.

## Targeting Options  
Robust targeting is how you can justify higher ad rates and offer better ad experiences to your users.

A list of the more relevant targeting options are:

* [Geo-Targeting](https://dev.kevel.co/v1.0/docs/geo-location)
* [Day & Hour Parting](https://dev.kevel.co/v1.0/docs/day-hour-parting)
* [Custom Targeting](https://dev.kevel.co/v1.0/docs/custom-targeting)
* [Frequency Capping](https://dev.kevel.co/v1.0/docs/frequency-capping-1)
* [User-Level Targeting](https://dev.kevel.co/v1.0/docs/user-level)
* [Keyword Targeting](https://dev.kevel.co/v1.0/docs/keyword-targeting)
* [Search Term Targeting](https://dev.kevel.co/v1.0/docs/search-term-targeting)
* [Category Targeting](https://dev.kevel.co/v1.0/docs/category)

## UserDB Targeting  
One of the most powerful tools available to you is [UserDB](https://dev.kevel.co/docs/userdb-1), your 1st party data store for user level targeting activation.

For information on UserDB, you can visit:

* [UserDB](https://dev.kevel.co/docs/userdb-1)
* [UserDB Tutorial (Interests)](https://dev.kevel.co/v1.0/docs/userdb-tutorial)
* [User-Level Targeting](https://dev.kevel.co/v1.0/docs/user-level)

If you'd like to test out demographic, interest, and additional user-level targeting, check out these docs.

> 📘  
> ### Note  
> Please note: Kevel does not provide user-level data. You need to be collecting that and sending it to UserDB. Kevel will do the heavy lifting of using that data to determine if an ad is eligible to be shown.

## What to Send in Decision API Request (For Beginners)  
Below looks at the most important fields to pass in the Decision API Request. Refer [here](https://dev.kevel.co/v1.0/reference/request) for a full list of all parameters and example JSON requests.

**Arguments**

| Property | Description |
| --- | --- |
| `placements`<br>(object) | Describes more details about the placement (ad slot). Required. |
| `user`<br>(object) | The UserKey for UserDB. |
| `time`<br>(string) | The UNIX epoch timestamp. For time-of-day targeting. |
| `ip`<br>(string) | IP Address. For location targeting. |
| `keywords`<br>(array) | Keywords for [Keyword Targeting](https://dev.kevel.co/v1.0/docs/keyword-targeting). |

**Placement Arguments**

| Property | Description |
| --- | --- |
| `divName`<br>(string) | A unique name for the placement defined by you. This field is required. |
| `networkId`<br>(integer) | Your numeric network id. This field is required. |
| `siteId`<br>(integer) | The numeric site id. The "site" will likely be Web, iOS, or Android. This field is required. |
| `adTypes`<br>(array) | The adType id for your native ad unit. This field is required. |
| `eventIds`<br>(array) | Requests a URL for a special event. See [here for more info](https://dev.kevel.co/v1.0/docs/custom-event-tracking). |
| `properties`<br>(object) | A hash of key/value pairs used for [Custom Targeting](http://dev.kevel.co/docs/custom-targeting). |

**To get`networkId`** : in the UI, click the info icon ("i" in a circle) in the far upper right.

**To get`siteId`** : in the UI, go to Inventory --> Sites --> the ID is to the right of the Site

**To get the`adTypes` id**, you have a few options:

1. If it's a pre-created ad type, it's listed [here](https://dev.kevel.co/v1.0/docs/ad-sizes)
2. If you create with the [Ad Types API](https://dev.kevel.co/v1.0/reference/ad-type#create-ad-types), it's in the response as `id`
3. You can send a request to the [List Ad Types API](https://dev.kevel.co/v1.0/reference/ad-type#list-ad-types) to get it
4. You can also go to UI --> Inventory --> Ad Sizes --> the ID is to the right of the Name/Width/Height

## Most Relevant Parameters in Decision API Response  
The [Decision API Response](https://dev.kevel.co/v1.0/reference/response) will return many fields, some more relevant than others. Below looks at the more salient fields:

| Property | Notes |
| --- | --- |
| `imageURL` | The URL of the hosted Kevel image. |
| `clickURL` | URL for the click event, which could be an outside link, an "expand the profile" click, etc. You don't need it if you don't want. |
| `impressionURL` | URL to record impressions. Needs to be called via browser or pinged server-side. |
| `customData` | This is the `metadata` field. Use this if there's additional info tied to the ad you want to insert into your Content Management System (CMS). |
| `events` | The URLs for any custom events you requested, broken down by `id`. Can be pinged server-side. |

You'll want to parse this information and insert it into your CMS to create a fully integrated native ad.

## Parsing Metadata  
When setting up an ad, you can also insert data (in JSON format) into the [metadata](https://dev.kevel.co/docs/creatives#section-metadata-field) field.

Anything you put here will be returned in the Decision API JSON response. So, when you get the API Response, you can parse this field and insert the information into the ad. Examples include call-to-action, location information, any custom text, etc.

JSON

```json
{
  "headline": "Test Headline",
  "cta": "Download Here"
}
```

You may also use [Macros](https://dev.kevel.co/docs/macrostokens) within metadata, as shown in the below example. See [this link](https://dev.kevel.co/docs/macrostokens) for a complete list of available macros.

JSON

```json
{
	"ad": "{{ad.id}}",
	"flight": "{{ad.flight.id}}",
	"campaign": "{{ad.flight.campaignId}}"
}
```

## Using Management APIs  
While you can build your own ad server with a combination of the Decision API and the Kevel UI, many clients like using the Management APIs to automate the creation/updating/deleting of Campaigns, Flights, Ads, Priorities, and more.

This is especially useful if you are building a self-serve dashboard for internal users or external advertisers.

For next steps, try the [Management API Tutorial](https://dev.kevel.co/v1.0/docs/management-api-tutorial). Some additional reading material include:

1. [Campaign API Overview](https://dev.kevel.co/v1.0/reference/campaign-api-overview)
2. [Inventory API Overview](https://dev.kevel.co/v1.0/reference/inventory-api-overview)
3. [User Management API Overview](https://dev.kevel.co/v1.0/reference/log-in-endpoints)

## Using The Reporting API  
The [Kevel Reporting API](https://dev.kevel.co/v1.0/reference/reporting-api-overview) offers multiple ways to pull data into your system, including [scheduled reports](https://dev.kevel.co/v1.0/reference/scheduled-reports) and [real-time data](https://dev.kevel.co/v1.0/reference/real-time-reporting-api).

Updated 10 months ago