Important
The main
branch hosts live code with latest changes. It is unstable and is used for development.
It is suitable for contribution and inspection of the latest code. The release-*
branches are
stable releases that can be used to build and deploy the system.
FLEDGE has been renamed to Protected Audience API. To learn more about the name change, see the blog post.
FLEDGE API is a proposal to serve remarketing and other custom-audience ads without third-party cookies. FLEDGE executes the ad auction between the buyers (DSP) and the sellers (SSP) locally, and receives real-time signals from the FLEDGE K/V servers. To learn more about
- FLEDGE for the Web: explainer and the developer guide.
- FLEDGE on Android: design proposal and the developer guide.
When the auction is executed, separate FLEDGE K/V servers are queried for the buyers and sellers. When a buyer is making a bid, the DSP K/V server can be queried to receive real-time information to help determine the bid. To help the seller pick an auction winner, the SSP K/V server can be queried to receive any information about the creative to help score the ad.
The current codebase represents the initial implementation and setup of the Key/Value server. It can be integrated with Chrome and Android with the Privacy Sandbox unified origin trial and Privacy Sandbox on Android Developer Preview. Our goal is to present the foundation of the project in a publicly visible way for early feedback. This feedback will help us shape the future versions.
The implementation, and in particular the APIs, are in rapid development and may change as new versions are released. The query API conforms to the API explainer. At the moment, to load data, instead of calling the mutation API, you would place the data as files into a location that can be directly read by the server. See more details in the data loading guide.
Currently, this service can be deployed to 1 region of your choice. Multi-region configuration is up to the service owner to configure.
- Source code is available on Github
- Releases are done on a regular basis
- Binaries can be built from source code
- C++ binary
- [AWS & GCP] Docker container image
- [AWS]: Nitro EIF
- [AWS]: Reference AMI
- Other tools
- Server can run as a standalone local process for testing without any cloud dependency or TEE-related functionality
- Server can be deployed to AWS Nitro enclave
- Server can be deployed to GCP Confidential Space
- Reference terraform available for a clean and comprehensive deployment to AWS or GCP
- Clean: assumes the cloud environment has no preset infrastructure
- Comprehensive: deploys all dependencies and some recommended (but not necessarily required) configuration
- Many server behaviors can be configured by parameter flags without having to rebuild
- Server loads key/value data from cloud file storage
- Server loads key/value data from cloud pub/sub services
- Server loads data into an in-RAM representation for query serving
- Server continuously monitors for new data and incrementally updates ("delta files") the in-RAM representation
- Support independent data ingestion pipelining by monitoring directories in cloud file storage independently
- Supports Flatbuffers as the data event format
- Supports Avro and Riegeli as the data file format
- Supports snapshot files for faster server start up
- Users can perform compactions of delta files into snapshot files in an offline path
- Support Protected Audience Key Value Server query spec: can be used as a BYOS server to serve requests from Chrome
- Support simple key value lookups for queries
- Users can write "user defined functions" to execute custom logic to process queries
- User defined functions can be written in JavaScript or WASM
- User defined functions can call "GetValues" to look up key value from the dataset
- Set-as-a-value is supported
- A key "value" pair in the dataset can be a key and a set of values
- UDF can call "RunQuery" API to run set operations on sets (intersection, union, difference)
- For GCP, Terraform supports deploying into an existing VPC, such as used by the Bidding and Auction services Non-prod Server logs are persisted after server shutdown
- Data can be sharded and different servers may load and serve different shards (subset) of the dataset.
- Sharding supports data locality, where the operator specifies "sharding key" for key value pairs so different key value pairs can have the same sharding key.
While we make efforts to not introduce breaking changes, we expect that to happen occasionally.
The release version follows the [major change]-[minor change]-[patch]
scheme. All 0.x.x versions
may contain breaking changes without notice. Refer to the release changelog for the
details of the breaking changes.
Once the codebase is in a more stable state that is version 1.0.0, we will establish additional channels for announcing breaking changes and major version will always be incremented for breaking changes.
- FLEDGE services overview
- FLEDGE K/V server API explainer
- FLEDGE K/V server trust model
- Local server quickstart guide
- AWS server user deployment documentation
- GCP server user deployment documentation
- Integrating the K/V server with FLEDGE
- FLEDGE K/V server sharding explainer
- Operating documentation
- Data loading API and operations
- Generating and loading UDF files
- Error handling explainer (to be published)
- Developer guide
- Code of conduct
- Change log
Contributions are welcome, and we will publish more detailed guidelines soon. In the meantime, if you are interested, open a new Issue in the GitHub repository.
The FLEDGE K/V feature set, API and system design are under active discussion and subject to change in the future. If you try this API and have feedback, we'd love to hear it:
- GitHub: For questions or feedback that are relevant to this proposal, open a new Issue in this repository. For questions that are purely relevant to browser-side logic, open an Issue in the Turtledove repository.
- W3C: You are welcome to attend the FLEDGE WICG meeting.
- Developer support: Ask questions and join discussions on
General announcements will be made on the FLEDGE mailing list on chromium.org and the Privacy Sandbox progress update page on the Android developer site, if needed, an accompanying article will be published on the Chrome Developers blog and Android Developers blog.