xref: /aosp_15_r20/external/googleapis/google/ads/admob/v1/admob_resources.proto (revision d5c09012810ac0c9f33fe448fb6da8260d444cc9)

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

syntax = "proto3";

package google.ads.admob.v1;

import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/type/date.proto";

option go_package = "google.golang.org/genproto/googleapis/ads/admob/v1;admob";
option java_outer_classname = "AdMobResourcesProto";
option java_package = "com.google.ads.admob.v1";

// The sorting order.
enum SortOrder {
  // Default value for an unset field. Do not use.
  SORT_ORDER_UNSPECIFIED = 0;

  // Sort dimension value or metric value in ascending order.
  ASCENDING = 1;

  // Sort dimension value or metric value in descending order.
  DESCENDING = 2;
}

// A publisher account contains information relevant to the use of this API,
// such as the time zone used for the reports.
message PublisherAccount {
  option (google.api.resource) = {
    type: "admob.googleapis.com/PublisherAccount"
    pattern: "accounts/{publisher}"
  };

  // Resource name of this account.
  // Format is accounts/{publisher_id}.
  string name = 1;

  // The unique ID by which this publisher account can be identified
  // in the API requests (for example, pub-1234567890).
  string publisher_id = 2;

  // The time zone that is used in reports that are generated for this account.
  // The value is a time-zone ID as specified by the CLDR project,
  // for example, "America/Los_Angeles".
  string reporting_time_zone = 3;

  // Currency code of the earning-related metrics, which is the 3-letter code
  // defined in ISO 4217. The daily average rate is used for the currency
  // conversion.
  string currency_code = 4;
}

