Protected Audience: integration guide

Protected Audience (formerly known as FLEDGE) on Android implementations typically involve integration between advertiser apps, publisher apps, sellers, and buyers. This guide is intended for partners who plan to manage custom audiences and run auctions, including ad tech networks that operate as both buyers and sellers. Different ad campaigns can have different goals, and not all Protected Audience features are used for all use cases. This guide attempts to call out the steps needed to support more specialized cases wherever possible.

To prepare for at scale production deployment of Protected Audience, partners may begin testing by mocking the integration points with other parties. To help you with integration planning, this guide provides a comprehensive view of how to integrate Protected Audience with your Android apps. This may include features that are not yet implemented at the current stage of the Privacy Sandbox on Android Developer Preview. In these cases, timeline guidance is provided.

The Protected Audience integration workflow consists of 4 key steps driven by different types of ad tech partners:

  1. The buyer creates custom audiences.
  2. The ad selection process picks a winning ad.
    1. The seller's app initiates ad selection.
    2. Ad services executes buy-side filtering and bidding code.
    3. Ad services executes sell-side decision code.
  3. The winning ad is rendered in the seller's app.
  4. Reports for ad impressions are made available to both the buyer and the seller.

The following diagram illustrates these steps:

Visual diagram of the ad selection workflow.
The Protected Audience custom audience management and ad selection workflow.

Terminology

  • Advertiser: A company that engages users through means of buying ad inventory.
  • Publisher: A company that sells ad inventory that is available alongside their content.
  • Buyer: An ad tech company that facilitates advertisers in buying ad inventory.
  • Seller: An ad tech company that facilitates publishers in selling ad inventory.
  • Network: An ad tech company that acts as both a buyer and a seller.
  • Owned and operated: A company that acts as the publisher, seller, and buyer.
  • Integration partners: Any companies that you need to work with to successfully integrate with Protected Audience.

Prerequisites, integration partner engagement, and setup

This section outlines a set of initial activities to help you understand how Protected Audience works, how to get started with Protected Audience integration, and how to engage with your integration partners on a Protected Audience implementation. These activities can happen in parallel.

Diagram showing the rollout guide for Protected Audience features.
Rollout guide for Protected Audience features.

Familiarize with Protected Audience

The first step is to familiarize yourself with the Protected Audience APIs and services.

  1. Begin by reading the design proposal to familiarize yourself with the Protected Audience API and its capabilities.
  2. Read the developer guide to learn how to incorporate the code and API calls that you need for your use cases, and the services needed to integrate with Protected Audience.
  3. Submit feedback regarding the design and implementation of Protected Audience APIs, services, and documentation.
  4. Sign up to receive updates to stay current on the latest Privacy Sandbox features.

Set up and test sample apps

Once you're familiar with the Protected Audience basics as outlined earlier, you should set up and test the sample apps.

  1. When you are ready to begin your integration, set up your development environment with the latest Privacy Sandbox Developer Preview.
  2. Set up required server endpoints. Use the sample mocks with your preferred API testing solution to bootstrap this process.
  3. Fork and run the code in our sample app to familiarize yourself with custom audience management, ad selection workflow, and impression reporting.

Integration partner engagement

Schedule discussions with your integration partners to discuss testing and adoption of Protected Audience on Android, including the shape of signals passed between parties. For buyers, discussions should include strategies to create and join custom audiences, which may include discussions on how audiences are defined. Collaborate with your integration partners to define timelines for integration, from initial testing to adoption, and which areas each party is responsible for in the design.

Beta setup (Available in Q4)

Enroll your organization with the Privacy Sandbox on Android. Enrollment is required to ensure ad tech developers operate within the policies of the Privacy Sandbox, and allows ad tech developers to define their identity across multiple SDKs and domains.

Architectural considerations

For both buyers and sellers, Protected Audience introduces the ability to run ad auctions on the device. You and your integration partners should factor in several critical considerations in your designs:

Audiences and remarketing ads are stored on the device

In contrast to storing ads entirely on servers today, audience information and remarketing ads are stored on the device. Contextual ads that don't rely on in-device data for targeting shall continue to remain on servers. Ad tech platforms need to expand to consider ads demand that is spread between servers and devices.

Bidding and auction processes happen on the device

In addition to running auctions on servers, ad tech platforms now have the opportunity to price and rank the ad demand stored on the device.

A common approach is that ad techs run auctions for contextual ads as they do today. After completing the auction, a seller can choose to run an auction on the device to evaluate the remarketing demand stored on the device. Given that these processes now run on the device it is important to remember the existing limits in place to ensure the auction runs end to end as designed by the different integration partners, in a variety of remarketing use cases.

