Link Search Menu Expand Document

PDF

Prebid SDK Integration

Apollo

Publisher

Last updated on May 13, 2021


The Prebid Server screen is where you perform a Prebid SDK Integration. Follow the sections in their respective order to complete the integration.


on this page


Overview

The OpenX Apollo Server is fully compatible with the open-source Prebid Mobile SDK. All information and integration guides hosted on Prebid.org are relevant to complete the integration with OpenX Apollo. Prior to starting the integration process, you should get familiar with the Prebid Flow.

In this flow:

  1. Prebid SDK sends the bid request to the OpenX Apollo Server.
  2. OpenX Apollo Server runs the header bidding auction among preconfigured demand partners.
  3. OpenX Apollo Server responds with the winning bid that contains targeting keywords.
  4. Prebid SDK sets up the targeting keywords of the winning bid into the ad unit of the Primary Ad Server SDK.
  5. Primary Ad Server SDK sends the ad request to the Primary Ad Server.
  6. Primary Ad Server responds with a chain of creatives.
  7. Primary Ad Server SDK loads the ad with Prebid Universal Creative into the ad view.
  8. Prebid Universal Creative loads the winning bid from the Prebid Cache and renders it.

The Prebid Mobile SDK plays a transport role between the Prebid Server and the Primary Ad Server SDK. It makes the bid requests to the Prebid Server and sets the targeting keywords (containing the winning bid price) as part of the Primary Ad Server SDK ad request. Then the process of delivering ads may vary and depends on the Primary Ad Server, its SDK, and the Prebid Universal Creative. In most cases, the ad response contains the chain of ad sources including a Prebid one. If the Prebid’s ad source wins, the Universal Creative is loaded into the ad view (display or video) and eventually loads the actual ad from the Prebid Cache.

For more details about ad operations with Prebid, see Prebid Ad Ops tutorials.


Prebid SDK Integration Requirements

The Prebid Mobile SDK works with MoPub and Google Ad Manager (GAM, fka DFP) as Primary Ad Servers. It is not responsible for the rendering of ad creatives which are performed by GAM or the MoPub SDK respectively. This means that for the displaying of Prebid demand, you should have a Primary Ad Server SDKs and an account on the ad server. If you already use GAM or MoPub to monetize your app, the integration is simpler and you only need to add the In-App bidding functionality to the existing inventory.

Below is a list of requirements which are necessary for an In-App Bidding integration:

  • An account on the Primary Ad Server (MoPub or GAM).
  • An ad unit on the Primary Ad Server.
  • A Prebid Order on the Primary Ad Server for the particular ad unit Configuration for the header bidding auction for the same type and size of inventory on the Primary Ad Server.
  • The Primary Ad Server SDK integrated into the application.
  • The Prebid SDK integrated into the application.

The following sections will not cover questions about creating accounts and ad units on the Primary Ad Server, you can read such topics in the respective guides for GAM and MoPub. However, the following sections describe how to prepare Prebid Orders on these servers.

For how to get started and set up Prebid Mobile, see Getting Started with Prebid Mobile.


Apollo Account Setup

If you do not currently have an Organization account and an Admin user on the OpenX Apollo UI, please contact OpenX Apollo Support.

Once you have access to your organization on the OpenX Apollo UI, you should prepare configurations for header bidding auctions. The two types of configurations are Stored Requests and Stored Impressions which are both covered in the following sections.


Creating Stored Configurations

In-App bidding is responsible for sending bid requests from the client app to the Prebid server which broadcasts the bid request to the registered bidders in the scope of a parallel auction. To provide more flexibility in the modification of bid requests without having to redeploy the application, the Prebid server provides the concept of Partially Stored Bid Requests. Basically, the OpenRTB blocks stored on the server-side are merged into OpenRTB requests which are sent to the bidders.

For more about how Prebid resolves Mobile bid requests and what should be placed in stored configurations, see Use Case: Prebid Server, Prebid Mobile SDK.

