Integrate a BidderThis page describes how to integrate a bidder with Xandr. It begins with an overview of the different "layers" of the integration, and ends with a worked example (using actual API calls) of a simple integration that will get you up and running quickly in our testing environment. It also provides links to more detailed information elsewhere on our wiki.
At a high level, there are two "layers" of the system we need to be concerned with during bidder setup:
- Real-Time Layer (RTB): This is the heart of the action, where your bidder will participate in the real-time auction.
- Configuration Layer (API): This is where you will configure your bidder' s "business logic" so it can bid on impressions; in other words, filtering out unwanted impressions, setting up users, adding the creatives your members want to serve, etc.
The diagram below shows the high-level architecture of a bidder and the various requests and responses it receives and sends.
In the diagram below, click on the request and response bubbles in the Real-Time Layer and the names of API services (such as the Bidder Profile) in the Configuration Layer to open the corresponding documentation in a new browser tab.
How to Set Up Your Bidder
In this section we'll walk through the entire process of setting up a bidder on the platform. We'll begin by making the API calls necessary to hook up the pipes.
Authenticate with the API
Before we can do anything else, we have to log in.
For more detailed information about authenticating via our API, see the Authentication Service.
Post to the test environment to authenticate:
View your Bidder Object
The bidder object represents your bidder in our system. As such, it has a lot of fields that you can use to configure how your bidder interacts with our platform. Think of it as the central "hook" on which you'll hang much of the rest of your configuration. A bidder object should already have been created for you by your Xandr representative.
In the example below, we make a
GET call to view the bidder object, but we don't explain any of its details. For more detailed information about the bidder object, see the Bidder Service.
Update your Bidder object to receive unaudited inventory
In order to avoid drastically limiting the number of bid requests sent to your bidder, you need to set the
send_unaudited field on the bidder object to
true using the Bidder Service. This is true even though there is a
non_audited_url_action (which defaults to
"include") on the Legacy Bidder Profile Service.
View your Member Object
You need to have at least one member that buys through your bidder. You should have had a member created for you by your Xandr representative as part of the onboarding process. The member is where you will configure much of the "business logic" such as user segments, creatives, etc.
Create a Segment for your Member and add yourself to it
In this step, we'll create a segment and put ourselves in it to test the integration. Later on, we'll target this segment with the Bidder Profile during testing. This will serve several purposes:
- Test that the "pipes" are open
- Test that our ability to set up the profile's targeting works as expected
- Allow us to send our bidder a very small amount of traffic (since presumably only a few users will be added to the testing segment)
Add yourself to the segment by visiting this URL:
Create a Bidder Profile
In this step, we'll create a bidder profile that only allows impressions shown to users in our test segment (created in the last step) to be sent in bid requests.
In the example below, the targeting breaks down like this:
- We include (that is, target) the testing segment ID we just created.
- Although we set the passthrough percent to 0, we should still receive bid requests for users in our members' segments. For details, see the docs for
passthrough_percenton the Legacy Bidder Profile Service.
- The segment boolean operator is set to "or" in case we'd like to add more testing segments later.
- Finally, we target a few common mobile sizes just for fun.
Associate your Profile with your Bidder Object
The profile we've just configured can't take effect until it's associated with your bidder object. Since we're doing integration testing, we'll set the profile we just created as the parent profile.
Add a Test Creative
In this step, we'll add a creative to serve to the users in our testing segment. After we upload this creative, we'll need to set up our bidder to respond to a Bid Request in the testing environment with a Bid Response that includes this creative when you bid on the test TinyTags provided to you by your Xandr representative. This will test that our profile (along with the rest of our integration) is working as expected.
This simple example creative uses very few of the creative configuration options we support. For more detailed information about the many types of creative configurations, see the Creative Service.
For more information on using the Client Testing environment to test creatives, see Using the Client Testing environment below.
Add a Bidder Instance
The bidder instance object represents a particular bidder server running in the data center. In this example, we set the data center ID to (NYM), since that's where the client testing environment lives.
For more information about configuring a bidder instance, see the Bidder Instance Service
Test the Integration
First, you should test the integration using our Client Testing environment, explained below. If this works as expected, you should be able to pull a debug log for the TinyTags provided to you by your Xandr contact as shown on our Troubleshooting page. If all is well, you will be able to compare the debug logs with your bidder's own logging to make sure that the integration is working as expected.
If you are still not seeing the bid requests you expect:
- Double check your configuration against the instructions on this page.
- Check out our Troubleshooting documentation
Using the Client Testing environment
The Client Testing environment provides a version of the Impbus and Impbus API that you can use to test your workflows and API implementations without incurring spend (as you would in production). The Client Testing environment's codebase and data are now updated every month. This means your testing environment will never be more than 30 days (and often less) behind the version of Xandr code that is running in Production. In addition, all Production data will also automatically be copied over to the Client Testing environment (including your member accounts and credentials) each month. This will allow far more robust testing against the latest features.
For reference, here are the endpoints for the Production and new Client Testing environments.
|Product||Product endpoint||Client Testing endpoint|
Read more about the Client Testing Environment.