integrating_with_fledge.md

FLEDGE has been renamed to Protected Audience API. To learn more about the name change, see the blog post

Integrating the Key/Value server with FLEDGE

FLEDGE is a proposed API intended to serve remarketing ads without the usage of third party identifiers such as cookies or AdIDs. FLEDGE facilitates the auction between the buyers and the sellers, and when the auction executes, the Chrome or Android client will call the Key/Value server to retrieve real-time data.

There are two Key/Value server modes for FLEDGE: demand-side platform (DSP) and sell-side platform (SSP). The DSP Key/Value server is called during bid time and the SSP Key/Value server is called during ad score time.

On Chrome and Android, FLEDGE and Key/Value server integration involves general steps listed below:

1. Configure the interest group and add users.
   1. Set the DSP Key/Value server URL as trustedBiddingSignalsUrl.
   2. Set the keys to be queried as trustedBiddingSignalsKeys.
2. Configure the auction. 3. Set the SSP Key/Value server URL as trustedScoringSignalsUrl.
3. Execute the auction. 4. The values for trustedBiddingSignals are available in the generateBid() function for the buyers. 5. The values for trustedScoringSignals are available in the scoreAd() function for the sellers.

The following sections describe platform-specific instructions.

Chrome integration

Integrate with the DSP Key/Value server

The DSP Key/Value server is registered when a user is added to an interest group. The Key/Value server URL is set as trustedBiddingSignalsUrl and the queried keys are set as trustedBiddingSignalsKeys as properties in the interest group object.

For example:

// const customAudience for Android
const interestGroup = {
    owner: 'https://dsp.example',
    trustedBiddingSignalsUrl: 'https://dsp.example/kv/v1/getvalues',
    trustedBiddingSignalsKeys: ['key1', 'key2'],
    // ...and other interest group properties
};

navigator.joinAdInterestGroup(interestGroup, 7 * kSecsPerDay);

The ad interest group properties can be inspected in DevTools. Open the Application tab and select Interest Group from the sidebar.

When the auction is executed at a later time, the browser will use the keys defined when the user was added to an interest group to query the Key/Value server. The trusted bidding signal values will be available to the bidding function when the auction is executed by the seller.

The values will be in the trustedBiddingSignals of the generateBid() function:

generateBid(interestGroup, auctionSignals, perBuyerSignals, trustedBiddingSignals, browserSignals) {
  const {key1, key2} = trustedBiddingSignals['keys'];

  return {
    // ...
   };
}

Integrate with the SSP Key/Value server

The SSP Key/Value server is registered when the auction is executed. The SSP Key/Value server URL is set as trustedScoringSignalsUrl in the auction config.

const auctionConfig = {
    seller: 'https://ssp.example',
    trustedScoringSignalsUrl: 'https://ssp.example/scoring-signal/v1/getvalues',
    // ...and other auction config properties
};

const auctionResult = await navigator.runAdAuction(auctionConfig);

When the auction is executed, the browser calls the SSP Key/Value server with the render URL of each creative in the ad interest group to retrieve the trusted scoring signals. The seller can use the trusted scoring signals to make a decision about which ad to render to the user. The values from the SSP Key/Value server will be available in the scoreAd() function:

scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
  const {renderUrl1, renderUrl2} = trustedScoringSignals['renderUrls'];

  return desirabilityScoreForThisAd;
}

Android Integration

Integrate with the DSP Key/Value server

The DSP Key/Value server is registered when a user is added to a custom audience. The Key/Value server URL is set using the fields trustedBiddingUri and the keys using trustedBiddingKeys in the trustedBiddingData property of the custom audience object.

CustomAudience customAudience = return new CustomAudience.Builder()
    .setOwnerPackageName(Context.getApplicationContext().getPackageName())
    .setBuyer("buyer")
    .setName("name")
    // ...
    .setTrustedBiddingData(
        new TrustedBiddingData.Builder()
            .setTrustedBiddingUri("https://dsp.example/kv/v1/getvalues")
            .setTrustedBiddingKeys(ImmutableList.of("key1", "key2"))
            .build())
    .build();

final ListenableFuture<Object> joinCaFuture =  
          customAudienceClient.joinCustomAudience(customAudience);

joinCaFuture.addListener(() -> {
    //handle success or failure in joining CA
});

Integrate with the SSP Key/Value server