To create a new configuration:

  1. In OpenX Apollo UI, click on the Prebid Server tab.

  2. Click on .

  3. From here, open the Type list to either create a Stored Request or a Stored Impression.


Stored Request

Stored Requests are parts of bid requests storing properties like timeouts and price granularity. The initial Stored Request on OpenX Apollo must contain the Organization ID, otherwise, the auction will not start.

example of a minimal and valid configuration

{
  "app": {
    "publisher": {
      "ext": {
        "prebid": {
          "parentAccount": "YOUR_ORGANIZATION_ID"
        }
      }
    }
  }
}

You can find your Organization ID in the Organizations list or in the URL of your Organization page:

organization ID in the organizations list

organization ID in the organizations page


Stored Impression

A Stored Impression is a part of the imp object stored on the server. Here you can provide impression details and bidder information.

example of a configuration

{
  "banner": {
    "format": [
      {
        "w": 300,
        "h": 250
      }
    ]
  },
  "ext": {
    "openx": {
      "delDomain": "<REPLACE_WITH_DEL_DOMAIN>",
      "unit": "<REPLACE_WITH_OX_ADUNIT>"
    }
  }
}

Each bidder requires its own unique set of properties which you can find on the Prebid Server Bidders Params page. For example, OpenX bidder requires the following parameters:

  • delDomain or platform: The OpenX delivery domain or platform id provided by your OpenX representative.
  • unit: The OpenX ad unit ID provided by your OpenX representative.

In addition, you can customize stored impressions with other bidding properties.

If you are not familiar with these properties, please contact OpenX Apollo Support.


Collecting Integration Details

Once you have a Stored Request and Stored Impression, you can then run the auction. To make a bid request you should provide the ID of Stored Request and the ID of Stored Impression to the SDK. You can easily find them in the OpenX Apollo UI.

The ID of the Stored Request is an Account ID in the Prebid SDK. The ID of the Stored Impression is a config ID for the particular ad unit in SDK API. Note these configs as they will come in handy later.


Preparing Prebid Orders

You can now prepare your delivery items on the Primary Ad Server. Prebid demand can be integrated into an existing Google Ad Manager or MoPub monetization setup by inserting the special Line Items with custom targeting into the ad unit waterfall.

You can find detailed instructions for creating line items in Prebid Docs:

The most significant requirement is to keep the Price Granularity rules. The automation tool for setting up Prebid orders like PubMonkey can help you to create hundreds of line items rapidly according to Prebid’s rules. The process of creating orders is crucial and requires several subtle configurations.

Feel free to contact OpenX Apollo Support anytime to get help here. The more precise the orders you create, the more efficient your integration is.


Integrating the Prebid SDK

The following section describes how to integrate the Prebid SDK.


Initializing the SDK

Once the OpenX Apollo and Primary Ad Servers are ready for serving Prebid demand, follow Prebid instructions to integrate the SDK into your application:

To connect the Prebid SDK to the OpenX Apollo Server, you must set the custom Prebid host.

Apollo Prebid host URL: https://prebid.openx.net/openrtb2/auction

In addition, you must return to the OpenX Apollo UI and prepare the Stored Request ID as it is required to initialize the Prebid SDK.

Initialization code for iOS

do {
     Prebid.shared.prebidServerAccountId = STORED_REQUEST_ID
     Prebid.shared.prebidServerHost = .Custom
     try Prebid.shared.setCustomPrebidServer(url: "https://prebid.openx.net/openrtb2/auction")
} catch {
    print("[ERROR] \(error.localizedDescription)")
}

Initialization code for Android

val prebidHostUrl = Host.CUSTOM
prebidHostUrl.hostUrl = "https://prebid.openx.net/openrtb2/auction"
val prebidServerId = STORED_REQUEST_ID

PrebidMobile.setPrebidServerHost( prebidHostUrl )
PrebidMobile.setPrebidServerAccountId( prebidServerId )

The Prebid SDK is now ready to make bid requests to OpenX Apollo.


Providing Targeting Information

