generate_bid.proto

// Copyright 2024 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package privacy_sandbox.bidding_auction_servers;

import "apis/privacysandbox/apis/roma/app_api/v1/options.proto";

service GenerateProtectedAudienceBidService {
  option (privacysandbox.apis.roma.app_api.v1.roma_svc_annotation) = {
    name: 'ProtectedAudience GenerateBid Service',
    code_id: "generateprotectedaudiencebid_service_v1",
    description:
      'Service to execute generateBid() UDF in a sandbox in the'
      ' Bidding service for ProtectedAudience',
    cpp_namespace: 'privacy_sandbox::bidding_auction_servers::roma_service',
    roma_app_name: 'GenerateProtectedAudienceBidService',
  };

  rpc GenerateProtectedAudienceBid(GenerateProtectedAudienceBidRequest) returns (GenerateProtectedAudienceBidResponse) {
    option (privacysandbox.apis.roma.app_api.v1.roma_rpc_annotation) = {description:
        'RPC call to generateBid() UDF for a single Protected Audience Custom'
        ' Audience (a.k.a Interest Group).'
};
  }
}

message GenerateProtectedAudienceBidRequest {
  option (privacysandbox.apis.roma.app_api.v1.roma_mesg_annotation) = {description:
      'Request to generateBid() UDF for a Protected Audience Interest Group'
      ' (similar to the parameters in the JS spec for generateBid) for a'
      ' Protected Audience auction.'
};

  ProtectedAudienceInterestGroup interest_group = 1 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'This will be prepared by the Bidding service based on the data received'
      ' in the BuyerInput from the device.'
}];

  string auction_signals = 2 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'Auction signals are sent by the seller in the Auction Config. This can'
      ' be encoded any way by the seller and will be passed as-is to the'
      ' generateBid() UDF.'
}];

  string per_buyer_signals = 3 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'Per buyer signals are sent by the seller in the Auction Config. This can'
      ' be encoded any way by the seller and will be passed as-is to the'
      ' generateBid() UDF.'
}];

  string trusted_bidding_signals = 4 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'This will be passed as the JSON response received from the buyer\'s'
      ' key/value server.'
}];

  oneof ProtectedAudienceDeviceSignals {
    ProtectedAudienceAndroidSignals android_signals = 5 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
        'This will be prepared by the Bidding server based on information'
        ' passed by the Android app.'
}];

    ProtectedAudienceBrowserSignals browser_signals = 6 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
        'This will be prepared by the Bidding server based on information'
        ' passed by the browser on desktop or Android.'
}];
  }

  ServerMetadata server_metadata = 7 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'This will be prepared by the Bidding server and will contain config'
      ' information about the current execution environment.'
}];
}

message ProtectedAudienceInterestGroup {
  option (privacysandbox.apis.roma.app_api.v1.roma_mesg_annotation) = {description: 'Custom Audience (a.k.a Interest Group) for bidding.'};

  string name = 1 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'Unique string that identifies the Custom Audience (a.k.a Interest Group)'
      ' for a buyer.'
}];

  repeated string trusted_bidding_signals_keys = 2 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'Used to fetch real time bidding signals from the buyer\'s key/value'
      ' server included in GenerateBidsRequest.'
}];

  repeated string ad_render_ids = 3 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'Optional. Id of ad_render_url generated by the buyer and passed to the'
      ' client. Then client passes this in InterestGroup if available. Note: If'
      ' the buyer doesn\'t generate the ad_render_id, then their generateBid()'
      ' UDF should dynamically generate the URL for the bid. The winning ad'
      ' render URL returned back to the client will be validated with the'
      ' Interest Group information on the client.'
}];

  repeated string ad_component_render_ids = 4 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'Optional. Id of ad_component_render_url generated by the buyer and'
      ' passed to the client.'
}];

  string user_bidding_signals = 5 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'Optional. User bidding signal that may be ingested during bidding and/or'
      ' filtering.'
}];
}

// (-- LINT.IfChange(android_signals_generate_bid) --)
message ProtectedAudienceAndroidSignals {
  option (privacysandbox.apis.roma.app_api.v1.roma_mesg_annotation) = {description:
      'Information sent from the Android app that the generateBid() UDF may'
      ' want to use or verify.'
};

  string top_level_seller = 1 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description: 'Top level seller origin/domain passed in case of component auctions.'}];
}
// (-- LINT.ThenChange(/api/bidding_auction_servers.proto:android_signals_bidding) --)

