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_ms = 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 milliseconds'
      ' 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.'}];

  string interest_group_name = 6 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description:
      'Name of the Custom Audience (a.k.a Interest Group) this ad belongs to'
      ' required by the device to validate that a winning remarketing ad'
      ' actually belongs to the Custom Audience (a.k.a Interest Group) as'
      ' stored on-device.'
}];

  double ad_cost = 7 [(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 = 8 [(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 = 9 [(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 = 10 [(privacysandbox.apis.roma.app_api.v1.roma_field_annotation) = {description: 'Optional. buyerReportingId set in buyerReportingMetadata of reportWin().'}];

  DebugReportUrls debug_report_urls = 11 [(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.'
}];
}
// (-- 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 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.'}];
}