// The specification for generating an AdMob Network report.
// For example, the specification to get clicks and estimated earnings for only
// the 'US' and 'CN' countries can look like the following example:
//
//     {
//       'date_range': {
//         'start_date': {'year': 2018, 'month': 9, 'day': 1},
//         'end_date': {'year': 2018, 'month': 9, 'day': 30}
//       },
//       'dimensions': ['DATE', 'APP', 'COUNTRY'],
//       'metrics': ['CLICKS', 'ESTIMATED_EARNINGS'],
//       'dimension_filters': [
//         {
//           'dimension': 'COUNTRY',
//           'matches_any': {'values': [{'value': 'US', 'value': 'CN'}]}
//         }
//       ],
//       'sort_conditions': [
//         {'dimension':'APP', order: 'ASCENDING'},
//         {'metric':'CLICKS', order: 'DESCENDING'}
//       ],
//       'localization_settings': {
//         'currency_code': 'USD',
//         'language_code': 'en-US'
//       }
//     }
//
// For a better understanding, you can treat the preceding specification like
// the following pseudo SQL:
//
//     SELECT DATE, APP, COUNTRY, CLICKS, ESTIMATED_EARNINGS
//     FROM NETWORK_REPORT
//     WHERE DATE >= '2018-09-01' AND DATE <= '2018-09-30'
//         AND COUNTRY IN ('US', 'CN')
//     GROUP BY DATE, APP, COUNTRY
//     ORDER BY APP ASC, CLICKS DESC;
message NetworkReportSpec {
  // Describes which report rows to match based on their dimension values.
  message DimensionFilter {
    // Filter operator to be applied.
    oneof operator {
      // Matches a row if its value for the specified dimension is in one of the
      // values specified in this condition.
      StringList matches_any = 2;
    }

    // Applies the filter criterion to the specified dimension.
    Dimension dimension = 1;
  }

  // Sorting direction to be applied on a dimension or a metric.
  message SortCondition {
    // Identifies which values to sort on.
    oneof sort_on {
      // Sort by the specified dimension.
      Dimension dimension = 1;

      // Sort by the specified metric.
      Metric metric = 2;
    }

    // Sorting order of the dimension or metric.
    SortOrder order = 3;
  }

  // The dimensions of the network report. Dimensions are data attributes to
  // break down or refine the quantitative measurements (metrics) by certain
  // attributes, such as the ad format or the platform an ad was viewed on.
  enum Dimension {
    // Default value for an unset field. Do not use.
    DIMENSION_UNSPECIFIED = 0;

    // A date in the YYYY-MM-DD format (for example, "2018-12-21"). Requests can
    // specify at most one time dimension.
    DATE = 1;

    // A month in the YYYY-MM format (for example, "2018-12"). Requests can
    // specify at most one time dimension.
    MONTH = 2;

    // The date of the first day of a week in the YYYY-MM-DD format
    // (for example, "2018-12-21"). Requests can specify at most one time
    // dimension.
    WEEK = 3;

    // The unique ID of the ad unit (for example, "ca-app-pub-1234/1234").
    // If AD_UNIT dimension is specified, then APP is included automatically.
    AD_UNIT = 4;

    // The unique ID of the mobile application (for example,
    // "ca-app-pub-1234~1234").
    APP = 5;

    // Type of the ad (for example, "text" or "image"), an ad delivery
    // dimension.
    //
    // **Warning:** The dimension is incompatible with
    // [AD_REQUESTS](#Metric.ENUM_VALUES.AD_REQUESTS),
    // [MATCH_RATE](#Metric.ENUM_VALUES.MATCH_RATE) and
    // [IMPRESSION_RPM](#Metric.ENUM_VALUES.IMPRESSION_RPM) metrics.
    AD_TYPE = 6;

    // CLDR country code of the place where the ad views/clicks occur (for
    // example, "US" or "FR"). This is a geography dimension.
    COUNTRY = 7;

    // Format of the ad unit (for example, "banner", "native"), an ad delivery
    // dimension.
    FORMAT = 8;

    // Mobile OS platform of the app (for example, "Android" or "iOS").
    PLATFORM = 9;
  }

  // The metrics of the network report. Metrics are quantitative measurements
  // indicating how the publisher business is performing. They are aggregated
  // from the individual ad events and grouped by the report dimensions. The
  // metric value is either integer, or decimal (without rounding).
  enum Metric {
    // Default value for an unset field. Do not use.
    METRIC_UNSPECIFIED = 0;

    // The number of ad requests. The value is an integer.
    //
    // **Warning:** The metric is incompatible with
    // [AD_TYPE](#Dimension.ENUM_VALUES.AD_TYPE) dimension.
    AD_REQUESTS = 1;

    // The number of times a user clicks an ad. The value is an integer.
    CLICKS = 2;

    // The estimated earnings of the AdMob publisher. The currency unit (USD,
    // EUR, or other) of the earning metrics are determined by the localization
    // setting for currency. The amount is in micros. For example, $6.50 would
    // be represented as 6500000.
    ESTIMATED_EARNINGS = 3;

    // The total number of ads shown to users. The value is an integer.
    IMPRESSIONS = 4;

    // The ratio of clicks over impressions. The value is a double precision
    // (approximate) decimal value.
    IMPRESSION_CTR = 5;

    // The estimated earnings per thousand ad impressions. The value is in
    // micros. For example, $1.03 would be represented as 1030000.
    //
    // **Warning:** The metric is incompatible with
    // [AD_TYPE](#Dimension.ENUM_VALUES.AD_TYPE) dimension.
    IMPRESSION_RPM = 6;

    // The number of times ads are returned in response to a request. The value
    // is an integer.
    MATCHED_REQUESTS = 7;

    // The ratio of matched ad requests over the total ad requests. The value is
    // a double precision (approximate) decimal value.
    //
    // **Warning:** The metric is incompatible with
    // [AD_TYPE](#Dimension.ENUM_VALUES.AD_TYPE) dimension.
    MATCH_RATE = 8;

    // The ratio of ads that are displayed over ads that are returned, defined
    // as impressions / matched requests. The value is a double precision
    // (approximate) decimal value.
    SHOW_RATE = 9;
  }

  // The date range for which the report is generated.
  DateRange date_range = 1;

  // List of dimensions of the report. The value combination of these dimensions
  // determines the row of the report. If no dimensions are specified, the
  // report returns a single row of requested metrics for the entire account.
  repeated Dimension dimensions = 2;

  // List of metrics of the report. A report must specify at least one metric.
  repeated Metric metrics = 3;

  // Describes which report rows to match based on their dimension values.
  repeated DimensionFilter dimension_filters = 4;

  // Describes the sorting of report rows. The order of the condition in the
  // list defines its precedence; the earlier the condition, the higher its
  // precedence. If no sort conditions are specified, the row ordering is
  // undefined.
  repeated SortCondition sort_conditions = 5;

  // Localization settings of the report.
  LocalizationSettings localization_settings = 6;

  // Maximum number of report data rows to return. If the value is not set, the
  // API returns as many rows as possible, up to 100000. Acceptable values are
  // 1-100000, inclusive. Any other values are treated as 100000.
  int32 max_report_rows = 7;

  // A report time zone. Accepts an IANA TZ name values, such as
  // "America/Los_Angeles."  If no time zone is defined, the account default
  // takes effect. Check default value by the get account action.
  //
  // **Warning:** The "America/Los_Angeles" is the only supported value at
  // the moment.
  string time_zone = 8;
}