// (-- LINT.IfChange(browser_signals_generate_bid) --)
message ProtectedAudienceBrowserSignals {
  option (privacysandbox.apis.roma.app_api.v1.roma_mesg_annotation) = {description:
      'Information sent by the browser on desktop or Android that the'
      ' generateBid() UDF may want to use or verify.'
};

  string top_window_hostname = 1 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description: 'Hostname of the top window.'}];

  string seller = 2 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description: 'Seller origin/domain.'}];

  string top_level_seller = 3 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description: 'Top level seller origin/domain passed in case of component auctions.'}];

  int64 join_count = 4 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description: 'Number of times the Interest Group was joined in the last 30 days.'}];

  int64 bid_count = 5 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'Number of times the Interest Group bid in an auction in the last 30'
      ' days.'
}];

  int64 recency = 6 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'The most recent join time for the Interest Group expressed in'
      ' milliseconds before the containing auctionBlob was requested.'
}];

  string prev_wins = 7 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'Tuple of time-ad pairs for a previous win for the Interest Group that'
      ' occurred in the last 30 days. The time is specified in seconds'
      ' before the containing auctionBlob was requested.'
}];
}
// (-- LINT.ThenChange(/api/bidding_auction_servers.proto:browser_signals_bidding) --)

message ServerMetadata {
  option (privacysandbox.apis.roma.app_api.v1.roma_mesg_annotation) = {description:
      'Config information about the current execution environment for a'
      ' GenerateBidRequest.'
};

  bool debug_reporting_enabled = 1 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'A boolean value which indicates if event level debug reporting is'
      ' enabled or disabled for the request. Adtechs should only return debug'
      ' URLs if this is set to true, otherwise the URLs will be ignored and'
      ' creating these will be wasted compute.'
}];

  bool logging_enabled = 2 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'A boolean value which indicates if logging is enabled or disabled for'
      ' the request. If this is false, the logs returned from the RPC in the'
      ' response will be ignored. Otherwise, these will be outputted to the'
      ' standard logs or included in the response.'
}];
}

message GenerateProtectedAudienceBidResponse {
  option (privacysandbox.apis.roma.app_api.v1.roma_mesg_annotation) = {description:
      'Response to GenerateProtectedAudienceBidRequest with bid(s) for ad'
      ' candidate(s) corresponding to the single Custom Audience (a.k.a'
      ' Interest Group) (similar to the return values from the JS spec for'
      ' generateBid), for a Protected Audience auction.'
};

  repeated ProtectedAudienceBid bids = 1 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'The generateBid() UDF can return a list of bids instead of a single bid.'
      ' This is added for supporting the K-anonymity feature. The maximum'
      ' number of bids allowed to be returned is specified by the seller. When'
      ' K-anonymity is disabled or not implemented, only the first candidate'
      ' bid will be considered.'
}];

  LogMessages log_messages = 2 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'Adtechs can add logs to the response if logging was enabled in the'
      ' request. Logs will be printed out to the console in case of non-prod'
      ' builds and added to the server response in case of debug consented'
      ' requests.'
}];
}

// (-- LINT.IfChange(bid_generate_bid) --)
message ProtectedAudienceBid {
  option (privacysandbox.apis.roma.app_api.v1.roma_mesg_annotation) = {description:
      'Bid for an ad candidate corresponding to a single Custom Audience (a.k.a'
      ' Interest Group).'
};

  string ad = 1 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'Metadata of the ad. Represents an opaque object that is eventually'
      ' passed to the seller\'s scoreAd() UDF. Note: API will be updated'
      ' separately for Component Ads.'
}];

  float bid = 2 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description: 'Bid price corresponding to an ad.'}];

  string render = 3 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description: 'Ad render URL that identifies an ad creative.'}];

  repeated string ad_components = 4 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'List of ad render URLs that identifies ad components. This field must'
      ' not be present if no component_ad_render_id was passed in'
      ' interest_group to the generateBid() UDF.'
}];

  bool allow_component_auction = 5 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description: 'Whether component auction is allowed.'}];

  double ad_cost = 6 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'A numerical value used to pass reporting advertiser click or conversion'
      ' cost from the generateBid() UDF to reportWin(). The precision of this'
      ' number is limited to an 8-bit mantissa and 8-bit exponent, with any'
      ' rounding performed stochastically.'
}];

  int32 modeling_signals = 7 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'A 12-bit integer signal used as input to win reporting URL generation'
      ' for the buyer.'
}];

  string bid_currency = 8 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'Indicates the currency used for the bid price (expressed as ISO 4217'
      ' alpha code).'
}];

  string buyer_reporting_id = 9 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description: 'Optional. buyerReportingId set in buyerReportingMetadata of reportWin().'}];

  DebugReportUrls debug_report_urls = 10 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'Optional field for debug report URLs. This should only be populated by'
      ' adtechs if debug_reporting_enabled was set to true in the request.'
}];

  repeated PrivateAggregateContribution private_aggregation_contributions = 11 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description: 'Private aggregation object.'}];
}
// (-- LINT.ThenChange(/api/bidding_auction_servers.proto:bid_bidding) --)

