--- 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; +}
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2024-02-20 UTC.