Add a Bidder Adapter to Prebid Server

This page describes how to write the code for a bidder adapter that integrates with Prebid Server.

Step 1. Get the source code and build the API docs

When writing your adapter it may be useful to refer to:

  • Autogenerated API documentation
  • Existing bidder adapter code

For autogenerated API documentation using godoc, run the following commands:

$ git clone https://github.com/prebid/prebid-server
$ cd prebid-server/
$ godoc ./adapters/

To read the source code of the existing adapters, see the prebid-server repo (either on GitHub or your own machine, of course).

Step 2. Build Prebid Server and run the tests

To build Prebid Server, see the instructions in the README.

As of this writing, when you run go test, you end up testing everything in the project. To test just the adapter code, run:

$ go test ./adapters/

If everything goes as planned, you should see something like:

ok  	github.com/prebid/prebid-server/adapters	0.098s

A failing test will look something like the following (I triggered this failure by changing the bidder code for the AppNexus adapter to an invalid value):

 --- FAIL: TestAppNexusBasicResponse (0.01s)
	appnexus_test.go:326: ParsePBSRequest returned invalid bidder
body {"account_id":"","tid":"","cache_markup":0,"sort_bids":0,"max_key_length":0,"secure":0,"timeout_millis":0,"ad_units":[{"code":"first-tag","is_top_frame":0,"sizes":[{"w":300,"h":250}],"bids":[{"bidder":"audienceNetwork","bid_id":"random-id-from-pbjs-0","params":{"placementId":"987654321_999998888"}}],"config_id":""},{"code":"second-tag","is_top_frame":0,"sizes":[{"w":300,"h":250}],"bids":[{"bidder":"audienceNetwork","bid_id":"random-id-from-pbjs-1","params":{"placementId":"987654321_66775544"}}],"config_id":""}],"is_debug":false,"app":null,"device":null,"Start":"0001-01-01T00:00:00Z"}

Step 3. Understand the adapter interface

Now that you have the godoc output (and have adapter.go available to read), you can see that the interface you need to implement is:

Name Description
Name Returns the code name of the adapter, a string – must match the bidder code in Prebid.js
FamilyName Returns a string used to build the OpenRTB bid request; used for cookie management
GetUsersyncInfo Returns user sync info for this bidder. For more information about user syncing, see What is Cookie Syncing and How Does it Work?
SkipNoCookies Returns a boolean value that answers: Should this adapter be called if there is no user ID on the impression?
Call Takes the request from the client and produces a bid request that is then sent to the adapter’s external server.

Other things to keep in mind include:

  • Your adapter must be in the adapters package
  • Your adapter’s constructor (e.g., NewYourBidderAdapter) needs to accept an HTTP adapter config that controls how it makes requests to your bidder

Step 4. Write code and tests

There’s enough variation among bidders that we can’t tell you exactly how to write the code. To see how it’s done, refer to the adapters in the repo, their tests, and the interface documentation.

The file naming conventions are:

  • yourbidder.go: implementation
  • yourbidder_test.go: tests

Step 5. Register your adapter with Prebid Server

Finally, in order for Prebid Server to integrate your adapter, it has to be added to the list of adapters in the implementation of setupExchanges.

Further Reading