// The specification for generating an AdMob Mediation report.
// For example, the specification to get observed ECPM sliced by ad source and
// app for the 'US' and 'CN' countries can look like the following example:
//
//     {
//       "date_range": {
//         "start_date": {"year": 2018, "month": 9, "day": 1},
//         "end_date": {"year": 2018, "month": 9, "day": 30}
//       },
//       "dimensions": ["AD_SOURCE", "APP", "COUNTRY"],
//       "metrics": ["OBSERVED_ECPM"],
//       "dimension_filters": [
//         {
//           "dimension": "COUNTRY",
//           "matches_any": {"values": [{"value": "US", "value": "CN"}]}
//         }
//       ],
//       "sort_conditions": [
//         {"dimension":"APP", order: "ASCENDING"}
//       ],
//       "localization_settings": {
//         "currency_code": "USD",
//         "language_code": "en-US"
//       }
//     }
//
// For a better understanding, you can treat the preceding specification like
// the following pseudo SQL:
//
//     SELECT AD_SOURCE, APP, COUNTRY, OBSERVED_ECPM
//     FROM MEDIATION_REPORT
//     WHERE DATE >= '2018-09-01' AND DATE <= '2018-09-30'
//         AND COUNTRY IN ('US', 'CN')
//     GROUP BY AD_SOURCE, APP, COUNTRY
//     ORDER BY APP ASC;
message MediationReportSpec {
  // Describes which report rows to match based on their dimension values.
  message DimensionFilter {
    // Filter operator to be applied.
    oneof operator {
      // Matches a row if its value for the specified dimension is in one of the
      // values specified in this condition.
      StringList matches_any = 2;
    }

    // Applies the filter criterion to the specified dimension.
    Dimension dimension = 1;
  }

  // Sorting direction to be applied on a dimension or a metric.
  message SortCondition {
    // Identifies which values to sort on.
    oneof sort_on {
      // Sort by the specified dimension.
      Dimension dimension = 1;

      // Sort by the specified metric.
      Metric metric = 2;
    }

    // Sorting order of the dimension or metric.
    SortOrder order = 3;
  }

  // The dimensions of the mediation report. Dimensions are data attributes to
  // break down or refine the quantitative measurements (metrics) by certain
  // attributes, such as the ad format or the platform an ad was viewed on.
  enum Dimension {
    // Default value for an unset field. Do not use.
    DIMENSION_UNSPECIFIED = 0;

    // A date in the YYYY-MM-DD format (for example, "2018-12-21"). Requests can
    // specify at most one time dimension.
    DATE = 1;

    // A month in the YYYY-MM format (for example, "2018-12"). Requests can
    // specify at most one time dimension.
    MONTH = 2;

    // The date of the first day of a week in the YYYY-MM-DD format
    // (for example, "2018-12-21"). Requests can specify at most one time
    // dimension.
    WEEK = 3;

    // The [unique ID of the ad source](/admob/api/v1/ad_sources) (for example,
    // "5450213213286189855" and "AdMob Network" as label value).
    AD_SOURCE = 4;

    // The unique ID of the ad source instance (for example,
    // "ca-app-pub-1234#5678" and "AdMob (default)" as label value).
    AD_SOURCE_INSTANCE = 5;

    // The unique ID of the ad unit (for example, "ca-app-pub-1234/8790").
    // If AD_UNIT dimension is specified, then APP is included automatically.
    AD_UNIT = 6;

    // The unique ID of the mobile application (for example,
    // "ca-app-pub-1234~1234").
    APP = 7;

    // The unique ID of the mediation group (for example,
    // "ca-app-pub-1234:mg:1234" and "AdMob (default)" as label value).
    MEDIATION_GROUP = 11;

    // CLDR country code of the place where the ad views/clicks occur (for
    // example, "US" or "FR"). This is a geography dimension.
    COUNTRY = 8;

    // Format of the ad unit (for example, "banner", "native"), an ad delivery
    // dimension.
    FORMAT = 9;

    // Mobile OS platform of the app (for example, "Android" or "iOS").
    PLATFORM = 10;
  }

  // The metrics of the mediation report. Metrics are quantitative measurements
  // indicating how the publisher business is performing. They are aggregated
  // from the individual ad events and grouped by the report dimensions. The
  // metric value is either integer, or decimal (without rounding).
  enum Metric {
    // Default value for an unset field. Do not use.
    METRIC_UNSPECIFIED = 0;

    // The number of requests. The value is an integer.
    AD_REQUESTS = 1;

    // The number of times a user clicks an ad. The value is an integer.
    CLICKS = 2;

    // The estimated earnings of the AdMob publisher. The currency unit (USD,
    // EUR, or other) of the earning metrics are determined by the localization
    // setting for currency. The amount is in micros. For example, $6.50 would
    // be represented as 6500000.
    //
    // Estimated earnings per mediation group and per ad source instance level
    // is supported dating back to October 20, 2019. Third-party estimated
    // earnings will show 0 for dates prior to October 20, 2019.
    ESTIMATED_EARNINGS = 3;

    // The total number of ads shown to users. The value is an integer.
    IMPRESSIONS = 4;

    // The ratio of clicks over impressions. The value is a double precision
    // (approximate) decimal value.
    IMPRESSION_CTR = 5;

    // The number of times ads are returned in response to a request. The value
    // is an integer.
    MATCHED_REQUESTS = 6;

    // The ratio of matched ad requests over the total ad requests. The value is
    // a double precision (approximate) decimal value.
    MATCH_RATE = 7;

    // The third-party ad network's estimated average eCPM. The currency unit
    // (USD, EUR, or other) of the earning metrics are determined by the
    // localization setting for currency. The amount is in micros. For example,
    // $2.30 would be represented as 2300000.
    //
    // The estimated average eCPM per mediation group and per ad source instance
    // level is supported dating back to October 20, 2019. Third-party estimated
    // average eCPM will show 0 for dates prior to October 20, 2019.
    OBSERVED_ECPM = 8;
  }

  // The date range for which the report is generated.
  DateRange date_range = 1;

  // List of dimensions of the report. The value combination of these dimensions
  // determines the row of the report. If no dimensions are specified, the
  // report returns a single row of requested metrics for the entire account.
  repeated Dimension dimensions = 2;

  // List of metrics of the report. A report must specify at least one metric.
  repeated Metric metrics = 3;

  // Describes which report rows to match based on their dimension values.
  repeated DimensionFilter dimension_filters = 4;

  // Describes the sorting of report rows. The order of the condition in the
  // list defines its precedence; the earlier the condition, the higher its
  // precedence. If no sort conditions are specified, the row ordering is
  // undefined.
  repeated SortCondition sort_conditions = 5;

  // Localization settings of the report.
  LocalizationSettings localization_settings = 6;

  // Maximum number of report data rows to return. If the value is not set, the
  // API returns as many rows as possible, up to 100000. Acceptable values are
  // 1-100000, inclusive. Any other values are treated as 100000.
  int32 max_report_rows = 7;

  // A report time zone. Accepts an IANA TZ name values, such as
  // "America/Los_Angeles."  If no time zone is defined, the account default
  // takes effect. Check default value by the get account action.
  //
  // **Warning:** The "America/Los_Angeles" is the only supported value at
  // the moment.
  string time_zone = 8;
}

