legacy-libs/google-proto-files/google/ads/googleads/v1/resources/recommendation.proto

   1 // Copyright 2019 Google LLC.
   2 //
   3 // Licensed under the Apache License, Version 2.0 (the "License");
   4 // you may not use this file except in compliance with the License.
   5 // You may obtain a copy of the License at
   6 //
   7 //     http://www.apache.org/licenses/LICENSE-2.0
   8 //
   9 // Unless required by applicable law or agreed to in writing, software
  10 // distributed under the License is distributed on an "AS IS" BASIS,
  11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 // See the License for the specific language governing permissions and
  13 // limitations under the License.
  14 //
  15
  16 syntax = "proto3";
  17
  18 package google.ads.googleads.v1.resources;
  19
  20 import "google/ads/googleads/v1/common/criteria.proto";
  21 import "google/ads/googleads/v1/enums/recommendation_type.proto";
  22 import "google/ads/googleads/v1/enums/target_cpa_opt_in_recommendation_goal.proto";
  23 import "google/ads/googleads/v1/resources/ad.proto";
  24 import "google/protobuf/wrappers.proto";
  25 import "google/api/annotations.proto";
  26
  27 option csharp_namespace = "Google.Ads.GoogleAds.V1.Resources";
  28 option go_package = "google.golang.org/genproto/googleapis/ads/googleads/v1/resources;resources";
  29 option java_multiple_files = true;
  30 option java_outer_classname = "RecommendationProto";
  31 option java_package = "com.google.ads.googleads.v1.resources";
  32 option objc_class_prefix = "GAA";
  33 option php_namespace = "Google\\Ads\\GoogleAds\\V1\\Resources";
  34 option ruby_package = "Google::Ads::GoogleAds::V1::Resources";
  35 // Proto file describing the Recommendation resource.
  36
  37 // A recommendation.
  38 message Recommendation {
  39   // The impact of making the change as described in the recommendation.
  40   // Some types of recommendations may not have impact information.
  41   message RecommendationImpact {
  42     // Base metrics at the time the recommendation was generated.
  43     RecommendationMetrics base_metrics = 1;
  44
  45     // Estimated metrics if the recommendation is applied.
  46     RecommendationMetrics potential_metrics = 2;
  47   }
  48
  49   // Weekly account performance metrics. For some recommendation types, these
  50   // are averaged over the past 90-day period and hence can be fractional.
  51   message RecommendationMetrics {
  52     // Number of ad impressions.
  53     google.protobuf.DoubleValue impressions = 1;
  54
  55     // Number of ad clicks.
  56     google.protobuf.DoubleValue clicks = 2;
  57
  58     // Cost (in micros) for advertising, in the local currency for the account.
  59     google.protobuf.Int64Value cost_micros = 3;
  60
  61     // Number of conversions.
  62     google.protobuf.DoubleValue conversions = 4;
  63
  64     // Number of video views for a video ad campaign.
  65     google.protobuf.DoubleValue video_views = 5;
  66   }
  67
  68   // The budget recommendation for budget constrained campaigns.
  69   message CampaignBudgetRecommendation {
  70     // The impact estimates for a given budget amount.
  71     message CampaignBudgetRecommendationOption {
  72       // The budget amount for this option.
  73       google.protobuf.Int64Value budget_amount_micros = 1;
  74
  75       // The impact estimate if budget is changed to amount specified in this
  76       // option.
  77       RecommendationImpact impact = 2;
  78     }
  79
  80     // The current budget amount in micros.
  81     google.protobuf.Int64Value current_budget_amount_micros = 1;
  82
  83     // The recommended budget amount in micros.
  84     google.protobuf.Int64Value recommended_budget_amount_micros = 2;
  85
  86     // The budget amounts and associated impact estimates for some values of
  87     // possible budget amounts.
  88     repeated CampaignBudgetRecommendationOption budget_options = 3;
  89   }
  90
  91   // The keyword recommendation.
  92   message KeywordRecommendation {
  93     // The recommended keyword.
  94     google.ads.googleads.v1.common.KeywordInfo keyword = 1;
  95
  96     // The recommended CPC (cost-per-click) bid.
  97     google.protobuf.Int64Value recommended_cpc_bid_micros = 2;
  98   }
  99
 100   // The Maximize Conversions Opt-In recommendation.
 101   message MaximizeConversionsOptInRecommendation {
 102     // The recommended new budget amount.
 103     google.protobuf.Int64Value recommended_budget_amount_micros = 1;
 104   }
 105
 106   // The Maximize Clicks opt-in recommendation.
 107   message MaximizeClicksOptInRecommendation {
 108     // The recommended new budget amount.
 109     // Only set if the current budget is too high.
 110     google.protobuf.Int64Value recommended_budget_amount_micros = 1;
 111   }
 112
 113   // The text ad recommendation.
 114   message TextAdRecommendation {
 115     // Recommended ad.
 116     Ad ad = 1;
 117
 118     // Creation date of the recommended ad.
 119     // YYYY-MM-DD format, e.g., 2018-04-17.
 120     google.protobuf.StringValue creation_date = 2;
 121
 122     // Date, if present, is the earliest when the recommendation will be auto
 123     // applied.
 124     // YYYY-MM-DD format, e.g., 2018-04-17.
 125     google.protobuf.StringValue auto_apply_date = 3;
 126   }
 127
 128   // The Target CPA opt-in recommendation.
 129   message TargetCpaOptInRecommendation {
 130     // The Target CPA opt-in option with impact estimate.
 131     message TargetCpaOptInRecommendationOption {
 132       // The goal achieved by this option.
 133       google.ads.googleads.v1.enums.TargetCpaOptInRecommendationGoalEnum.TargetCpaOptInRecommendationGoal goal = 1;
 134
 135       // Average CPA target.
 136       google.protobuf.Int64Value target_cpa_micros = 2;
 137
 138       // The minimum campaign budget, in local currency for the account,
 139       // required to achieve the target CPA.
 140       // Amount is specified in micros, where one million is equivalent to one
 141       // currency unit.
 142       google.protobuf.Int64Value required_campaign_budget_amount_micros = 3;
 143
 144       // The impact estimate if this option is selected.
 145       RecommendationImpact impact = 4;
 146     }
 147
 148     // The available goals and corresponding options for Target CPA strategy.
 149     repeated TargetCpaOptInRecommendationOption options = 1;
 150
 151     // The recommended average CPA target. See required budget amount and impact
 152     // of using this recommendation in options list.
 153     google.protobuf.Int64Value recommended_target_cpa_micros = 2;
 154   }
 155
 156   // The Search Partners Opt-In recommendation.
 157   message SearchPartnersOptInRecommendation {
 158
 159   }
 160
 161   // The Optimize Ad Rotation recommendation.
 162   message OptimizeAdRotationRecommendation {
 163
 164   }
 165
 166   // The Enhanced Cost-Per-Click Opt-In recommendation.
 167   message EnhancedCpcOptInRecommendation {
 168
 169   }
 170
 171   // The resource name of the recommendation.
 172   //
 173   // `customers/{customer_id}/recommendations/{recommendation_id}`
 174   string resource_name = 1;
 175
 176   // The type of recommendation.
 177   google.ads.googleads.v1.enums.RecommendationTypeEnum.RecommendationType type = 2;
 178
 179   // The impact on account performance as a result of applying the
 180   // recommendation.
 181   RecommendationImpact impact = 3;
 182
 183   // The budget targeted by this recommendation. This will be set only when
 184   // the recommendation affects a single campaign budget.
 185   //
 186   // This field will be set for the following recommendation types:
 187   // CAMPAIGN_BUDGET
 188   google.protobuf.StringValue campaign_budget = 5;
 189
 190   // The campaign targeted by this recommendation. This will be set only when
 191   // the recommendation affects a single campaign.
 192   //
 193   // This field will be set for the following recommendation types:
 194   // ENHANCED_CPC_OPT_IN, KEYWORD, MAXIMIZE_CLICKS_OPT_IN,
 195   // MAXIMIZE_CONVERSIONS_OPT_IN, OPTIMIZE_AD_ROTATION, SEARCH_PARTNERS_OPT_IN,
 196   // TARGET_CPA_OPT_IN, TEXT_AD
 197   google.protobuf.StringValue campaign = 6;
 198
 199   // The ad group targeted by this recommendation. This will be set only when
 200   // the recommendation affects a single ad group.
 201   //
 202   // This field will be set for the following recommendation types:
 203   // KEYWORD, OPTIMIZE_AD_ROTATION, TEXT_AD
 204   google.protobuf.StringValue ad_group = 7;
 205
 206   // Whether the recommendation is dismissed or not.
 207   google.protobuf.BoolValue dismissed = 13;
 208
 209   // The details of recommendation.
 210   oneof recommendation {
 211     // The campaign budget recommendation.
 212     CampaignBudgetRecommendation campaign_budget_recommendation = 4;
 213
 214     // The keyword recommendation.
 215     KeywordRecommendation keyword_recommendation = 8;
 216
 217     // Add expanded text ad recommendation.
 218     TextAdRecommendation text_ad_recommendation = 9;
 219
 220     // The TargetCPA opt-in recommendation.
 221     TargetCpaOptInRecommendation target_cpa_opt_in_recommendation = 10;
 222
 223     // The MaximizeConversions Opt-In recommendation.
 224     MaximizeConversionsOptInRecommendation maximize_conversions_opt_in_recommendation = 11;
 225
 226     // The Enhanced Cost-Per-Click Opt-In recommendation.
 227     EnhancedCpcOptInRecommendation enhanced_cpc_opt_in_recommendation = 12;
 228
 229     // The Search Partners Opt-In recommendation.
 230     SearchPartnersOptInRecommendation search_partners_opt_in_recommendation = 14;
 231
 232     // The MaximizeClicks Opt-In recommendation.
 233     MaximizeClicksOptInRecommendation maximize_clicks_opt_in_recommendation = 15;
 234
 235     // The Optimize Ad Rotation recommendation.
 236     OptimizeAdRotationRecommendation optimize_ad_rotation_recommendation = 16;
 237   }
 238 }