message DebugReportUrls {
  option (privacysandbox.apis.roma.app_api.v1.roma_mesg_annotation) = {description:
      'URLs to support debug reporting, when auction is won and auction is'
      ' lost.'
};

  string auction_debug_win_url = 1 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'URL to be triggered if the Interest Group wins the auction. If undefined'
      ' or malformed, it will be ignored.'
}];

  string auction_debug_loss_url = 2 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'URL to be triggered if the Interest Group loses the auction. If'
      ' undefined or malformed, it will be ignored.'
}];
}

message PrivateAggregateContribution {
  option (privacysandbox.apis.roma.app_api.v1.roma_mesg_annotation) = {description: 'Represents a private aggregation contribution.'};

  PrivateAggregationBucket bucket = 1 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'Tells the browser how to calculate the bucket for this private'
      ' aggregation contribution.'
}];

  PrivateAggregationValue value = 2 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'Tells the browser how to calculate the value for this private'
      ' aggregation contribution.'
}];

  PrivateAggregationEvent event = 3 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'Populated only for component multi seller auctions and response from'
      ' BFE. This is not expected to be sent to the client for single seller'
      ' and server orchestrated multi seller auctions.'
}];
}

message PrivateAggregationBucket {
  option (privacysandbox.apis.roma.app_api.v1.roma_mesg_annotation) = {description: 'Represents a private aggregation bucket.'};

  oneof bucket {
    Bucket128Bit bucket_128_bit = 1 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description: 'A 128-bit ID that identifies a bucket.'}];

    SignalBucket signal_bucket = 2 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description: 'A signal object that identifies a bucket.'}];
  }
}

message SignalBucket {
  option (privacysandbox.apis.roma.app_api.v1.roma_mesg_annotation) = {description:
      'Represents a private aggregation bucket that has final value dependent'
      ' on post auction information. For more information, see https://github.com/WICG/turtledove/blob/44a00e4e8f02ec03c05075fd994a8abad7b2a6cd/FLEDGE_extended_PA_reporting.md#example-3-understand-the-reason-an-ad-did-not-win.'
};

  BaseValue base_value = 1 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'The name of the auction result value that will dictate the final bucket.'
      ' For instance, bid-reject-reason.'
}];

  double scale = 2 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'Optional scale factor for the bucket. Default value is 1.0. Scale is'
      ' applied before offset is added.'
}];

  BucketOffset offset = 3 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description: 'Optional offset to add to get the final bucket.'}];
}

enum BaseValue {
  option (privacysandbox.apis.roma.app_api.v1.roma_enum_annotation) = {description:
      'Available base values for signalBucket and signalValue. For more'
      ' information, see https://github.com/WICG/turtledove/blob/44a00e4e8f02ec03c05075fd994a8abad7b2a6cd/FLEDGE_extended_PA_reporting.md?plain=1#L192.'
};

  BASE_VALUE_UNSPECIFIED = 0 [(privacysandbox.apis.roma.app_api.v1.roma_enumval_annotation) = {description: 'Base value unspecified.'}];

  BASE_VALUE_WINNING_BID = 1 [(privacysandbox.apis.roma.app_api.v1.roma_enumval_annotation) = {description: 'Base value is the winning bid value.'}];

  BASE_VALUE_HIGHEST_SCORING_OTHER_BID = 2 [(privacysandbox.apis.roma.app_api.v1.roma_enumval_annotation) = {description: 'Base value is the bid value that was scored as second highest.'}];

  BASE_VALUE_SCRIPT_RUN_TIME = 3 [(privacysandbox.apis.roma.app_api.v1.roma_enumval_annotation) = {description:
      'Base value is the milliseconds of CPU time that the calling function'
      ' required, when called.'
}];

