google/ads/admanager/v1/ad_unit_service.proto

// Copyright 2023 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.admanager.v1;

import "google/ads/admanager/v1/ad_unit_enums.proto";
import "google/ads/admanager/v1/ad_unit_size.proto";
import "google/ads/admanager/v1/applied_label.proto";
import "google/ads/admanager/v1/frequency_cap.proto";
import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";

option csharp_namespace = "Google.Ads.AdManager.V1";
option go_package = "google.golang.org/genproto/googleapis/ads/admanager/v1;admanager";
option java_multiple_files = true;
option java_outer_classname = "AdUnitServiceProto";
option java_package = "com.google.ads.admanager.v1";
option objc_class_prefix = "GAA";
option php_namespace = "Google\\Ads\\AdManager\\V1";

// Provides methods for handling AdUnit objects.
service AdUnitService {
  option (google.api.default_host) = "admanager.googleapis.com";

  // API to retrieve an AdUnit object.
  rpc GetAdUnit(GetAdUnitRequest) returns (AdUnit) {
    option (google.api.http) = {
      get: "/v1/{name=networks/*/adUnits/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // API to retrieve a list of AdUnit objects.
  rpc ListAdUnits(ListAdUnitsRequest) returns (ListAdUnitsResponse) {
    option (google.api.http) = {
      get: "/v1/{parent=networks/*}/adUnits"
    };
    option (google.api.method_signature) = "parent";
  }
}

// The AdUnit resource.
message AdUnit {
  option (google.api.resource) = {
    type: "admanager.googleapis.com/AdUnit"
    pattern: "networks/{network_code}/adUnits/{ad_unit}"
    plural: "adUnits"
    singular: "adUnit"
  };

  // The status of an AdUnit.
  enum Status {
    // Default value. This value is unused.
    STATUS_UNSPECIFIED = 0;

    // The ad unit is active, available for targeting, and serving.
    ACTIVE = 1;

    // The ad unit will be visible in the UI, but ignored by serving.
    INACTIVE = 2;

    // The ad unit will be hidden in the UI and ignored by serving.
    ARCHIVED = 3;
  }

  // Identifier. The resource name of the AdUnit.
  // Format: `networks/{network_code}/adUnits/{ad_unit_id}`
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  // Output only. AdUnit ID.
  int64 ad_unit_id = 15 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Required. Immutable. The AdUnit's parent. Every ad unit has a parent except
  // for the root ad unit, which is created by Google. Format:
  // "networks/{network_code}/adUnits/{ad_unit_id}"
  string parent_ad_unit = 10 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.field_behavior) = IMMUTABLE,
    (google.api.resource_reference) = {
      type: "admanager.googleapis.com/AdUnit"
    }
  ];

  // Output only. The path to this AdUnit in the ad unit hierarchy represented
  // as a list from the root to this ad unit's parent. For root ad units, this
  // list is empty.
  repeated AdUnitParent parent_path = 11
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Required. The display name of the ad unit. Its maximum length is 255
  // characters.
  string display_name = 9 [(google.api.field_behavior) = REQUIRED];

  // Immutable. A string used to uniquely identify the ad unit for the purposes
  // of serving the ad. This attribute is optional and can be set during ad unit
  // creation. If it is not provided, it will be assigned by Google based off of
  // the ad unit ID.
  string ad_unit_code = 2 [(google.api.field_behavior) = IMMUTABLE];

  // Output only. The status of this ad unit.  It defaults to ACTIVE.
  Status status = 13 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Non-empty default. The value to use for the HTML link's target attribute.
  // This value will be interpreted as TOP if left blank.
  TargetWindowEnum.TargetWindow target_window = 12
      [(google.api.field_behavior) = NON_EMPTY_DEFAULT];

  // Optional. The resource names of Teams directly applied to this AdUnit.
  // Format: "networks/{network_code}/teams/{team_id}"
  repeated string applied_teams = 3 [
    (google.api.field_behavior) = OPTIONAL,
    (google.api.resource_reference) = { type: "admanager.googleapis.com/Team" }
  ];

  // Output only. The resource names of all Teams that this AdUnit is on as well
  // as those inherited from parent AdUnits. Format:
  // "networks/{network_code}/teams/{team_id}"
  repeated string teams = 4 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.resource_reference) = { type: "admanager.googleapis.com/Team" }
  ];

  // Optional. A description of the ad unit. The maximum length is 65,535
  // characters.
  string description = 5 [(google.api.field_behavior) = OPTIONAL];

  // Optional. If this field is set to true, then the AdUnit will not be
  // implicitly targeted when its parent is. Traffickers must explicitly
  // target such an AdUnit or else no line items will serve to it. This
  // feature is only available for Ad Manager 360 accounts.
  bool explicitly_targeted = 6 [(google.api.field_behavior) = OPTIONAL];

  // Output only. This field is set to true if the ad unit has any children.
  bool has_children = 7 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The instant this AdUnit was last modified.
  google.protobuf.Timestamp update_time = 8
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. The sizes that can be served inside this ad unit.
  repeated AdUnitSize ad_unit_sizes = 14
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Determines what set top box video on demand channel this ad unit
  // corresponds to in an external set top box ad campaign system.
  string external_set_top_box_channel_id = 17
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. The duration after which an Ad Unit will automatically refresh.
  // This is only valid for ad units in mobile apps. If not set, the ad unit
  // will not refresh.
  google.protobuf.Duration refresh_delay = 19
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. The ID of the CTV application that this ad unit is within.
  int64 ctv_application_id = 20 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The set of labels applied directly to this ad unit.
  repeated AppliedLabel applied_labels = 21
      [(google.api.field_behavior) = OPTIONAL];

  // Output only. Contains the set of labels applied directly to the ad unit as
  // well as those inherited from the parent ad units. If a label has been
  // negated, only the negated label is returned. This field is readonly and is
  // assigned by Google.
  repeated AppliedLabel effective_applied_labels = 22
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. The set of label frequency caps applied directly to this ad unit.
  // There is a limit of 10 label frequency caps per ad unit.
  repeated LabelFrequencyCap applied_label_frequency_caps = 23
      [(google.api.field_behavior) = OPTIONAL];

  // Output only. The label frequency caps applied directly to the ad unit as
  // well as those inherited from parent ad units.
  repeated LabelFrequencyCap effective_label_frequency_caps = 24
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. The smart size mode for this ad unit. This attribute is optional
  // and defaults to SmartSizeMode.NONE for fixed sizes.
  SmartSizeModeEnum.SmartSizeMode smart_size_mode = 25
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. The value of AdSense enabled directly applied to this ad unit.
  // This attribute is optional and if not specified this ad unit will inherit
  // the value of effectiveAdsenseEnabled from its ancestors.
  AppliedAdsenseEnabledEnum.AppliedAdsenseEnabled applied_adsense_enabled = 26
      [(google.api.field_behavior) = OPTIONAL];

  // Output only. Specifies whether or not the AdUnit is enabled for serving ads
  // from the AdSense content network. This attribute defaults to the ad unit's
  // parent or ancestor's setting if one has been set. If no ancestor of the ad
  // unit has set appliedAdsenseEnabled, the attribute is defaulted to true.
  bool effective_adsense_enabled = 27
      [(google.api.field_behavior) = OUTPUT_ONLY];
}