Data strategy

Ad tech platforms should consider the data types that are used in auctions. Today, this information is collected from various sources and then centralized on a server. Protected Audience auctions offer several different paths to pass that data in. For example: Real-time signals such as remaining budget come from a key-value service as trusted signals, whereas contextual signals like time of day are sent from sellers when running an auction. These signals are explained more in depth in the relevant sections of this guide.

Build your solution

There are several key stages to run an auction with Protected Audience. Buyers must build the audience, supply bidding data, target ads to audiences, and set up bidding. The seller must configure and trigger the auction, score the candidate ads, and select a winner. Some of these stages require collaboration between both parties to ensure the auction can execute correctly. The following sections describe each stage in detail and explicitly call out which party is responsible for implementation.

Buyers: Building an audience

Buyers typically manage custom audiences. Since custom audiences are managed on device, the API to manage custom audiences is designed to be invoked on device.

If you have your own SDK present in the advertisers app, you can implement this code directly via joinCustomAudience().

If you don't have your own SDK code on devices, you can consider partnering with an existing integration partner that is also an SDK provider. Identify and work with this partner to define a contract and a flow for defining and managing custom audiences. This guide uses the term "buyer" regardless of which approach is used. Some example approaches include:

  • As a buyer, have the advertiser define the audience. An integration partner SDK on the device can send app events to the buyer. When predefined criteria are met, the buyer sends a message to the SDK to join the custom audience on the client on behalf of the buyer.
  • The SDK can own the audience directly. Advertisers work with an SDK provider to define the audience. The SDK monitors app events and joins the audience at the appropriate time, and notifies the buyer that a user has been joined to the audience.

Prototype remarketing campaign: Design a custom audience

A custom audience is a grouping of users with similar interests that can be served personalized ads. Buyers can help advertisers build custom audiences in their apps based on user activity.

Protected Audience establishes a container for the custom audience that maps to a particular custom user engagement as defined by the advertiser. This includes a collection of candidate ads that can be shown to that audience, and a collection of custom bidding logic and data that can be used during an auction to filter and price the ads.

Setup and prototype

Design considerations

Buyers can support a variety of use cases by configuring custom audiences. This includes defining bidding logic for the type of ad or campaign this audience is targeted with, defining the list of candidate ads, and similar considerations. This section includes design considerations for populating and using some key fields in a custom audience.

Bidding logic URL

Since auctions are executed on device, buyers need to deploy an endpoint that can return bidding logic as JavaScript. Our developer guide describes the method signatures required. Bidding logic has access to certain signals about the user during the auction as described in the next few sections. Bidding logic and user signals setup is explained later in this article.

User bidding signals

The buyers can use UserBiddingSignals to pass in knowledge that the advertiser or the buyer itself has about the user into future auctions on the device. This can include information such as:

  • Other audiences the user has been added to.
  • First-party insights the advertiser has about the user.

Because these signals are available during the auction, the buyers can perform custom bidding operations during the auction, including:

  • Bid up or down based on bidding signals.
  • Filter out specific ads from the auction.

Trusted bidding data

As part of the Protected Audience implementation, buyers can access real-time information during the auction from a key-value service. As a temporary mechanism, the buyer and seller can fetch these bidding signals from any service, including one they operate themselves. The most common example is to look up the remaining budget for ads. During development, it is possible to mock this service, and you can develop against this mock endpoint. See the FledgeServerSpec directory in our sample app repo on GitHub for setup instructions.

The TrustedBiddingData field is composed of a URL and a set of keys. Here are some considerations when designing what kind of key structure to use:

  • A simple approach is to include a key that maps 1:1 to the audience being created. The key-value service can then contain all the relevant information associated with the audience.
  • Budget and ad status are important things to consider in real-time.
  • Maximum bid amount or other signals that can be used to price an ad in an auction. It is possible to include this information with the ad in an AdData list, but storing this in a key-value service allows for it to more easily be updated as needed.

AdData list

When building a remarketing campaign, advertisers typically consider many different types of ads to show to a user in an audience, such as advertising different discounts based on a user's prior engagement with the app. A custom audience includes an AdData list that holds candidate ads.

