Your First Bid Interceptor

This tutorial will take you through the process of writing and testing your first bid interceptor.

The interceptor we create will implement some of the simplest bidding logic possible: deciding to bid on every impression, and choosing a random price for that. (Not likely a very profitable strategy!)

Previous step

For instructions on prepping your development environment and retrieving the Open Bidder SDK source, see Before you Begin. Once this step is completed, you will be ready to write your first bid interceptor.

Create your own Maven project

First we'll create our own Maven project that will contain the bid interceptor. Create the project with the Maven command:

mvn archetype:generate -DgroupId=com.example \
-DartifactId=random-bid-interceptor \
-DarchetypeArtifactId=maven-archetype-quickstart

If you have not previously used Maven, it will be helpful to take the time to read Maven's Getting Started guide to get an idea for your project's layout and how to build with Maven.

Next, we'll add the dependency to some modules, in particular the open-bidder-api module we previously installed in our local Maven repository. Open your newly created project's pom.xml file, located in the root of the Maven project, in your editor of choice and update the properties and dependencies sections to the following:

<properties>
  <openBidderVersion><!-- FILL THIS IN --></openBidderVersion>
</properties>
<dependencies>
  <dependency>
    <groupId>com.google.openbidder</groupId>
    <artifactId>open-bidder-api</artifactId>
    <version>${openBidderVersion}</version>
  </dependency>
  <dependency>
    <groupId>com.google.openbidder</groupId>
    <artifactId>open-bidder-api</artifactId>
    <version>${openBidderVersion}</version>
    <type>test-jar</type>
    <scope>test</scope>
  </dependency>
  <dependency>
    <groupId>junit</groupId>
    <artifactId>junit</artifactId>
    <version>4.12</version>
    <scope>test</scope>
  </dependency>
</dependencies>

You must set the openBidderVersion property to the most recent version. You can find the most recent version in the release notes in the code repository, or check the version in the project's pom.xml.

To ensure that your project has been configured correctly, run the following from the top level of your project:

mvn verify

If there aren't any errors, we're ready to write the interceptor.

Write the bid interceptor

Open the project in your IDE or editor of choice. Feel free to delete any stub classes added by Maven when it created the project. Create the class RandomBidInterceptor and have it implement the BidInterceptor interface, following this structure:

public class RandomBidInterceptor implements BidInterceptor {
  @Override public void execute(InterceptorChain<BidRequest, BidResponse> chain) {
    // Create bids -- FILL ME IN
    // Proceed down the chain -- FILL ME IN
  }
}

Now let's write the execute() method so it creates the bids and dispatches to other interceptors with chain.proceed(). The order is significant: if you first create bids and then dispatch, any interceptors put later in the chain can see (and potentially update) bids created by earlier interceptors. Bidding logic before the dispatch characterizes a "preprocessing interceptor"; the opposite would be a "postprocessing interceptor", and of course you could have interceptors that perform some actions before dispatching the chain and others after. The BidRequest and BidResponse objects can be accessed from the InterceptorChain; both have accessors to a wrapped openRtb property you can manipulate directly, or you may prefer helper methods that facilitate common operations such as listing impressions of a specific type. Try completing the interceptor yourself; the solution can be found by expanding the section below.

Interceptor unit test

Now we're ready to do some testing. To start, create a class called RandomBidInterceptorTest. Below is a stub with one test:

public class RandomBidInterceptorTest {
  @Test public void testInterceptor() {
    // Create a bid request with an impression -- FILL ME IN.
    // Execute the interceptor using BiddingTestUtil#executeInterceptor -- FILL ME IN.
    // Check that response has a bid with expected price -- FILL ME IN.
  }
}

Now try writing the tests for your interceptor. Open Bidder's test-jar modules provide many utilities for testing; for this exercise, look at NoopInterceptorChain, which makes easy to test isolated interceptors (for a chain of several interceptors you would need a controller, as shown in more advanced tutorials). You may also want to use test-specific builders such as TestBidRequestBuilder to easily create a request for unit tests.

Once you've written the test code, run the project's tests with Maven:

mvn test

If all goes well, your results should include a line like this:

Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

Congratulations! You have written a bid interceptor.

Next steps

Now that we've written a bid interceptor, we can create a bidder on Google Compute Engine to execute it. Start with Creating App Engine Project and Application.

After you get bidding running successfully, you can iterate with adding support for impression and click tracking.

Send feedback about...

Open Bidder (Beta)