// A row of the returning report.
message ReportRow {
  // Representation of a dimension value.
  message DimensionValue {
    // Dimension value in the format specified in the report's spec Dimension
    // enum.
    string value = 1;

    // The localized string representation of the value. If unspecified, the
    // display label should be derived from the value.
    string display_label = 2;
  }

  // Representation of a metric value.
  message MetricValue {
    // Metric value in the format specified in the report's spec Metric enum
    // name.
    oneof value {
      // Metric integer value.
      int64 integer_value = 1;

      // Double precision (approximate) decimal values. Rates are from 0 to 1.
      double double_value = 2;

      // Amount in micros. One million is equivalent to one unit. Currency value
      // is in the unit (USD, EUR or other) specified by the request.
      // For example, $6.50 whould be represented as 6500000 micros.
      int64 micros_value = 3;
    }
  }

  // Map of dimension values in a row, with keys as enum name of the dimensions.
  map<string, DimensionValue> dimension_values = 1;

  // Map of metric values in a row, with keys as enum name of the metrics. If
  // a metric being requested has no value returned, the map will not include
  // it.
  map<string, MetricValue> metric_values = 2;
}

// Warnings associated with generation of the report.
message ReportWarning {
  // Warning type.
  enum Type {
    // Default value for an unset field. Do not use.
    TYPE_UNSPECIFIED = 0;

    // Some data in this report is aggregated based on a time zone different
    // from the requested time zone. This could happen if a local time-zone
    // report has the start time before the last time this time zone changed.
    // The description field will contain the date of the last time zone
    // change.
    DATA_BEFORE_ACCOUNT_TIMEZONE_CHANGE = 1;

    // There is an unusual delay in processing the source data for the
    // requested date range. The report results might be less up to date than
    // usual. AdMob is aware of the issue and is actively working to resolve
    // it.
    DATA_DELAYED = 2;

    // Warnings that are exposed without a specific type. Useful when new
    // warning types are added but the API is not changed yet.
    OTHER = 3;

    // The currency being requested is not the account currency. The earning
    // metrics will be based on the requested currency, and thus not a good
    // estimation of the final payment anymore, due to the currency rate
    // fluctuation.
    REPORT_CURRENCY_NOT_ACCOUNT_CURRENCY = 4;
  }

  // Type of the warning.
  Type type = 1;

  // Describes the details of the warning message, in English.
  string description = 2;
}

