Privacy Sandbox on Android Developer Preview is here! Learn how to get started, and continue to provide feedback.

Multi-seller auction support with FLEDGE Mediation

Stay organized with collections Save and categorize content based on your preferences.

Provide feedback

Sell-side ad platforms typically diversify their ad demand sources to optimize for ad revenue. With ad mediation, an ad network or service invokes multiple ad networks to determine the best ad for a given ad slot. This proposal introduces how FLEDGE on Android can be extended to implement waterfall mediation functionality in a privacy-preserving way. Today, ad networks provide various ways for app developers to mediate ad auctions from multiple ad sellers:

  1. Waterfall mediation: App developers define an ordered list of ad networks, often ranked by historical eCPMs for the given network. This list is known as a mediation chain. The app developer's mediation platform uses this list to call ad networks in the order they are listed to determine relevant ad demand sources.
  2. Programmatic mediation: Multiple ad networks are configured by the app developer to participate in bidding for ad opportunities. These networks are allowed to bid in real-time based on how they value the opportunity.
  3. Hybrid mediation: A combination of waterfall and programmatic mediation techniques.

Waterfall mediation

In waterfall mediation, when an ad opportunity arises, an ad SDK sends a request to its backend server. Instead of responding to the request with a winning ad creative, the server responds with a mediation chain that contains a list of ad networks ordered by historical eCPM.

Diagram of the waterfall mediation model
Figure 1: The waterfall mediation model

In the traditional waterfall model, an ads SDK calls each ad network (or its own auction SDK) in the order specified by the mediation chain. If an ad network can fulfill the ad request, the ad network renders the ad. If not, the request is sent to the next network in the chain. This process is repeated until the request is fulfilled or the chain is exhausted.

Waterfall mediation is often optimized by regularly reordering the mediation chain based on the re-evaluation of eCPM from first-party ad demand sources.

Programmatic mediation

Programmatic mediation (also known as "header bidding") is an alternative to using historical eCPM to determine which ad network gets the chance to serve an ad request. With programmatic mediation, providers instead use live bid values to find the winning ad.

Diagram of the programmatic mediation model
Figure 2: The programmatic mediation model

Hybrid mediation

Some programmatic mediation solutions combine ad networks in a hybrid mode of waterfall and bidding to provide more control to the ad while getting the benefit of using live eCPMs to maximize revenue from participating ad networks.

In hybrid mediation models, ad networks and mediation providers can provide increased flexibility to app developers by combining elements of waterfall and real-time bidding. Hybrid models allow app developers to configure ad networks based on historical eCPMs, giving them the opportunity to show an ad before running real-time bidding with participating networks to fill ad opportunities.

FLEDGE waterfall mediation

FLEDGE for Android supports waterfall mediation by having multiple FLEDGE auctions, each for an individual node in the mediation graph. If there is no winner from an auction, the next network auction node is called until the chain is exhausted. The waterfall mediation process is as follows:

  1. The mediation SDK fetches the mediation chain from the contextual ad server endpoint, which may return either contextual ads or mediation chains.
  2. If the ad server endpoint returns a mediation chain, the mediation SDK iterates through each item of the chain in order, invoking the participating ad network’s SDK to run a contextual and remarketing ad selection. Each item in the chain represents an ad network’s request to purchase ad space for a specific price for a specific amount of impressions, clicks or ad time.
  3. If none of the line items in the chain pick a winning ad, the mediation SDK may choose to show an ad from its own ad network by running a FLEDGE ad selection that considers both remarketing and contextual ads.

Diagram of FLEDGE's waterfall mediation flow
Figure 3: Waterfall mediation with FLEDGE

The above diagram represents an example of a waterfall mediation algorithm that a mediation SDK can implement, but without the ability for the first-party ad network to optimize. FLEDGE supports first-party ad network optimization by allowing chaining of ad selection workflows and reporting winning impressions.

AdSelection outcome

The return type of runAdSelection() is an AdSelectionOutcome object. AdSelectionOutcome contains the render URI of the winning ad and an AdSelectionId, which is an opaque integer that identifies the winning line item’s ad creative.

