--- v15/services/recommendation_service.proto 2024-02-20 20:29:01.000000000 +0000 +++ v16/services/recommendation_service.proto 2024-02-20 20:29:04.000000000 +0000 @@ -78,11 +85,31 @@ rpc DismissRecommendation(DismissRecommendationRequest) returns (DismissRecommendationResponse) { option (google.api.http) = { - post: "/v15/customers/{customer_id=*}/recommendations:dismiss" + post: "/v16/customers/{customer_id=*}/recommendations:dismiss" body: "*" }; option (google.api.method_signature) = "customer_id,operations"; } + + // Generates Recommendations based off the requested recommendation_types. + // + // List of thrown errors: + // [AuthenticationError]() + // [AuthorizationError]() + // [HeaderError]() + // [InternalError]() + // [QuotaError]() + // [RecommendationError]() + // [RequestError]() + rpc GenerateRecommendations(GenerateRecommendationsRequest) + returns (GenerateRecommendationsResponse) { + option (google.api.http) = { + post: "/v16/customers/{customer_id=*}/recommendations:generate" + body: "*" + }; + option (google.api.method_signature) = + "customer_id,recommendation_types,advertising_channel_type"; + } } // Request message for @@ -306,6 +333,19 @@ optional int64 campaign_budget_amount_micros = 2; } + // Parameters to use when applying a lead form asset recommendation. + message LeadFormAssetParameters { + // Required. Lead form assets to be added. This is a required field. + AdAssetApplyParameters ad_asset_apply_parameters = 1 + [(google.api.field_behavior) = REQUIRED]; + + // If true, the "Submit Lead Form" goal will be set on the target campaign. + // As a result, ads will be shown as lead form creative ads. If false, + // the "Submit Lead Form" goal will not be set on the campaign and ads will + // contain lead form assets. + optional bool set_submit_lead_form_asset_campaign_goal = 2; + } + // The resource name of the recommendation to apply. string resource_name = 1 [(google.api.resource_reference) = { type: "googleads.googleapis.com/Recommendation" @@ -393,6 +433,9 @@ // Parameters to use when applying set target ROAS // recommendation. ForecastingSetTargetRoasParameters set_target_roas = 24; + + // Parameters to use when applying lead form asset recommendation. + LeadFormAssetParameters lead_form_asset = 25; } } @@ -460,3 +503,132 @@ // errors) we return the RPC level error. google.rpc.Status partial_failure_error = 2; } + +// Request message for +// [RecommendationService.GenerateRecommendations][google.ads.googleads.v16.services.RecommendationService.GenerateRecommendations]. +message GenerateRecommendationsRequest { + // Current bidding information of the campaign. Provides a wrapper for + // bidding-related signals that inform recommendations. + message BiddingInfo { + // Current bidding strategy. + // This field is necessary for the following recommendation_types: + // MAXIMIZE_CLICKS_OPT_IN, MAXIMIZE_CONVERSIONS_OPT_IN, + // MAXIMIZE_CONVERSION_VALUE_OPT_IN, SET_TARGET_CPA, SET_TARGET_ROAS, + // TARGET_CPA_OPT_IN, TARGET_ROAS_OPT_IN + optional google.ads.googleads.v16.enums.BiddingStrategyTypeEnum + .BiddingStrategyType bidding_strategy_type = 1; + + // Optional details related to the bidding_strategy_type. + oneof bidding_strategy_target_info { + // Current target_cpa in micros. + // This can be populated for campaigns with a bidding strategy type of + // TARGET_CPA or MAXIMIZE_CONVERSIONS. + int64 target_cpa_micros = 2; + + // Current target_roas. + // This can be populated for campaigns with a bidding strategy type of + // TARGET_ROAS or MAXIMIZE_CONVERSION_VALUE. + double target_roas = 3; + } + } + + // Current AdGroup Information of the campaign. + message AdGroupInfo { + // Optional. AdGroup Type of the AdGroup. + // This field is necessary for the following recommendation_types if + // ad_group_info is set: + // KEYWORD + optional google.ads.googleads.v16.enums.AdGroupTypeEnum.AdGroupType + ad_group_type = 1 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. Current keywords. + // This field is optional for the following recommendation_types if + // ad_group_info is set: + // KEYWORD + repeated google.ads.googleads.v16.common.KeywordInfo keywords = 2 + [(google.api.field_behavior) = OPTIONAL]; + } + + // A keyword seed and a specific url to generate keywords from. + message SeedInfo { + // A specific url to generate ideas from, for example: www.example.com/cars. + optional string url_seed = 2; + + // Optional. Keywords or phrases to generate ideas from, for example: cars + // or "car dealership near me". + repeated string keyword_seeds = 3 [(google.api.field_behavior) = OPTIONAL]; + } + + // Required. The ID of the customer generating recommendations. + string customer_id = 1 [(google.api.field_behavior) = REQUIRED]; + + // Required. List of eligible recommendation_types to generate. If the + // uploaded criteria isn't sufficient to make a recommendation, or the + // campaign is already in the recommended state, no recommendation will be + // returned for that type. Generally, a recommendation is returned if all + // required fields for that recommendation_type are uploaded, but there are + // cases where this is still not sufficient. + // + // The following recommendation_types are supported for recommendation + // generation: + // KEYWORD, MAXIMIZE_CLICKS_OPT_IN, MAXIMIZE_CONVERSIONS_OPT_IN, + // MAXIMIZE_CONVERSION_VALUE_OPT_IN, SET_TARGET_CPA, SET_TARGET_ROAS, + // SITELINK_ASSET, TARGET_CPA_OPT_IN, TARGET_ROAS_OPT_IN + repeated + google.ads.googleads.v16.enums.RecommendationTypeEnum.RecommendationType + recommendation_types = 2 [(google.api.field_behavior) = REQUIRED]; + + // Required. Advertising channel type of the campaign. + // The following advertising_channel_types are supported for recommendation + // generation: + // PERFORMANCE_MAX and SEARCH + google.ads.googleads.v16.enums.AdvertisingChannelTypeEnum + .AdvertisingChannelType advertising_channel_type = 3 + [(google.api.field_behavior) = REQUIRED]; + + // Optional. Number of sitelinks on the campaign. + // This field is necessary for the following recommendation_types: + // SITELINK_ASSET + optional int32 campaign_sitelink_count = 4 + [(google.api.field_behavior) = OPTIONAL]; + + // Optional. Current conversion tracking status. + // This field is necessary for the following recommendation_types: + // MAXIMIZE_CLICKS_OPT_IN, MAXIMIZE_CONVERSIONS_OPT_IN, + // MAXIMIZE_CONVERSION_VALUE_OPT_IN, SET_TARGET_CPA, SET_TARGET_ROAS, + // TARGET_CPA_OPT_IN, TARGET_ROAS_OPT_IN + optional google.ads.googleads.v16.enums.ConversionTrackingStatusEnum + .ConversionTrackingStatus conversion_tracking_status = 5 + [(google.api.field_behavior) = OPTIONAL]; + + // Optional. Current bidding information of the campaign. + // This field is necessary for the following recommendation_types: + // MAXIMIZE_CLICKS_OPT_IN, MAXIMIZE_CONVERSIONS_OPT_IN, + // MAXIMIZE_CONVERSION_VALUE_OPT_IN, SET_TARGET_CPA, SET_TARGET_ROAS, + // TARGET_CPA_OPT_IN, TARGET_ROAS_OPT_IN + optional BiddingInfo bidding_info = 6 + [(google.api.field_behavior) = OPTIONAL]; + + // Optional. Current AdGroup Information. + // Supports information from a single AdGroup. + // This field is optional for the following recommendation_types: + // KEYWORD + repeated AdGroupInfo ad_group_info = 7 + [(google.api.field_behavior) = OPTIONAL]; + + // Optional. Seed information for Keywords. + // This field is necessary for the following recommendation_types: + // KEYWORD + optional SeedInfo seed_info = 8 [(google.api.field_behavior) = OPTIONAL]; +} + +// Response message for +// [RecommendationService.GenerateRecommendations][google.ads.googleads.v16.services.RecommendationService.GenerateRecommendations]. +message GenerateRecommendationsResponse { + // List of generated recommendations from the passed in set of requested + // recommendation_types. If there isn't sufficient data to generate a + // recommendation for the requested recommendation_types, the result set won't + // contain a recommendation for that type. + repeated google.ads.googleads.v16.resources.Recommendation recommendations = + 1; +}
