The simplest form of auction is one where you do not provide any auction properties. When running such an auction, all ads you have added to Kleio are part of the auction, and a single winner is returned.

You can specify how many ads you want returned from the auction. A use case where you might want this is where you would like the top three search results to be ads.

The auction will return at most as many ads as you specified. The number of ads is restricted by the number of eligible ads in the system. If for example there are only 4 ads but you have specified 5, then at most 4 ads are returned.

Filters can be used to achieve quite sophisticated targeting.

Let's explain the capabilities using an example of wanting to promote products in the search results of an e-commerce shop:

You likely have invested quite some resources in attaining a high degree of relevance in your search results. We do not want to give up this relevancy when introducing sponsored products. As a result, we might want to limit the products that are candidates for being promoted to those that the search engine would naturally return for a given search query. In practice, this could mean that where we might normally request and show the top 20 results, we might now instead request the top 100 results from the search index, and feed these into Kleio. A filter to achieve this goal could look like this:

{
  "product_ids": [... top 100 product ids]
}

Additionally, we might have a wide range of ads for products we want to promote in Kleio. Some of these ads are for promoting products among the recommendations we offer users on the front page, whereas others are targeted at search. In a scenario like this, you could add the tag of search to the ads that should also be eligible for promotion in search.

Expanding on our previous filter, it would now look like this:

{
  "product_ids": [... top 100 product ids],
  "tags": ["search"]
}

In some cases using search relevancy as a means of determining which product to promote might be too restrictive. We might for example also want to promote related products that wouldn't naturally be returned by the search engine. If we were to tag these products with the )search keywords_ we would like them to appear on, we could use a second filter to expand the pool of ads eligible for the auction:

{
  "tags": ["search", "keyword:<search term>"]
}

(there is nothing magic about the keyword:-prefix here. You can use whatever format you want for your tags, but this approach is one we commonly see.).

Combining the two filters we end up with:

[
  {
    "product_ids": [... top 100 product ids],
    "tags": ["search"]
  },
  {
    "tags": ["search", "keyword:<search term>"]
  }
]

which will include all products in the top 100 list that have been enabled for search, as well as all products that have been tagged with the search term.

You can run multiple auctions as part of a single request.

This can come in handy if:

• you have multiple ad spots you want to fill and want to reduce the latency incurred by bundling them into a single request to Kleio
• you want model priority levels. For example, you want to show house ads if there are no regular ads to be shown

The response will contain the results for each auction in turn. The results are in the same order as the requests were made.

For example, if you wanted to model priority levels, you could create a request along the lines of:

[
  { ... request for priority level 1 ... },
  ...,
  { ... request for priority level N ... },
  { ... house ads ... }
]