// The summary of a parent AdUnit.
message AdUnitParent {
  // Output only. The parent of the current AdUnit
  // Format: `networks/{network_code}/adUnits/{ad_unit_id}`
  string parent_ad_unit = 1 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.resource_reference) = {
      type: "admanager.googleapis.com/AdUnit"
    }
  ];

  // Output only. The display name of the parent AdUnit.
  string display_name = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. A string used to uniquely identify the ad unit for the
  // purposes of serving the ad.
  string ad_unit_code = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Wrapper message for
// [TargetWindow][google.ads.admanager.v1.TargetWindowEnum.TargetWindow].
message TargetWindowEnum {
  // Corresponds to an HTML link's target attribute.
  // See http://www.w3.org/TR/html401/present/frames.html#adef-target
  enum TargetWindow {
    // Default value. This value is unused.
    TARGET_WINDOW_UNSPECIFIED = 0;

    // Specifies that the link should open in the full body of the page.
    TOP = 1;

    // Specifies that the link should open in a new window.
    BLANK = 2;
  }
}

// Frequency cap using a label.
message LabelFrequencyCap {
  // The label to used for frequency capping.
  // Format: "networks/{network_code}/labels/{label_id}"
  string label = 1;

  // The frequency cap.
  FrequencyCap frequency_cap = 2;
}

// Wrapper message for
// [SmartSizeMode][google.ads.admanager.v1.SmartSizeModeEnum.SmartSizeMode].
message SmartSizeModeEnum {
  // The smart size mode for this ad unit. This attribute is optional and
  // defaults to SmartSizeMode.NONE for fixed sizes.
  enum SmartSizeMode {
    // Default value. This value is unused.
    SMART_SIZE_MODE_UNSPECIFIED = 0;

    // Fixed size mode (default).
    NONE = 1;

    // The height is fixed for the request, the width is a range.
    SMART_BANNER = 2;

    // Height and width are ranges.
    DYNAMIC_SIZE = 3;
  }
}

// Request object for GetAdUnit method.
message GetAdUnitRequest {
  // Required. The resource name of the AdUnit.
  // Format: `networks/{network_code}/adUnits/{ad_unit_id}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "admanager.googleapis.com/AdUnit"
    }
  ];
}

// Request object for ListAdUnits method.
message ListAdUnitsRequest {
  // Required. The parent, which owns this collection of AdUnits.
  // Format: `networks/{network_code}`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "admanager.googleapis.com/Network"
    }
  ];

  // Optional. The maximum number of AdUnits to return. The service may return
  // fewer than this value. If unspecified, at most 50 ad units will be
  // returned. The maximum value is 1000; values above 1000 will be coerced to
  // 1000.
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A page token, received from a previous `ListAdUnits` call.
  // Provide this to retrieve the subsequent page.
  //
  // When paginating, all other parameters provided to `ListAdUnits` must match
  // the call that provided the page token.
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Expression to filter the response.
  // See syntax details at
  // https://developers.google.com/ad-manager/api/beta/filters
  string filter = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Expression to specify sorting order.
  // See syntax details at
  // https://developers.google.com/ad-manager/api/beta/filters#order
  string order_by = 5 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Number of individual resources to skip while paginating.
  int32 skip = 6 [(google.api.field_behavior) = OPTIONAL];
}

// Response object for ListAdUnitsRequest containing matching AdUnit resources.
message ListAdUnitsResponse {
  // The AdUnit from the specified network.
  repeated AdUnit ad_units = 1;

  // A token, which can be sent as `page_token` to retrieve the next page.
  // If this field is omitted, there are no subsequent pages.
  string next_page_token = 2;

  // Total number of AdUnits.
  // If a filter was included in the request, this reflects the total number
  // after the filtering is applied.
  //
  // `total_size` will not be calculated in the response unless it has been
  // included in a response field mask. The response field mask can be provided
  // to the method by using the URL parameter `$fields` or `fields`, or by using
  // the HTTP/gRPC header `X-Goog-FieldMask`.
  //
  // For more information, see
  // https://developers.google.com/ad-manager/api/beta/field-masks
  int32 total_size = 3;
}