Integration process

This document includes the necessary information for supply partners to review, plan, and execute a new OpenRTB integration, or migrate from a custom SSP protocol integration to OpenRTB standard, in a self-paced fashion.

Prerequisite checklist

1. Contact your account manager (or open a ticket with our support team) to confirm the following information:
   • Member seat ID and if not requested yet, new member seat creation and API login credentials for Xandr's API.
   • Endpoints for incoming bid requests, and if not requested yet, new endpoint creation on Xandr.
2. Review the documentation outlined below and discuss any open questions:
   • OpenRTB Specs
   • FAQ - Integration Process
   • Object Hierarchy
   • Inventory Mapping
   • User Sync
   • Ads.txt/App-Ads.txt
   • Deals (If applicable)

• Engagement is expected to take 3-4 weeks.
• The client must fully review the Prerequisite Checklist (this document) - and gather all the information prior to following the steps below.

Step 1: Self-guided API/UI training and creation of publisher and placement objects (estimated time: 7 - 10 days)

1. Review Xandr Object Hierarchy and API/UI documentation.

2. Provision the objects that you will need for initial testing, either via or the API. See API Documentation for more details.

3. Create sell-side objects to synchronize inventories (at least the ones are needed for initial functional testing) via UI/API

   • Review Xandr Object Hierarchy: Member → Publisher → Placement Group → Placement
   • Create a publisher and a placement for the test
     • Within each object, the code value must be populated with the external identifier the SSP will pass in the bid request.
   • Related API documentation
     • Member Service
     • Publisher Service
     • Placement Group Service (Site Service)
     • Placement Service

4. Setup a Default placement on the publisher and member level. (in case we cannot identify inventory from the bid request, the impression will be logged into that default placement.)

5. Use the code field to map your bid requests to your publishers and placements. For more details and examples, read the Integration FAQ.

   Note

   In order to provide transparency to our buyers and improve our optimization, we require our partners to break out their inventory by publisher. For more information regarding our inventory structure standards please visit our wiki page Use the API to Synchronize Your Inventory Structure.

6. Use the Publisher Service to create publishers that are mapped to your inventory.

   Note

   • The code field is required for all external sellers at both the publisher and placement levels and is highly recommended for all other sellers to ensure that your inventory is as granular as possible so that it can be investigated accurately for quality issues, and specifically for domain detectability. This step will help you to split your inventory into highly detectable and less detectable tags, allowing you to isolate the impacts of non-detectable domains on the rest of your inventory's viability.
   • In order to create or edit publishers in or the API, you have to declare the Inventory Relationship. The requested information is basic business information about how the inventory is accessed and will be used to support Xandr's inventory quality efforts. For a complete list of fields and their usage requirements, refer to the Publisher Service documentation.

7. User Sync Setup
   Store the user mapping table between Xandr's and yours by using the getUID service. Learn details from User ID Mapping.

Step 2: OpenRTB bid request endpoint testing (estimated time: 3 - 4 days)

Xandr supports the OpenRTB 2.4 protocolfor receiving all media type impressions. Follow the OpenRTB 2.4 specification from IAB.

Use the endpoints below to send server-to-server OpenRTB bid requests to Xandr:

• http://MEMBER_ALIAS-useast..com/openrtb2member_id=MEMBER_ID&test=1
• http://MEMBER_ALIAS-uswest..com/openrtb2member_id=MEMBER_ID&test=1
• http://MEMBER_ALIAS-emea..com/openrtb2?member_id=MEMBER_ID&test=1
• http://MEMBER_ALIAS-apac..com/openrtb2?member_id=MEMBER_ID&test=1

Feel free to use the bid request examples from the page Incoming Bid Request from SSPs and adjust the code fields accordingly to match your publisher and placement inventory mapping.

You must use the "test=1" query string parameter on your calls to identify a test impression. It will not be logged in reporting.

Step 3: Manual tests

1. Provide a bid request sample to Xandr.

2. Setup a test placement on Xandr platform and make sure the inventory is mapped correctly.

3. Provide a sample creative that meets all the requirements of the test placement.

4. Setup Ad Quality rule that only allows Xandr Test Buyer to buy Impressions on the Test Placement.

5. Remove "&test=1" from the endpoint query string when the test starts.

   Note

   If you do not remove "&test=1", imps will not be logged on Xandr side.

6. Fire the traffic manually from the test placement to confirm the receipt of a bid response, the creative served, and impressions logged on your side.

7. Xandr will run a delivery test from a dedicated buy-side member seat and notify you of any discrepancies before scaling your inventory further.

8. Xandr will validate your OpenRTB bid requests and notify you in case the format needs to be corrected.  

Step 4: Programmatic functional test (live traffic)

1. Open up a small but substantial portion of traffic to Xandr on the established endpoint (at a minimum of several thousand imps per day). Xandr will confirm the volume of traffic being sent in and verify that impressions are flowing in through our reporting and they align with your internal reporting.
2. Run the test for a day or so and compare numbers to ensure the discrepancy between your reporting and Xandr reporting is acceptable.

Step 5: Go live

1. Map all your inventories on Xandr platform before going live with 100% traffic.
2. After finishing the inventory mapping, ramp up traffic and remove filters that may be imposed during testing such as country pre-targeting, device pre-targeting and bid volume throttling.

Step 6: Completion/Follow up (estimated time: 2 - 3 days)

We encourage a gradual traffic ramp-up where distinct portions of your inventory are being sent to Xandr. General recommendation is to start with a small chunk of traffic (100-200 QPS).

Notify your Xandr contact about the completion of the self-paced integration/migration; your contact will initiate the final OpenRTB requirement validation tests and provide you with final results and feedback.