To increase the opportunity to receive a winning bid you should provide as much targeting information as possible. See the iOS and Android docs for details. Also make sure that you follow the Prebid Mobile Guide to Privacy Regulation.


Integrating into the Primary Ad Server Ad Units

Once the Prebid SDK is ready to send bid requests and the Prebid Order is prepared on the Primary Ad Server, it is time to integrate In-App bidding into particular inventory using the Prebid SDK API.

This step does not require any modifications of the Prebid SDK integration instructions, so follow the instructions for the respective ad formats provided in Prebid Docs:

Ad UnitPrebid Integration Guide
Banner Android
iOS
Banner Interstitial Android
iOS
Native Android
iOS
Native Styles Android
iOS
Banner Video Android
iOS
Video Interstitial Android
iOS
Rewarded Video Android
iOS
In-Stream Video Android
iOS

The configuration IDs that you need during the integration are IDs of Stored Impressions on OpenX Apollo:

You should now receive ads from Prebid demand in your apps.


Troubleshooting

If you have completed all integration steps but are still not receiving bids or they are not monetized on the Primary Ad Server, contact OpenX Apollo Support which is the first point of contact for OpenX Apollo Publishers.

Below are the most common issues.


Stage 1: Bid Request

If you do not see ads from demand partners, you first need to check the status of the fetchDemand() function. The Success and NoBids statuses confirm that the SDK is set up correctly.

If you receive another status, check the troubleshooting tips below:

StatusAction
ServerNotSpecifiedMake sure that the prebid server URL is set correctly. See Integrating the Prebid SDK.
InvalidAccountIdMake sure that you provide a correct ID of Apollo’s stored request. See Integrating the Prebid SDK.
InvalidConfigIdMake sure that Stored Request and Stored Impression have the correct format. See Preparing Prebid Orders.
InvalidSizeMake sure that you used the proper ad size for the ad unit and that your biders support it. See Preparing Prebid Orders.
NetworkErrorCheck your connection and try to make auction requests from the command line of the developer machine or in the browser of the device.
ServerURLInvalidMake sure that the prebid server URL is set correctly. See Integrating the Prebid SDK.
ServerErrorIf the error is not self-descriptive and could not be solved on the client side, contact OpenX Apollo Support.
DemandTimedOutContact the demand partner or OpenX Apollo Support to figure out the reason for the timeout.

Stage 2: Debugging of Bid Requests

If you constantly receive NoBids and your configurations are correct, inspect the requests to the bidders by adding the test flag to the Stored Request.

{
  "app": {
    "publisher": {
      "ext": {
        "prebid": {
          "parentAccount": "b4eb1475-4e3d-4186-97b7-25b6a6cf8618"
        }
      }
    }
  },
  "test": 1
}

Now using the proxy toll, you can see the debug information in the bid responses. In particular, you will see the bid requests to the bidders. It might help you to figure out the reason for empty bid responses. Feel free to reach the OpenX Apollo Support to get help in debugging.


Stage 3: Ad Request

If you receive bids from OpenX Apollo but do not see ads in the app, do the following:

  • Check the Prebid Order on the Primary Ad Server, in particular the prices and targeting keywords in the Line Items. Remember the targeting keyword of the winning bid, for example hb_pb:0.10, and make sure that you have a Line Item with respective price and targeting keyword.
  • Verify that the Line Items have the correct creative with a respective Prebid Universal Creative (PUC) to the ad unit format.
  • Using any proxy tool, verify that the Universal Creative is shipped in the ad response.
  • Verify that the PUC makes a request to the Prebid Cache (PBC).
  • Verify that the request to the PBC is correct and utilizes the same cache_id that returned in the winning bid within the targeting keywords.
  • Verify that the PBC responds with a valid creative code.

If you do not see Prebid ads after performing all of the steps mentioned above, reach out to OpenX Apollo Support to get help in debugging.


References

In addition, you should consult the following troubleshooting articles from Prebid:


Support

For any support inquiries, feel free to contact the OpenX Apollo support team at apollo-support@openx.com.