| // Copyright 2021 The Chromium Authors |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| module auction_worklet.mojom; |
| |
| import "content/services/auction_worklet/public/mojom/private_aggregation_request.mojom"; |
| import "content/services/auction_worklet/public/mojom/reject_reason.mojom"; |
| import "mojo/public/mojom/base/time.mojom"; |
| import "services/network/public/mojom/url_loader_factory.mojom"; |
| import "third_party/blink/public/mojom/devtools/devtools_agent.mojom"; |
| import "third_party/blink/public/mojom/interest_group/interest_group_types.mojom"; |
| import "url/mojom/origin.mojom"; |
| import "url/mojom/url.mojom"; |
| |
| // The other seller associated with a bid. For component (nested) |
| // SellerWorklets, `top_level_seller` is the seller for the parent auction. |
| // For top-level SellerWorklets, `component_seller` is the seller in the |
| // nested component auction where the bid was originally made. |
| union ComponentAuctionOtherSeller { |
| url.mojom.Origin top_level_seller; |
| url.mojom.Origin component_seller; |
| }; |
| |
| // When ScoreAd() is invoked for a component seller worklet, it returns an |
| // additional set of parameters that are passed to the top-level seller |
| // worklet in place of output from the GenerateBid() call that created the bid. |
| struct ComponentAuctionModifiedBidParams { |
| // Ad metadata to send to the top-level seller in place of |
| // BidderWorkletBid::ad. |
| string ad; |
| |
| // Bid value and currency to send to the top-level seller seller in place of |
| // BidderWorkletBid::bid. Only valid if `has_bid` is true. |
| double bid; |
| blink.mojom.AdCurrency? bid_currency; |
| |
| // True to indicate that `bid` has been populated. |
| // TODO(https://crbug.com/657632): Update when optional doubles are supported. |
| bool has_bid; |
| }; |
| |
| // Input parameters specific to a component auction's ReportResult() method. |
| struct ComponentAuctionReportResultParams { |
| // Metadata returned by the top-level seller's ReportResult() method, as JSON. |
| string top_level_seller_signals; |
| |
| // The bid value returned by the component seller's ScoreAd() method. May |
| // be the same value as the original bid. |
| double modified_bid; |
| |
| // True to indicate that `modified_bid` has been populated. False if the |
| // component seller's ScoreAd() method didn't return a bid value (either the |
| // same value of the original bid or a different value). |
| // TODO(https://crbug.com/657632): Update when optional doubles are supported. |
| bool has_modified_bid; |
| }; |
| |
| // Interface for returning ScoreAd results. The advantage of having an interface |
| // is that it makes ScoreAd() calls cancellable, and allows callbacks passed |
| // over the Mojo pipe to be deleted when the Mojo pipe is, to avoid setting off |
| // the raw pointer lifetime validation logic. |
| interface ScoreAdClient { |
| // Called when a ScoreAd() invocation completes. |
| // |
| // Parameters: |
| // `score` Non-negative score the SellerWorklet assigns to the bid. A value |
| // of 0 indicates either an error running the script, or that the script |
| // indicated the bid should not be used. |
| // |
| // `bid_in_seller_currency` If present, denotes the conversion of bidder's |
| // bid to seller's currency. Should be present only when auction |
| // configuration specifies what the seller currency is. |
| // |
| // `reject_reason` The reason this bid was rejected by the auction (i.e., the |
| // reason why `score` was non-positive). Default to kNotAvailable if not set. |
| // Will be ignored if `score` is positive. |
| // |
| // `component_auction_modified_bid_params` If this is a component seller |
| // worklet, contains parameters to pass to the top-level seller worklet |
| // in place of values from the original bidder worklet's BidderWorkletBid. |
| // |
| // `scoring_signals_data_version` The value of the Data-Version header served |
| // with the trusted scoring signals. nullopt when the header wasn't present. |
| // |
| // `debug_loss_report_url` The URL to request if this bid does not win the |
| // auction. It's requested if the auction runs to completion and this is not |
| // the winning bid, including the case that this worklet rejects this bid |
| // outright, giving it a score <= 0. This field has the debug prefix because |
| // it's part of an interim reporting API that will be replaced with |
| // standardized reporting APIs once available. It must be a valid HTTPS URL. |
| // |
| // `debug_win_report_url` The URL to request if this bid wins the auction. |
| // This field has the debug prefix because it's part of an interim reporting |
| // API that will be replaced with standardized reporting APIs once available. |
| // It must be a valid HTTPS URL. |
| // |
| // `pa_requests` The various requests made to the Private Aggregation API. |
| // |
| // `errors` are various error messages to be used for debugging. These are too |
| // sensitive for the renderers to see. `errors` should not be assumed to be |
| // empty if `score` is positive, nor should it be assumed to be non-empty if |
| // `score` is 0. |
| OnScoreAdComplete(double score, |
| RejectReason reject_reason, |
| ComponentAuctionModifiedBidParams? |
| component_auction_modified_bid_params, |
| double? bid_in_seller_currency, |
| uint32? scoring_signals_data_version, |
| url.mojom.Url? debug_loss_report_url, |
| url.mojom.Url? debug_win_report_url, |
| array<PrivateAggregationRequest> pa_requests, |
| array<string> errors); |
| }; |
| |
| // Manages the auction workflow for one loaded FLEDGE seller worklet. |
| // See https://github.com/WICG/turtledove/blob/main/FLEDGE.md |
| // |
| // The SellerWorklet is functionally stateless, so methods are idempotent |
| // and can be called multiple times, in any order, for multiple auctions |
| // using the same worklet. There is no need to wait for one callback to be |
| // invoked before calling another method. There is no guarantee methods will |
| // complete in the order they are invoked. |
| interface SellerWorklet { |
| // Calls the Javascript scoreAd() function to evaluate a bid. No data is |
| // leaked between consecutive invocations of this method, or between |
| // invocations of this method and ReportResult(). |
| // |
| // In the case a worklet needs to fetch trusted scoring signals before |
| // running any Javascript, the method may wait so it can merge several signals |
| // fetched together. See SendPendingSignalsRequests() for more information. |
| // |
| // Arguments: |
| // `ad_metadata_json` JSON representation of the `ad` value returned by the |
| // BidderWorklet that offered the bid. |
| // |
| // `bid` The numeric value of the bid offered by the BidderWorklet. |
| // |
| // `bid_currency` Currency of the bid offered by the BidderWorklet. |
| // |
| // `auction_ad_config_non_shared_params` Values in an AuctionConfig that can |
| // vary between auctions that can share a SellerWorklet. |
| // |
| // `direct_from_seller_seller_signals` The subresource URL of the |
| // DirectFromSellerSignals for the seller, as produced by concatenating the |
| // `directFromSellerSignals` URL prefix field passed from runAdAuction() with |
| // "?sellerSignals". Since this is fetched from a subresource bundle, it may |
| // only be fetched using the URLLoaderFactory passed in when creating the |
| // worklet. |
| // |
| // `direct_from_seller_auction_signals` The subresource URL of the |
| // directFromSellerSignals for the seller and all buyers, as produced by |
| // concatenating the `directFromSellerSignals` URL prefix field passed from |
| // runAdAuction() with "?auctionSignals". Since this is fetched from a |
| // subresource bundle, it may only be fetched using the URLLoaderFactory |
| // passed in when creating the worklet. |
| // |
| // `browser_signals_other_seller` The origin of the other seller associated |
| // with the bid. If this is a component seller worklet, it's the |
| // top-level seller. If this is a top-level seller scoring a bid from a |
| // component auction, it's the seller in the component auction. |
| // Null if this is the top-level seller scoring its own bids. |
| // |
| // `component_expect_bid_currency` If this is a component auction, specifies |
| // what currency the top-level auction expects it to provide, if any. |
| // nullopt for top-level auction. |
| // |
| // `browser_signal_interest_group_owner` The owner of the interest group |
| // that offered the bid. |
| // |
| // `browser_signal_render_url` The `renderUrl` returned by the |
| // BidderWorklet making the bid. |
| // |
| // `browser_signal_ad_component_urls` The `adComponents` array returned by |
| // the BidderWorklet making the bid. |
| // |
| // `browser_signal_bidding_duration_msecs` is the duration the BiddingWorklet |
| // took to generate the bid. Taken as milliseconds to reduce granularity of |
| // timing information passed to an untrusted process. |
| // |
| // `seller_timeout` Restrict the runtime of the seller's scoring script. Any |
| // timeout higher than 500 ms will be clamped to 500 ms before passing in as |
| // `seller_timeout`. Null if not provided by the publisher page. Null will be |
| // passed to the worklet in that case. |
| // |
| // `trace_id` ID of a nestable asynchronous trace event of category `fledge` |
| // to use with tracing calls. |
| // |
| // `score_ad_client` When the ScoreAd completes, successfully or not, its |
| // OnScoreAdComplete() method will be invoked with the results. |
| ScoreAd(string ad_metadata_json, |
| double bid, |
| blink.mojom.AdCurrency? bid_currency, |
| blink.mojom.AuctionAdConfigNonSharedParams |
| auction_ad_config_non_shared_params, |
| url.mojom.Url? direct_from_seller_seller_signals, |
| url.mojom.Url? direct_from_seller_auction_signals, |
| ComponentAuctionOtherSeller? browser_signals_other_seller, |
| blink.mojom.AdCurrency? component_expect_bid_currency, |
| url.mojom.Origin browser_signal_interest_group_owner, |
| url.mojom.Url browser_signal_render_url, |
| array<url.mojom.Url> browser_signal_ad_component_render_urls, |
| uint32 browser_signal_bidding_duration_msecs, |
| mojo_base.mojom.TimeDelta? seller_timeout, |
| uint64 trace_id, |
| pending_remote<ScoreAdClient> score_ad_client); |
| |
| // Hint to the worklet to send a network request for any needed trusted |
| // signals data now. SellerWorklets normally wait briefy for there to be a |
| // number of ScoreAd() calls before requesting trusted scoring signals so the |
| // request can be batched together. This method can be called once all bids |
| // have been generated to minimize the amount of time an auction spends |
| // waiting on trusted signals data once the final bid has been generated. Does |
| // nothing if no trusted scoring signals need to be fetched. |
| SendPendingSignalsRequests(); |
| |
| // Calls the Javascript reportResult() function to get the information needed |
| // to report the result of the auction to the seller. May only be called once |
| // ScoreAd() has successfully scored an ad, which will ensure the worklet has |
| // completed loading. It does not make sense to invoke this with a score not |
| // generated by a previous ScoreAd() call, so this should not limit consumers. |
| // No data is leaked between consecutive invocations of this method, or |
| // between invocations of this method and ScoreAd(). |
| // |
| // Arguments: |
| // `auction_ad_config_non_shared_params` Values in an AuctionConfig that can |
| // vary between auctions that can share a SellerWorklet. |
| // |
| // `direct_from_seller_seller_signals` The subresource URL of the |
| // DirectFromSellerSignals for the seller, as produced by concatenating the |
| // `directFromSellerSignals` URL prefix field passed from runAdAuction() with |
| // "?sellerSignals". Since this is fetched from a subresource bundle, it may |
| // only be fetched using the URLLoaderFactory passed in when creating the |
| // worklet. |
| // |
| // `direct_from_seller_auction_signals` The subresource URL of the |
| // directFromSellerSignals for the seller and all buyers, as produced by |
| // concatenating the `directFromSellerSignals` URL prefix field passed from |
| // runAdAuction() with "?auctionSignals". Since this is fetched from a |
| // subresource bundle, it may only be fetched using the URLLoaderFactory |
| // passed in when creating the worklet. |
| // |
| // `browser_signals_other_seller` The origin of the other seller associated |
| // with the bid. If this is a component seller worklet, it's the |
| // top-level seller. If this is a top-level seller scoring a bid from a |
| // component auction, it's the seller in the component auction. |
| // Null if this is the top-level seller scoring its own bids. |
| // |
| // `browser_signal_interest_group_owner` The owner of the interest group |
| // that offered the winning bid. |
| // |
| // `browser_signal_buyer_and_seller_reporting_id`. If the winning ad |
| // specified buyerAndSellerReportingId, and that ID passed the appropriate |
| // k-anonymity check, a value to set as |
| // browserSignals.buyerAndSellerReportingId will be included here; otherwise |
| // it is nullopt. |
| // |
| // `browser_signal_render_url` The render URL provided by the winning bid. |
| // |
| // `browser_signal_bid` The numeric value of the winning bid. |
| // |
| // `browser_signal_bid_currency` The currency the bid is in. This is either |
| // the sellerCurrency from auction configuration, or unset to denote it's in |
| // the bidder's currency. |
| // |
| // `browser_signal_desirability` The score returned by ScoreAd for the |
| // winning bid. |
| // |
| // `browser_signal_highest_scoring_other_bid` The numeric value of the bid |
| // that got the second highest score, or 0 if it's not available, either |
| // because there is no such thing or because no currency conversion was |
| // performed. |
| // |
| // `browser_signal_highest_scoring_other_bid_currency` The currency associated |
| // with `browser_signal_highest_scoring_other_bid`. This is either the |
| // sellerCurrency from auction configuration, if it's set, or nullopt to |
| // denote it's in the bidder's currency. |
| // |
| // `browser_signals_component_auction_report_result_params` Extra parameters |
| // passed to the component auction's ReportResult() method. Should be null |
| // for top-level sellers. |
| // |
| // `scoring_signals_data_version` The value of the Data-Version header served |
| // with the trusted scoring signals. |
| // |
| // `has_scoring_signals_data_version` True to indicate Data-Version header |
| // was present in the HTTP response for the trusted scoring signals. |
| // TODO(https://crbug.com/657632): Update when optional integers supported. |
| // |
| // `trace_id` ID of a nestable asynchronous trace event of category `fledge` |
| // to use with tracing calls. |
| // |
| // Returns: |
| // `signals_for_winner` The value to pass to the winning bidder's |
| // ReportWin function, as a JSON string. Null if no value is provided. |
| // |
| // `report_url` The URL to request to report the result of the auction to the |
| // seller, if any. |
| // |
| // `ad_beacon_map` The map of ad reporting events to URLs for fenced frame |
| // reporting. |
| // |
| // `pa_requests` The various requests made to the Private Aggregation API. |
| // |
| // `errors` are various error messages to be used for debugging. These are too |
| // sensitive for the renderers to see. `errors` should not be assumed to be |
| // empty if the other values are populated, nor should it be assumed to be |
| // non-empty if the other values are null. |
| ReportResult( |
| blink.mojom.AuctionAdConfigNonSharedParams |
| auction_ad_config_non_shared_params, |
| url.mojom.Url? direct_from_seller_seller_signals, |
| url.mojom.Url? direct_from_seller_auction_signals, |
| ComponentAuctionOtherSeller? browser_signals_other_seller, |
| url.mojom.Origin browser_signal_interest_group_owner, |
| string? browser_signal_buyer_and_seller_reporting_id, |
| url.mojom.Url browser_signal_render_url, |
| double browser_signal_bid, |
| blink.mojom.AdCurrency? browser_signal_bid_currency, |
| double browser_signal_desirability, |
| double browser_signal_highest_scoring_other_bid, |
| blink.mojom.AdCurrency? browser_signal_highest_scoring_other_bid_currency, |
| ComponentAuctionReportResultParams? |
| browser_signals_component_auction_report_result_params, |
| uint32 scoring_signals_data_version, |
| bool has_scoring_signals_data_version, |
| uint64 trace_id) => |
| (string? signals_for_winner, |
| url.mojom.Url? report_url, |
| map<string, url.mojom.Url> ad_beacon_map, |
| array<PrivateAggregationRequest> pa_requests, |
| array<string> error_msgs); |
| |
| // Establishes a debugger connection to the worklet. |
| ConnectDevToolsAgent( |
| pending_associated_receiver<blink.mojom.DevToolsAgent> agent); |
| }; |