// 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 ad group criterion resource.
syntax = "proto3";

package google.ads.googleads.v0.resources;

import "google/ads/googleads/v0/common/criteria.proto";
import "google/ads/googleads/v0/common/custom_parameter.proto";
import "google/ads/googleads/v0/enums/ad_group_criterion_status.proto";
import "google/ads/googleads/v0/enums/bidding_source.proto";
import "google/ads/googleads/v0/enums/criterion_type.proto";
import "google/ads/googleads/v0/enums/quality_score_bucket.proto";
import "google/protobuf/wrappers.proto";

option java_package = "com.google.ads.googleads.v0.resources";
option java_outer_classname = "AdGroupCriterionProto";
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";

// An ad group criterion.
message AdGroupCriterion {

  // The resource name of the ad group criterion.
  // Ad group criterion resource names have the form:
  //
  // `customers/{customer_id}/adGroupCriteria/{ad_group_id}_{criterion_id}`
  string resource_name = 1;

  // The ID of the criterion.
  //
  // This field is ignored for mutates.
  google.protobuf.Int64Value criterion_id = 26;

  // The status of the criterion.
  enums.AdGroupCriterionStatusEnum.AdGroupCriterionStatus status = 3;

  // Information regarding the quality of the criterion.
  QualityInfo quality_info = 4;

  // The ad group to which the criterion belongs.
  //
  // This field must not be used in WHERE clauses.
  google.protobuf.StringValue ad_group = 5;

  // The type of the criterion.
  enums.CriterionTypeEnum.CriterionType type = 25;

  // Whether to target (`false`) or exclude (`true`) the criterion.
  //
  // This field is immutable. To switch a criterion from positive to negative,
  // remove then re-add it.
  google.protobuf.BoolValue negative = 31;

  // The CPC (cost-per-click) bid.
  google.protobuf.Int64Value cpc_bid_micros = 16;

  // The CPM (cost-per-thousand viewable impressions) bid.
  google.protobuf.Int64Value cpm_bid_micros = 17;

  // The CPV (cost-per-view) bid.
  google.protobuf.Int64Value cpv_bid_micros = 24;

  // The CPC bid amount, expressed as a fraction of the advertised price
  // for some good or service. The valid range for the fraction is [0,1) and the
  // value stored here is 1,000,000 * [fraction].
  google.protobuf.Int64Value percent_cpc_bid_micros = 33;

  // The effective CPC (cost-per-click) bid.
  google.protobuf.Int64Value effective_cpc_bid_micros = 18;

  // The effective CPM (cost-per-thousand viewable impressions) bid.
  google.protobuf.Int64Value effective_cpm_bid_micros = 19;

  // The effective CPV (cost-per-view) bid.
  google.protobuf.Int64Value effective_cpv_bid_micros = 20;

  // The effective Percent CPC bid amount.
  google.protobuf.Int64Value effective_percent_cpc_bid_micros = 34;

  // Source of the effective CPC bid.
  enums.BiddingSourceEnum.BiddingSource effective_cpc_bid_source = 21;

  // Source of the effective CPM bid.
  enums.BiddingSourceEnum.BiddingSource effective_cpm_bid_source = 22;

  // Source of the effective CPV bid.
  enums.BiddingSourceEnum.BiddingSource effective_cpv_bid_source = 23;

  // Source of the effective Percent CPC bid.
  enums.BiddingSourceEnum.BiddingSource effective_percent_cpc_bid_source = 35;

  // Estimates for criterion bids at various positions.
  PositionEstimates position_estimates = 10;

  // The list of possible final URLs after all cross-domain redirects for the
  // ad.
  repeated google.protobuf.StringValue final_urls = 11;

  // The URL template for constructing a tracking URL.
  google.protobuf.StringValue tracking_url_template = 13;

  // The list of mappings used to substitute custom parameter tags in a
  // `tracking_url_template`, `final_urls`, or `mobile_final_urls`.
  repeated common.CustomParameter url_custom_parameters = 14;

  // The ad group criterion.
  //
  // Exactly one must be set.
  oneof criterion {

    // Keyword.
    common.KeywordInfo keyword = 27;

    // Listing group.
    common.ListingGroupInfo listing_group = 32;
  }

  // A container for ad group criterion quality information.
  message QualityInfo {

    // The quality score.
    //
    // This field may not be populated if Google does not have enough
    // information to determine a value.
    google.protobuf.Int32Value quality_score = 1;

    // The performance of the ad compared to other advertisers.
    enums.QualityScoreBucketEnum.QualityScoreBucket creative_quality_score = 2;

    // The quality score of the landing page.
    enums.QualityScoreBucketEnum.QualityScoreBucket post_click_quality_score =
      3;

    // The click-through rate compared to that of other advertisers.
    enums.QualityScoreBucketEnum.QualityScoreBucket search_predicted_ctr = 4;
  }

  // Estimates for criterion bids at various positions.
  message PositionEstimates {

    // The estimate of the CPC bid required for ad to be shown on first
    // page of search results.
    google.protobuf.Int64Value first_page_cpc_micros = 1;

    // The estimate of the CPC bid required for ad to be displayed in first
    // position, at the top of the first page of search results.
    google.protobuf.Int64Value first_position_cpc_micros = 2;

    // The estimate of the CPC bid required for ad to be displayed at the top
    // of the first page of search results.
    google.protobuf.Int64Value top_of_page_cpc_micros = 3;
  }
}
