// Copyright 2018 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.


// Proto file describing the Recommendation resource.
syntax = "proto3";

package google.ads.googleads.v0.resources;

import "google/ads/googleads/v0/common/ad.proto";
import "google/ads/googleads/v0/common/criteria.proto";
import "google/ads/googleads/v0/enums/recommendation_type.proto";
import
  "google/ads/googleads/v0/enums/target_cpa_opt_in_recommendation_goal.proto";
import "google/protobuf/wrappers.proto";

option java_package = "com.google.ads.googleads.v0.resources";
option java_outer_classname = "RecommendationProto";
option java_multiple_files = true;

// Objective-C prefix. Google Ads API.
option objc_class_prefix = "GAA";
option csharp_namespace = "Google.Ads.GoogleAds.V0.Resources";
option php_namespace = "Google\\Ads\\GoogleAds\\V0\\Resources";
option php_metadata_namespace = "Google\\Ads\\GoogleAds\\V0\\Resources";

// A recommendation.
message Recommendation {

  // The resource name of the recommendation.
  //
  // `customers/{customer_id}/recommendations/{recommendation_id}`
  string resource_name = 1;

  // The type of recommendation.
  enums.RecommendationTypeEnum.RecommendationType type = 2;

  // The impact on account performance as a result of applying the
  // recommendation.
  RecommendationImpact impact = 3;

  // The budget targeted by this recommendation. This will be set only when
  // the recommendation affects a single campaign budget.
  //
  // This field must not be used in WHERE clauses.
  //
  // This field will be set for the following recommendation types:
  // CAMPAIGN_BUDGET
  google.protobuf.StringValue campaign_budget = 5;

  // The campaign targeted by this recommendation. This will be set only when
  // the recommendation affects a single campaign.
  //
  // This field must not be used in WHERE clauses.
  //
  // This field will be set for the following recommendation types:
  // KEYWORD, TEXT_AD, TARGET_CPA_OPT_IN
  google.protobuf.StringValue campaign = 6;

  // The ad group targeted by this recommendation. This will be set only when
  // the recommendation affects a single ad group.
  //
  // This field must not be used in WHERE clauses.
  //
  // This field will be set for the following recommendation types:
  // KEYWORD, TEXT_AD
  google.protobuf.StringValue ad_group = 7;

  // The details of recommendation.
  oneof recommendation {

    // The campaign budget recommendation.
    CampaignBudgetRecommendation campaign_budget_recommendation = 4;

    // The keyword recommendation.
    KeywordRecommendation keyword_recommendation = 8;

    // Add expanded text ad recommendation.
    TextAdRecommendation text_ad_recommendation = 9;

    // The TargetCPA opt-in recommendation.
    TargetCpaOptInRecommendation target_cpa_opt_in_recommendation = 10;
  }

  // The impact of making the change as described in the recommendation.
  // Some types of recommendations may not have impact information.
  message RecommendationImpact {

    // Base metrics at the time the recommendation was generated.
    RecommendationMetrics base_metrics = 1;

    // Estimated metrics if the recommendation is applied.
    RecommendationMetrics potential_metrics = 2;
  }

  // Weekly account performance metrics. For some recommendation types, these
  // are averaged over the past 90-day period and hence can be fractional.
  message RecommendationMetrics {

    // Number of ad impressions.
    google.protobuf.DoubleValue impressions = 1;

    // Number of ad clicks.
    google.protobuf.DoubleValue clicks = 2;

    // Cost (in micros) for advertising, in the local currency for the account.
    google.protobuf.Int64Value cost_micros = 3;

    // Number of conversions.
    google.protobuf.DoubleValue conversions = 4;

    // Number of video views for a video ad campaign.
    google.protobuf.DoubleValue video_views = 5;
  }

  // The budget recommendation for budget constrained campaigns.
  message CampaignBudgetRecommendation {

    // The current budget amount in micros.
    google.protobuf.Int64Value current_budget_amount_micros = 1;

    // The recommended budget amount in micros.
    google.protobuf.Int64Value recommended_budget_amount_micros = 2;

    // The budget amounts and associated impact estimates for some values of
    // possible budget amounts.
    repeated CampaignBudgetRecommendationOption budget_options = 3;

    // The impact estimates for a given budget amount.
    message CampaignBudgetRecommendationOption {

      // The budget amount for this option.
      google.protobuf.Int64Value budget_amount_micros = 1;

      // The impact estimate if budget is changed to amount specified in this
      // option.
      RecommendationImpact impact = 2;
    }
  }

  // The keyword recommendation.
  message KeywordRecommendation {

    // The recommended keyword.
    common.KeywordInfo keyword = 1;

    // The recommended CPC (cost-per-click) bid.
    google.protobuf.Int64Value recommended_cpc_bid_micros = 2;
  }

  // The text ad recommendation.
  message TextAdRecommendation {

    // Recommended ad.
    common.Ad ad = 1;

    // Creation date of the recommended ad.
    // YYYY-MM-DD format, e.g., 2018-04-17.
    google.protobuf.StringValue creation_date = 2;

    // Date, if present, is the earliest when the recommendation will be auto
    // applied.
    // YYYY-MM-DD format, e.g., 2018-04-17.
    google.protobuf.StringValue auto_apply_date = 3;
  }

  // The Target CPA opt-in recommendation.
  message TargetCpaOptInRecommendation {

    // The available goals and corresponding options for Target CPA strategy.
    repeated TargetCpaOptInRecommendationOption options = 1;

    // The recommended average CPA target. See required budget amount and impact
    // of using this recommendation in options list.
    google.protobuf.Int64Value recommended_target_cpa_micros = 2;

    // The Target CPA opt-in option with impact estimate.
    message TargetCpaOptInRecommendationOption {

      // The goal achieved by this option.
      enums.TargetCpaOptInRecommendationGoalEnum.TargetCpaOptInRecommendationGoal
        goal = 1;

      // Average CPA target.
      google.protobuf.Int64Value target_cpa_micros = 2;

      // The minimum campaign budget, in local currency for the account,
      // required to achieve the target CPA.
      // Amount is specified in micros, where one million is equivalent to one
      // currency unit.
      google.protobuf.Int64Value required_campaign_budget_amount_micros = 3;

      // The impact estimate if this option is selected.
      RecommendationImpact impact = 4;
    }
  }
}