AdSelectionOutcome {
  Uri renderUri;
  Long AdSelectionId;

AdSelectionId acts like a pointer to the AdSelectionOutcome. Today, AdSelectionId is passed into the reportResult() method as the ReportImpressionInput parameter to help identify the correct ads that the reportWin() and reportResult() methods are invoked upon.

Chain ad selections proposal

We propose to extend RunAdSelection to consider the results of previous ad selection runs to select a winning ad by way of the AdSelectionOutcome object. This allows ad networks to run mediation that considers contextual and remarketing ads from multiple ad networks.

ChainedAdSelections is added as an optional parameter to AdSelectionConfig. ChainedAdSelections can contain a list of ad selection outcomes from previous invocations of the runAdSelection() method in the mediation chain. In the following example, an SDK runs AdSelection using outcomes from SDK A and SDK B on the device. SDKs A and B both explicitly share the AdSelectionOutcome from their respective runAdSelection() calls to the SDK that runs the chained ad selection.

AdSelectionConfig myAdSelectionConfig = new AdSelectionConfig {
    Seller = "",
    DecisionLogicURL = Uri.parse("https://..."),
    CustomAudienceBuyerList = Arrays.asList("",""),
    AdSelectionSignals = "{"min_price": 10,"auction_attempts": 3}"
    SellerSignals = "{"seller_type": "news", "content_category": "sports","mature_ads_accepted" :"false"}"
    PerBuyerSignals = "{"": {"key1" : "value1"},
                        "": {"key1" : "value1", "key2" : "value2"}"
    ChainedAdSelections = {network_a_selection_outcome, network_b_selection_outcome}

// Invoke ad services API to initiate ad selection workflow.
AdSelectionOutcome winningAd = runAdSelection(myAdSelectionConfig);

Diagram of ad selection chaining
Figure 4: Chaining ad selection with RunAdSelection().

Note that the return value of this runAdSelection() call is another AdSelectionOutcome object.

  • A value of null is returned in case there is no ad selected.
  • A new AdSelectionOutcome object is returned in case any of the ads referred to by the ChainedAdSelections is not the winning ad.
  • One of the outcomes passed in AdSelection is returned in case it is the selected ad.

Report winning impressions

In case there is no winner of the chained ad selection, no winning impression is expected to be reported.

If one of the AdSelectionOutcome objects that is passed into the AdSelectionConfig is selected, then the SDK running the chained ad selection is expected to communicate with the winning ad SDK about the outcome. The winning ad SDK can then invoke the winning impression report as it would after running its own AdSelection. This will ensure that the winning ad's SDKs decision logic JavaScript is used for reporting the result. In this scenario, the SDK that runs the chained ad selection can report which ad SDK had the winning impression.

If none of the AdSelectionOutcome results are selected, the SDK that runs the chained ad selection invokes its winning impression report.

Run waterfall mediation

With the ability to chain instances of AdSelectionOutcome, as described earlier on this page, a mediation SDK can run waterfall mediation while allowing a first-party ad network to optimize. This process is summarized as follows:

  1. The mediation SDK obtains a mediation chain from the mediation server using a contextual ad request.
  2. The mediation SDK runs ad selection that considers both remarketing and contextual ads.
  3. The mediation SDK runs an auction that considers the outcome of the first-party ad selection and the historical eCPM of the first eligible item in the mediation chain.

  4. If an ad is selected, the winning ad is determined and the process ends.

  5. If no ad was selected, the mediation SDK selects the first eligible item from the mediation chain and invokes the corresponding SDK to run a contextual and remarketing ad selection.

  6. If an ad is selected, the ad is rendered and the process ends.

  7. If an ad is not selected, then the next item in the chain is considered, and step 3 is executed.

  8. If there are no more items in the chain, the mediation SDK shows a first-party ad by running FLEDGE ad selection that considers both remarketing and contextual ads, similar to step 2.

The FLEDGE waterfall mediation process
Figure 5: The FLEDGE waterfall mediation process

Best practices

Run contextual auctions before first-party optimization

Remarketing demand can generate high bids that can yield winning outcomes in a mediation chain. Truncation is a process that is often used to enable first-party optimization by refining the remarketing audience list.

FLEDGE remarketing demand is only available client-side with FLEDGE auctions. This can make it challenging to enable first-party optimization on the server side. To mitigate issues with first-party optimization, run the contextual auction first, and then perform first-party optimization based on the winning ad result as described earlier on this page.

Keep your on-device mediation chains small

For optimal performance, on-device mediation chains should be kept small. The compute cost for on-device execution may be linear at the number of auctions evaluated as part of the mediation chain. In other words, more nodes leads to more computational cycle requirements and increased latency. Consider the impact of latency on revenue when you pass nodes to on-device mediation evaluation.

Additional considerations

This proposal for FLEDGE mediation is a work in progress, and feedback is welcome.

FLEDGE doesn’t currently offer a comprehensive solution for mediation of multiple ad slots. Each ad slot must be processed independently.

The FLEDGE Mediation API currently supports waterfall mediation and limited programmatic mediation. More details on supporting additional programmatic mediation use cases will be shared in the future.

Since FLEDGE ad selection runs after contextual ads are fetched, invoking FLEDGE may impact the end-to-end latency of ad requests.