The amount of information to include for each ad is up to the buyers to decide. Some things to consider:

  • The AdData list can be updated in 2 ways:
    • When the app has a visible activity in the foreground, it can initiate the list when it joins a user to a custom audience.
    • During a daily update the fetch initiated in the background. The device sends a request to the daily_update_url included in the joinCustomAudience call and expects a response including an updated AdData list.
  • Additional information about ads can be requested at the time of the auction. Before the auction, the device sends a request to the buyers' key-value service that was provided in the trustedBiddingData field of joinCustomAudience. The key-value service is a new service that is part of the buyers' implementation of Protected Audience. More details about this service are explained later in this document.
  • The inclusion of a creative id for your ad can help you take certain actions on specific creatives. For example, advertisers may pause specific creatives and you want to pull those creative ids from the real-time key-value service and then match against ads in the AdData list.

AdData should include a render_url. The render URL of the winning remarketing ad is used to render the ad. Some considerations include:

  • The render URL has a k-anonymity threshold, so avoid including narrow parameters. More information regarding this k-anonymity threshold will be published at a later date.
  • This URL should contain all the information necessary to render the ad. For example, if you want to show specific products, embed product ids as parameters in the URL.

While prototyping, the only required field is the renderUri, which points to the ad's rendering assets. The metadata field in AdData can be ignored while you create your solution. As you move your solution towards production, you should consider what metadata is relevant to you as it can be used during bid generation to adjust your bid price.

Activation time and expiry time

You can use the activation and expiry time fields to support use cases where a custom audience should only be eligible for auctions within a predefined time. Be aware that there are certain limitations for how long an activation time can be delayed and the delta between activation and expiry time. Example use cases include:

  • Lapsed user (e.g. a user who hasn't engaged with the advertiser's app in the past 7 days)
    • Every time the user opens the app, the buyer can call joinCustomAudience and configure activation_time to be a timestamp to be 7 days in the future.
    • The audience is eligible for bidding, if 7 days have passed since the user last opened the app.
  • Seasonal audience (an audience that is only valid during a specific timeframe in the near future)
    • A buyer can start defining custom audiences in advance that should only be eligible for bidding during a predetermined time in the (near) future.
    • For example if an advertiser has an end of summer campaign in the United States in 2022, their buyer can call joinCustomAudience and configure activation_time to be Saturday August 20th, 2022. If the campaign only runs for one week, the buyer can set the expiration date to August 27th, 2022, after which the custom audience is filtered out by the platform during ad selection and eventually garbage collected.

Buyers and sellers: Ad selection

Ad selection requires collaboration between buyers and sellers. This can be looked at as a four step process:

  1. Sellers define a mediation strategy.
  2. Sellers configure the auction and initiate ad selection.
  3. Buyers are invited to participate in the auction via the seller defined configuration. The buyer's bidding logic is executed to select a candidate ad and bid.
  4. Sellers decision logic is executed to score the candidates and select a winning ad.

To ease development, it is possible to mock service responses for buyers and for sellers, which includes bidding and scoring logic, allowing you to focus on developing what is relevant to your use case. See the FledgeServerSpec directory on GitHub for instructions on setting up mock endpoints, or the developer guide for instructions on how to override the need for remote JavaScript fetching.

Sellers: Define mediation strategy

Protected Audience aims to support waterfall mediation. This area is under development, and more information will be provided when available. For now, refer to the design proposal for waterfall mediation in Protected Audience.

Sellers: Configure the auction

Sellers are responsible for configuring the auction, providing information to the ad selection process. Sellers can choose to make information available to every or selected parties only. This can include information that you have or information you include on behalf of buyers.

Setup and prototype

  • A seller can configure and initiate an auction by setting up an AdSelectionConfig object and using the AdSelection API. Trigger the auction by invoking selectAds().
  • See the developer guide for implementation and API usage details.

Design considerations

This section includes design considerations for populating and using key fields in an ad selection configuration.

  • The private execution environment only includes custom audience ads on the device, so issuing a contextual ad request prior lets you consider additional demand.

  • Before you initiate the ad selection workflow, run an ad request to collect information from buyers. Then, use this information to configure ad selection.

  • Since many buyers could have created custom audiences on the device, sellers must use the custom audience buyers field to indicate the specific buyers to include in the process. There are many ways this list can be constructed. Some examples include:

    • A static list of buyers that the seller always wants to include in the process.
    • A list of buyers indicating wanting to participate in their ad response. This option is useful if the seller works with ad exchanges and might not have full knowledge of all buyers.

  • The seller can pass information into the process in several ways:

    • The ad selection signals field is available to all buyers and the seller that participate in the auction in the private runtime. Use it to provide information about the ad opportunity such as ad size and ad format.
    • The per buyer signals field is forwarded to a specific buyer to be used in their bidding process. This information is provided by the buyer, and you as the seller need to consider how to get this information on device for use during ad selection.
    • The seller signals field is the final way for the seller to pass information into the process. You as a seller use these signals when scoring ads and filtering ads, such as enabling a brand safety check.

