Getting Started Guide

Initial Reading

Start with these overviews of our taxonomy and terminology:

Next, we recommend making a few test requests against the APIs using our quickstart guides:

Understanding Inventory

Inventory is the Kevel term for the properties (sites and apps) where your ads appear. Most of these are pre-created for you.

Understanding Campaign Hierarchy

Campaign covers who is advertising, how they target, and what the ad looks like. It is organized into four levels: Advertisers --> Campaigns --> Flights --> Ads.

Building The Ad Unit

Before you can serve an ad, you need to configure your Custom Ad Unit. You can do this in the UI or through the API.

You can also use our Creative Templates option. Speak to your Kevel rep to learn more.

For more on ads, see:

📘
Note
In Kevel terminology, a 'creative' holds the details of what gets shown, such as the image, the source URL, and metadata. An 'ad' is a creative that is tied to a Flight and therefore eligible to serve, which means targeting attaches to an 'ad' rather than a 'creative'. We separate the two so that the same 'creative' can be used across multiple Flights.

Understanding Priorities

Priorities are the business rules that decide which ads take precedence over others. The chart below shows how this works:

Priorities run from 1 (the highest) to 100 (the lowest). Kevel gives you four by default, and you can add up to 96 more:

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

Here are a few ways to structure them:

Scenario	Advice
You want to sell every available impression to one 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 high-CPM advertisers eligible first, then unfilled slots opened to lower-CPM ones	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 when no advertisers are available for a given ad slot	Use default "House" (#20), alongside higher Priorities.

Understanding Business Logic

With Kevel, you can sell, pace, and cap by any metric, including:

Metric	Examples
Flat rate (fixed amount)	$100K over 30 days.
CPM (cost per thousand impressions)	$5.00 CPMs for 100K impressions.
CPC (cost per click)	$1.00 CPC for 10K clicks.
CPA (cost per action)	$20 CPA for 500 actions. Here, "actions" can be any event you choose.

You can also optimize revenue through bidding strategies:

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.	Best when you need to guarantee a set number of impressions, clicks, spend, and so on.
Auctions (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.	Best when you want to maximize revenue. Because every ad is an auction, it is difficult to guarantee an advertiser how many impressions or clicks will be seen.
2nd 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.	Maximizes revenue while selling the ad at "true market value". Advertisers generally pay less and see better performance, which increases stickiness.
Relevancy Score	Dunkin Donuts and Starbucks have the same bid, but Starbucks's relevancy score is higher and is selected.	Best when you want the Ad Decision Engine to weigh a relevance metric that you create and send. Useful for spotting ads that users are less likely to want.

You set up these rules through a combination of Priorities / Waterfall and Flights. Refer to our documents for more details.

Tracking Custom Events

Kevel lets you track impressions, clicks, actions, and any custom metric. For custom metrics, you request custom event URLs and then ping Kevel server-side when the events happen, or add the pixel endpoint to the page.

For each Event ID you request, you'll receive separate URLs to hit.

Targeting Options

Robust targeting is how you justify higher ad rates and offer better ad experiences to your users. The most relevant options are:

UserDB Targeting

One of the most powerful tools available to you is UserDB, your 1st party data store for activating user-level targeting.

If you'd like to test demographic, interest, and additional user-level targeting, start here:

📘
Note
Kevel does not provide user-level data. You need to collect it and send it to UserDB. From there, Kevel does the heavy lifting of using that data to determine whether an ad is eligible to be shown.

What to Send in Decision API Request (For Beginners)

The fields below are the most important ones to pass in the Decision API Request. Refer here for a full list of all parameters and example JSON requests.

Arguments

Property	Description
`placements` (object)	The details of the placement (ad slot). Required.
`user` (object)	The UserKey for UserDB.
`time` (string)	The UNIX epoch timestamp. For time-of-day targeting.
`ip` (string)	IP Address. For location targeting.
`keywords` (array)	Keywords for Keyword Targeting.

Placement Arguments

Property	Description
`divName` (string)	A unique name for the placement, defined by you. This field is required.
`networkId` (integer)	Your numeric network id. This field is required.
`siteId` (integer)	The numeric site id. The "site" will likely be Web, iOS, or Android. This field is required.
`adTypes` (array)	The adType id for your native ad unit. This field is required.
`eventIds` (array)	Requests a URL for a special event. See here for more info.
`properties` (object)	A hash of key/value pairs used for Custom Targeting.

Three of those values are IDs you'll need to look up first.

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:

If it's a pre-created ad type, it's listed here
If you create it with the Ad Types API, it's in the response as id
You can send a request to the List Ad Types API to get it
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 returns many fields, some more relevant than others. The more salient ones are:

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, and so on. You can leave it out if you don't need it.
`impressionUrl`	URL that records impressions. Needs to be called via browser or pinged server-side.
`customData`	This is the `metadata` field. Use it if there's additional info tied to the ad that you want to insert into your Content Management System (CMS).
`events`	The URLs for any custom events you requested, broken down by `id`. These 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.

Using Management APIs

You can build your own ad server with a combination of the Decision API and the Kevel UI, but many clients prefer the Management APIs to automate the creation, updating, and 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. Additional reading:

Using The Reporting API

The Kevel Reporting API offers multiple ways to pull data into your system, including scheduled reports and real-time data.