--- 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;
+}