// Groups data helps to treat the generated report. Always sent as a first
// message in the stream response.
message ReportHeader {
  // The date range for which the report is generated. This is identical to the
  // range specified in the report request.
  DateRange date_range = 1;

  // Localization settings of the report. This is identical to the settings
  // in the report request.
  LocalizationSettings localization_settings = 2;

  // The report time zone. The value is a time-zone ID as specified by the CLDR
  // project, for example, "America/Los_Angeles".
  string reporting_time_zone = 3;
}

// Groups data available after report generation, for example, warnings and row
// counts. Always sent as the last message in the stream response.
message ReportFooter {
  // Warnings associated with generation of the report.
  repeated ReportWarning warnings = 1;

  // Total number of rows that matched the request.
  //
  // Warning: This count does NOT always match the number of rows in the
  // response. Do not make that assumption when processing the response.
  int64 matching_row_count = 2;
}

// Specification of a single date range. Both dates are inclusive.
message DateRange {
  // Start date of the date range, inclusive. Must be less than or equal to the
  // end date.
  google.type.Date start_date = 1;

  // End date of the date range, inclusive. Must be greater than or equal to the
  // start date.
  google.type.Date end_date = 2;
}

// Localization settings for reports, such as currency and language. It affects
// how metrics are calculated.
message LocalizationSettings {
  // Currency code of the earning related metrics, which is the 3-letter code
  // defined in ISO 4217. The daily average rate is used for the currency
  // conversion. Defaults to the account currency code if unspecified.
  string currency_code = 1;

  // Language used for any localized text, such as some dimension value display
  // labels. The language tag defined in the IETF BCP47. Defaults to 'en-US' if
  // unspecified.
  string language_code = 2;
}

// List of string values.
message StringList {
  // The string values.
  repeated string values = 1;
}