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:
- The buyer creates custom audiences.
- The ad selection process picks a winning ad.
- The seller's app initiates ad selection.
- Ad services executes buy-side filtering and bidding code.
- Ad services executes sell-side decision code.
- The winning ad is rendered in the seller's app.
- Reports for ad impressions are made available to both the buyer and the seller.
The following diagram illustrates these steps:
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.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/android/fledge-rollout-plan.png?authuser=6)
Familiarize with Protected Audience
The first step is to familiarize yourself with the Protected Audience APIs and services.
- Begin by reading the design proposal to familiarize yourself with the Protected Audience API and its capabilities.
- 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.
- Submit feedback regarding the design and implementation of Protected Audience APIs, services, and documentation.
- 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.
- When you are ready to begin your integration, set up your development environment with the latest Privacy Sandbox Developer Preview.
- Set up required server endpoints. Use the sample mocks with your preferred API testing solution to bootstrap this process.
- 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
- Use the custom audience API to create and store an audience on the device that can later be used in an auction.
- See the developer guide for implementation and API usage details.
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 thejoinCustomAudience
call and expects a response including an updatedAdData
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 ofjoinCustomAudience
. 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 configureactivation_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.
- Every time the user opens the app, the buyer can call
- 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 configureactivation_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:
- Sellers define a mediation strategy.
- Sellers configure the auction and initiate ad selection.
- 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.
- 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 theAdSelection
API. Trigger the auction by invokingselectAds()
. - 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 thebiddingLogicUrl
parameter set when building aCustomAudience
. 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 thescoringLogicUrl
parameter set when building theAdSelectionConfig
. 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 thebiddingLogicUrl
orscoringLogicUrl
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.
Recommended for you
- Note: link text is displayed when JavaScript is off
- Protected Audience API on Android developer guide
- Support custom audience targeting with the Protected Audience API
- Protected Audience frequency capping