Buyers: Bidding for an ad slot

Setup and prototype

  • A buyer can add their bidding logic to the generateBid() JavaScript function that's served from the biddingLogicUrl parameter set when building a CustomAudience. You can set up a mock service using the provided spec, or implement this endpoint on a real server.
  • See the developer guide for implementation and API usage details.

Design considerations

  • Bidding logic is executed on device, and some signals used in the auction are queried in real time. Refer to the list of limitations for constraints.
  • For some ad use cases, it is important to work with the seller to ensure you have multiple ad candidates and their bids to be considered on device.

Design bidding logic

The buyers' bidding logic needs to be implemented via JavaScript and is executed on device. The developer guide has information on the required signature and details about the various parameters passed in during the auction. Your bidding logic on the device has access to additional information, passed in as parameters to your generateBid() function.

Supply bidding data

Real-time bidding signals with key-value services

As a buyer, you can fetch real time signals during an auction from a key-value service you own. You can find an initial implementation of this service in the public Privacy Sandbox repository, or you can create a service of your own. The URL for this service is specified as the trustedBiddingUrl in a custom audience, and the platform attempts to fetch the data and make it available to your generateBid function with the trusted_bidding_signals parameter. You need to establish your own key structure.

Contextual and user signals

Your generateBid function has access to additional user signals when running the auction on device. These signals are passed with the contextual_signals and per_buyer_signals fields. These fields are all JSON objects whose format needs to be defined by buyers and sellers.

The contextual_signals field includes information that may be relevant about the user. The object holding these signals are created by Protected Audience itself and passed through to your bidding logic. This is currently passed as an empty object. If you believe a contextual signal about the user could be relevant to your use case, file feedback for consideration.

The per_buyer_signals field is made available to your bidding logic. A seller sets these values when creating the auction configuration. Buyers and sellers need to collaborate to ensure this data is on device and passed to your bidding logic. Some example uses for this field include:

  • Filtering for brand safety. The seller can let the buyers know some classification information about the app that is requesting an ad, and the buyer can use this information to filter out certain ads.
  • Sending an embedding for an ML model that considers contextual information.

Sellers: Score and select the winning ad

Setup and prototype

  • A seller can add their scoring logic to the scoreAd() JavaScript function that's served from the scoringLogicUrl parameter set when building the AdSelectionConfig. You can set up a mock service using the provided spec, or implement this endpoint on a real server.
  • See the developer guide for implementation and API usage details.

Design scoring logic

Sellers implement scoring logic in JavaScript, which is executed on device. The developer guide has information on the required signature and details about the various parameters passed in during the auction. In addition, your scoring logic on the device has access to additional information passed in as parameters to your scoreAd function.

Supply scoring data

Real-time scoring signals with key-value services

As a seller, you can fetch real time signals during an auction from a key-value service you own. You can find an initial implementation of this service in the public Privacy Sandbox repository. The URL for this service is specified as the trustedScoringUri in the auction configuration, and the platform attempts to fetch the data and make it available to your scoreAd function via the trusted_scoring_signals parameter. You should establish your own key structure.

Contextual and user signals

Your scoreAd function has access to additional user signals when running the auction on device. These signals are passed to your scoring function via the contextual_signal field. This field holds a JSON objects whose format is defined by buyers and sellers.

The contextual_signal field includes contextual information that may be relevant about the user. The object holding these signals is created by Protected Audience itself and passed through to your scoring logic. This is passed as an empty object. If you believe a signal about the user could be relevant to your use case, file feedback for consideration.

Sellers: Render an ad

Sellers need to render the winning ad. Refer to the design proposal for additional details regarding how winning ads are rendered. This area is still under design.

Report impression results

Setup and prototype

  • Buyers and sellers can add reporting logic to the reportWin() JavaScript function that's served from the biddingLogicUrl or scoringLogicUrl parameter respectively. You can set up a mock service using the provided spec, or implement this endpoint on a real server.
  • See the developer guide for implementation and API usage details.

Design considerations

Buyers and sellers must implement a reportWin function in their JavaScript code returned from their configured endpoints. This method allows you to send data back to your servers.

The Privacy Sandbox also provides an Attribution Reporting API for managing event level and aggregate reports. Read the integration guide for more details.