  BASE_VALUE_SIGNALS_FETCH_TIME = 4 [(privacysandbox.apis.roma.app_api.v1.roma_enumval_annotation) = {description:
      'Base value is the milliseconds required to fetch the trusted bidding or'
      ' scoring signals, when called from generateBid() or scoreAd()'
      ' respectively.'
}];

  BASE_VALUE_BID_REJECTION_REASON = 5 [(privacysandbox.apis.roma.app_api.v1.roma_enumval_annotation) = {description: 'Base value indicates the reason the bid was rejected.'}];
}

message BucketOffset {
  option (privacysandbox.apis.roma.app_api.v1.roma_mesg_annotation) = {description: 'Optional offset to add to the bucket. Default value is 0.'};

  repeated uint64 value = 1 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'Value of the offset. This can be a 128 bit number. The 1st 64 bits are'
      ' pushed into the array followed by 2nd 64 bits.'
}];

  bool is_negative = 2 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description: 'Indicates whether the offset is negative.'}];
}

message Bucket128Bit {
  option (privacysandbox.apis.roma.app_api.v1.roma_mesg_annotation) = {description: 'Represents a private aggregation bucket identified by a 128-bit ID.'};

  repeated uint64 bucket_128_bits = 1 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'Bucket should support 128 bit int value. The 1st 64 bits are pushed into'
      ' the array followed by 2nd 64 bits.'
}];
}

message PrivateAggregationValue {
  option (privacysandbox.apis.roma.app_api.v1.roma_mesg_annotation) = {description: 'Represents a private aggregation value.'};

  oneof value {
    int32 int_value = 1 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description: 'A non-negative integer value.'}];

    SignalValue extended_value = 2 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description: 'A signal object that identifies a value.'}];
  }
}

message SignalValue {
  option (privacysandbox.apis.roma.app_api.v1.roma_mesg_annotation) = {description:
      'Represents a private aggregation value that has final value dependent on'
      ' post auction information. For more information, see https://github.com/WICG/turtledove/blob/main/FLEDGE_extended_PA_reporting.md#example-2-getting-the-average-bid-gap-for-an-ad.'
};

  BaseValue base_value = 1 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'The name of the auction result value we want to report. For instance,'
      ' winning-bid.'
}];

  double scale = 2 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'Optional scale factor for the value. This is useful for controlling the'
      ' amount of noise added by the aggregation service. Default value is 1.0.'
      ' Scale is applied before offset is added.'
}];

  int32 offset = 3 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description: 'Optional offset to add to get the final value.'}];
}

message PrivateAggregationEvent {
  option (privacysandbox.apis.roma.app_api.v1.roma_mesg_annotation) = {description: 'A private aggregation event.'};

  EventType event_type = 1 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description: 'Type of the event.'}];

  string event_name = 2 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description: 'Name of the event. Only populated in case of CUSTOM events.'}];
}

enum EventType {
  option (privacysandbox.apis.roma.app_api.v1.roma_enum_annotation) = {description: 'Event types to indicate the event for which contribution was made.'};

  EVENT_TYPE_UNSPECIFIED = 0 [(privacysandbox.apis.roma.app_api.v1.roma_enumval_annotation) = {description: 'Event type unspecified.'}];

  EVENT_TYPE_WIN = 1 [(privacysandbox.apis.roma.app_api.v1.roma_enumval_annotation) = {description: 'Event type for contributions made via reserved.win event type.'}];

  EVENT_TYPE_LOSS = 2 [(privacysandbox.apis.roma.app_api.v1.roma_enumval_annotation) = {description: 'Event type for contributions made via reserved.loss event type.'}];

  EVENT_TYPE_ALWAYS = 3 [(privacysandbox.apis.roma.app_api.v1.roma_enumval_annotation) = {description: 'Event type for contributions made via reserved.always event type.'}];

  EVENT_TYPE_CUSTOM = 4 [(privacysandbox.apis.roma.app_api.v1.roma_enumval_annotation) = {description: 'Event type for contributions made with a custom event name.'}];
}

message LogMessages {
  option (privacysandbox.apis.roma.app_api.v1.roma_mesg_annotation) = {description: 'Logs, errors, and warnings populated by the generateBid() UDF.'};

  repeated string logs = 1 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description: 'Optional list of logs.'}];

  repeated string errors = 2 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description: 'Optional list of errors.'}];

  repeated string warnings = 3 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description: 'Optional list of warnings.'}];
}