// Copyright 2026 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/audience_segment_enums.proto";
import "google/ads/admanager/v1/targeting.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/protobuf/timestamp.proto";
import "google/type/money.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 = "AudienceSegmentMessagesProto";
option java_package = "com.google.ads.admanager.v1";
option php_namespace = "Google\\Ads\\AdManager\\V1";
option ruby_package = "Google::Ads::AdManager::V1";

// The `AudienceSegment` resource.
message AudienceSegment {
  option (google.api.resource) = {
    type: "admanager.googleapis.com/AudienceSegment"
    pattern: "networks/{network_code}/audienceSegments/{audience_segment}"
    plural: "audienceSegments"
    singular: "audienceSegment"
  };

  // An `AudienceSegment` owned by the publisher network that does not contain
  // a rule. Cookies are usually added to these segments through cookie upload.
  message NonRuleBasedFirstPartyAudienceSegment {
    // Required. Number of days after which a user's cookie will be removed from
    // the `AudienceSegment` due to inactivity. The field can be between 1 and
    // 540.
    optional int64 membership_expiration_days = 1
        [(google.api.field_behavior) = REQUIRED];
  }

  // An `AudienceSegment` owned by the publisher network that contains a rule.
  message RuleBasedFirstPartyAudienceSegment {
    // Required. Number of times a user's cookie must match the `rule` before
    // it's associated with the `AudienceSegment`. This is used with
    // `recency_days` to determine eligibility of the association. This
    // attribute is between 1 and 12.
    optional int64 page_views = 1 [(google.api.field_behavior) = REQUIRED];

    // Optional. Number of days within which a user's cookie must match the
    // `rule` before it's associated with the `AudienceSegment`. This is used
    // with `page_views` to determine eligibility of the association. This
    // attribute is required if `page_views` is greater than 1. When set, it can
    // be between 1 and 30.
    optional int64 recency_days = 2 [(google.api.field_behavior) = OPTIONAL];

    // Required. Number of days after which a user's cookie will be removed from
    // the `AudienceSegment` due to inactivity. The field can be between 1 and
    // 540.
    optional int64 membership_expiration_days = 3
        [(google.api.field_behavior) = REQUIRED];

    // Required. The rule definition which determines the eligibility criteria
    // for the `AudienceSegment`.
    Rule rule = 4 [(google.api.field_behavior) = REQUIRED];
  }

  // An `AudienceSegment` owned by a data provider and licensed to the
  // Ad Manager publisher network.
  message ThirdPartyAudienceSegment {
    // Output only. Whether the publisher has approved or rejected the segment.
    optional AudienceSegmentApprovalStatusEnum.AudienceSegmentApprovalStatus
        approval_status = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The CPM cost for the given segment. This is assigned by the
    // data provider. The CPM cost comes from the active pricing if it exists,
    // otherwise it comes from the latest pricing.
    google.type.Money cost = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The license type of the external segment.
    optional AudienceSegmentLicenseTypeEnum.AudienceSegmentLicenseType
        license_type = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. Time which this segment becomes available for use. It is
    // assigned by the data provider.
    google.protobuf.Timestamp start_time = 4
        [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. Time which this segment ceases to be available. It is
    // assigned by the data provider.
    google.protobuf.Timestamp end_time = 5
        [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // Eligibility criteria for a user to be part of an `AudienceSegment`.
  message Rule {
    // Required. Specification of inventory (i.e. ad units and placements) that
    // are part of the rule of the RuleBasedFirstPartyAudienceSegment.
    InventoryTargeting inventory_targeting = 1
        [(google.api.field_behavior) = REQUIRED];

    // Optional. Specification of custom criteria that are part of the rule of
    // the RuleBasedFirstPartyAudienceSegment. Once specified, the server may
    // return a normalized but equivalent representation of the rule. There are
    // up to 3 levels of custom criteria allowed. See
    // [CustomTargeting][google.ads.admanager.v1.CustomTargeting] and its
    // sub-messages for limitations.
    CustomTargeting custom_targeting = 2
        [(google.api.field_behavior) = OPTIONAL];
  }

  // Based on the `type` classification, the `AudienceSegment` has additional
  // information in zero or one of the following sub-types.
  oneof sub_type {
    // Optional. An `AudienceSegment` owned by the publisher network that does
    // not contain a rule. Cookies are usually added to these segments through
    // cookie upload.
    NonRuleBasedFirstPartyAudienceSegment
        non_rule_based_first_party_audience_segment = 13
        [(google.api.field_behavior) = OPTIONAL];

    // Optional. An `AudienceSegment` owned by the publisher network that
    // contains a rule.
    RuleBasedFirstPartyAudienceSegment rule_based_first_party_audience_segment =
        14 [(google.api.field_behavior) = OPTIONAL];

    // Output only. An `AudienceSegment` owned by a data provider and licensed
    // to the Ad Manager publisher network.
    ThirdPartyAudienceSegment third_party_audience_segment = 16
        [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // Identifier. The resource name of the `AudienceSegment`.
  // Format: `networks/{network_code}/audienceSegments/{audience_segment_id}`
  // The `audience_segment_id` is not always numerical and may have one of
  // the following suffixes:
  //   - `~direct` for directly licensed third-party segments
  //   - `~global` for globally licensed third-party segments
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  // Output only. The ID of the `AudienceSegment`. Up to two resources may share
  // this ID.
  int64 shared_id = 17 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Required. Display name of the `AudienceSegment`. The attribute has a
  // maximum length of 255 characters.
  optional string display_name = 2 [(google.api.field_behavior) = REQUIRED];

  // Optional. Unordered list. IDs of the categories that this audience segment
  // belongs to. See `segment_categories` for additional information about the
  // categories.
  repeated int64 category_ids = 3 [
    (google.api.field_behavior) = OPTIONAL,
    (google.api.field_behavior) = UNORDERED_LIST
  ];

  // Optional. Description of the `AudienceSegment`. This has a maximum length
  // of 8192 characters.
  optional string description = 4 [(google.api.field_behavior) = OPTIONAL];

  // Output only. Non-empty default. Status of the `AudienceSegment` used to
  // determine whether the segment is available for targeting. Defaults to
  // `ACTIVE` if not set.
  optional AudienceSegmentStatusEnum.AudienceSegmentStatus status = 5 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.field_behavior) = NON_EMPTY_DEFAULT
  ];

  // Output only. Number of unique identifiers in the `AudienceSegment`.
  optional int64 size = 6 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Number of unique mobile web identifiers in the
  // `AudienceSegment`.
  optional int64 mobile_web_size = 7
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Number of unique Identifier for Advertisers (IDFA) identifiers
  // in the `AudienceSegment`.
  optional int64 idfa_size = 8 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Number of unique AdID identifiers in the `AudienceSegment`.
  optional int64 ad_id_size = 9 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Number of unique publisher-provided (PPID) identifiers in the
  // `AudienceSegment`.
  optional int64 ppid_size = 10 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Display name of the owner data provider. For a first-party
  // audience segment, this is the display name of the publisher network.
  // Otherwise, this is the display name of the entity providing the audience
  // segment.
  optional string data_provider_display_name = 11
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Non-empty default. Type of the `AudienceSegment`. Every
  // `AudienceSegment` is either `FIRST_PARTY` or `THIRD_PARTY`.
  optional AudienceSegmentTypeEnum.AudienceSegmentType segment_type = 12 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.field_behavior) = NON_EMPTY_DEFAULT
  ];
}