The SSP Key Value server is registered when an ad selection is initiated. It should be set in the AdSelectionConfig object used to configure the selectAds function.

AdSelectionConfig myAdSelectionConfig = new AdSelectionConfig.Builder()
    .setSeller("example-ssp1.com")
    .setDecisionLogicURI(Uri.parse("https://..."))
    .setTrustedScoringSignalsURi(
        Uri.parse("https://ssp.example/scoring-signal/v1/getvalues"))
    .setCustomAudienceBuyers(
        ImmutableList.of("example-dsp1.com","bexample-dsp2.com")),
    .setAdSelectionSignals("{\"min_price\": 10,\"auction_attempts\": 3}")
    .setSellerSignals("{\"seller_type\": \"news\", " +
        "\"content_category\": \"sports"," +
        "\"mature_ads_accepted\" :\"false\"}")
    .setPerBuyerSignals(ImmutableMap.of(
        "buyer1Name", AdSelectionSignals.fromString("{"key1" : "value1"}"),
        "buyer2Name" , AdSelectionSignals.fromString("{\"key1\" : \"value1\", \"key2\" : \"value2\" }"))
    .build();

// Invoke ad services API to initiate ad selection workflow.
ListenableFuture<AdSelectionOutcome> adSelectionOutcomeFuture =
    adSelectionClient.selectAds(myAdSelectionConfig);

adSelectionOutcomeFuture.addListener(() -> {
    // Handle result
});

When the auction is executed, the browser calls the SSP Key/Value server with the render URL of each creative in the ad interest group to retrieve the trusted scoring signals. The seller can use the trusted scoring signals to make a decision about which ad to render to the user. The values from the SSP Key/Value server will be available in the scoreAd() function:

scoreAd(adMetadata, bid, adSelectionConfig, sellerSignals, trustedScoringSignals,
        contextualSignals, customAudienceSignals) {
  const {renderUrl1, renderUrl2} = trustedScoringSignals['renderUrls'];

  return desirabilityScoreForThisAd;
}

Bidding and Auction Services with Key-Value Integration

Bidding & Auction services is a way to allow FLEDGE computation to take place on cloud servers in a trusted execution environment, rather than running locally on a user's device. Bidding & Auction system include:

• BuyerFrontEnd service and Bidding service operated by Buyer / DSP. BuyerFrontend service will send RPC to DSP Key/Value service to fetch real-time bidding signals.
• SellerFrontEnd service and Auction service operated by Seller / SSP. SellerFrontend service will send RPC to SSPKey/Value service to fetch real-time scoring signals.

Key-Value API

Following is the API of Key/Value Service that will be used by the Bidding & Auction system. You may also refer to the API public document.

// Key Value Service API.
service KeyValueService {
 rpc GetValues(GetValuesRequest) returns (GetValuesResponse) {
   option (google.api.http) = {
     get: "/v1/getvalues"
   };
 }
}

// Request for getting value.
message GetValuesRequest {
 // [DSP] List of keys to query values for, under the namespace keys.
 repeated string keys = 1;
 // [DSP] The browser sets the hostname of the publisher page to be the value.
 // If no specific value is available in the system for this subkey,
 // a default value will be returned.
 // The default value corresponds to the key when the subkey is not set.
 optional string subkey = 2;
 // hostname is a legacy name for subkey used specifically for Chrome FLEDGE.
 // New requests should use subkey.
 optional string hostname = 5;
 // [SSP] List of keys to query values for, under the namespace renderUrls.
 repeated string render_urls = 3;
 // [SSP] List of keys to query values for, under the namespace
 // adComponentRenderUrls.
 repeated string ad_component_render_urls = 4;
 // [Internal] List of keys to query values for, under the namespace
 // kvinternal. Internal demo/debug namespace. Not used by browsers.
 repeated string kv_internal = 6;
}

// Response for getting value.
message GetValuesResponse {
 // Map of key value pairs for namespace keys.
 google.protobuf.Struct keys = 1;
 // Map of key value pairs for namespace renderUrls.
 google.protobuf.Struct render_urls = 2;
 // Map of key value pairs for namespace adComponentRenderUrls.
 google.protobuf.Struct ad_component_render_urls = 3;
 // Map of key value pairs for namespace kvInternal.
 google.protobuf.Struct kv_internal = 4;
}