// Copyright 2025 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/creative_template_enums.proto";
import "google/ads/admanager/v1/creative_template_variable_url_type_enum.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.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 = "CreativeTemplateMessagesProto";
option java_package = "com.google.ads.admanager.v1";
option php_namespace = "Google\\Ads\\AdManager\\V1";
option ruby_package = "Google::Ads::AdManager::V1";

// A template that can be used to create a [TemplateCreative][].
message CreativeTemplate {
  option (google.api.resource) = {
    type: "admanager.googleapis.com/CreativeTemplate"
    pattern: "networks/{network_code}/creativeTemplates/{creative_template}"
    plural: "creativeTemplates"
    singular: "creativeTemplate"
  };

  // Identifier. The resource name of the creative template.
  // Format: `networks/{network_code}/creativeTemplates/{creative_template_id}`
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  // Required. The display name of the creative template. This has a maximum
  // length of 255 characters.
  optional string display_name = 2 [(google.api.field_behavior) = REQUIRED];

  // Optional. The description of the creative template.
  optional string description = 3 [(google.api.field_behavior) = OPTIONAL];

  // Required. The code snippet of the creative template, with placeholders for
  // the associated variables.
  optional string snippet = 4 [(google.api.field_behavior) = REQUIRED];

  // Output only. The status of the creative template. This attribute is
  // assigned by Google.
  optional CreativeTemplateStatusEnum.CreativeTemplateStatus status = 6
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. The type of the creative template. Users can only create or
  // update `CreativeTemplateType.CUSTOM` templates.
  optional CreativeTemplateTypeEnum.CreativeTemplateType type = 7
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. `True` if this creative template produces out-of-page creatives.
  // Creative templates with this setting enabled must include the viewed
  // impression macro.
  optional bool interstitial = 8 [(google.api.field_behavior) = OPTIONAL];

  // Optional. `True` if this creative template produces native-eligible
  // creatives.
  optional bool native_eligible = 9 [(google.api.field_behavior) = OPTIONAL];

  // Optional. `True` if this creative template produces native video-eligible
  // creatives.
  optional bool native_video_eligible = 10
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Whether the Creative produced is compatible for SafeFrame
  // rendering. This attribute defaults to `True`.
  optional bool safe_frame_compatible = 12
      [(google.api.field_behavior) = OPTIONAL];

  // Required. The list of creative template variables.
  repeated CreativeTemplateVariable variables = 14
      [(google.api.field_behavior) = REQUIRED];
}

// Represents a variable defined in a creative template.
message CreativeTemplateVariable {
  // Represents a file asset variable defined in a creative template.
  //
  // Use [AssetCreativeTemplateVariableValue][] to specify the value for this
  // variable when creating a [TemplateCreative][] from a
  // [CreativeTemplate][google.ads.admanager.v1.CreativeTemplate].
  message AssetCreativeTemplateVariable {
    // Different MIME types that the asset variable supports.
    enum MimeType {
      // Default value. This value is unused.
      MIME_TYPE_UNSPECIFIED = 0;

      // The `image/jpeg` MIME type.
      JPG = 1;

      // The `image/png` MIME type.
      PNG = 2;

      // The `image/gif` MIME type.
      GIF = 3;
    }

    // Optional. The set of allowed MIME types. If unspecified, all MIME types
    // are allowed.
    repeated MimeType mime_types = 1 [(google.api.field_behavior) = OPTIONAL];
  }

  // Represents a list variable defined in a creative template. This is similar
  // to
  // [StringCreativeTemplateVariable][google.ads.admanager.v1.CreativeTemplateVariable.StringCreativeTemplateVariable],
  // except that there are possible choices to choose from.
  //
  // Use [StringCreativeTemplateVariableValue][] to specify the value
  // for this variable when creating a [TemplateCreative][] from a
  // [CreativeTemplate][google.ads.admanager.v1.CreativeTemplate].
  message ListStringCreativeTemplateVariable {
    // Stores variable choices selectable by users.
    message VariableChoice {
      // Required. A label is displayed to users when creating a
      // [TemplateCreative][]. This attribute is intended to be more descriptive
      // than value. This attribute has a maximum length of 255 characters.
      optional string label = 1 [(google.api.field_behavior) = REQUIRED];

      // Required. When creating a [TemplateCreative][], the value in
      // [StringCreativeTemplateVariableValue][] should match this value, if you
      // intend to select this value. This attribute has a maximum length of 255
      // characters.
      optional string value = 2 [(google.api.field_behavior) = REQUIRED];
    }

    // Optional. Default value to be filled in when creating creatives from the
    // creative template.
    optional string default_value = 1 [(google.api.field_behavior) = OPTIONAL];

    // Optional. Sample value that is used when previewing the template in the
    // UI.
    optional string sample_value = 2 [(google.api.field_behavior) = OPTIONAL];

    // Optional. The selectable values that the user can choose from.
    repeated VariableChoice choices = 3
        [(google.api.field_behavior) = OPTIONAL];

    // Optional. `True` if a user can specify an 'other' value. For example, if
    // a variable called backgroundColor is defined as a list with values: red,
    // green, blue, this boolean can be set to allow a user to enter a value not
    // on the list such as purple.
    optional bool allow_other_choice = 4
        [(google.api.field_behavior) = OPTIONAL];
  }

  // Represents a long variable defined in a creative template.
  //
  // Use [LongCreativeTemplateVariableValue][] to specify the value
  // for this variable when creating [TemplateCreative][] from a
  // [CreativeTemplate][google.ads.admanager.v1.CreativeTemplate].
  message LongCreativeTemplateVariable {
    // Optional. Default value to be filled in when creating creatives from the
    // creative template.
    optional int64 default_value = 1 [(google.api.field_behavior) = OPTIONAL];

    // Optional. Sample value that is used when previewing the template in the
    // UI.
    optional int64 sample_value = 2 [(google.api.field_behavior) = OPTIONAL];
  }

  // Represents a string variable defined in a creative template.
  //
  // Use [StringCreativeTemplateVariableValue][] to specify the value
  // for this variable when creating [TemplateCreative][] from a
  // [CreativeTemplate][google.ads.admanager.v1.CreativeTemplate].
  message StringCreativeTemplateVariable {
    // Optional. Default value to be filled in when creating creatives from the
    // creative template.
    optional string default_value = 1 [(google.api.field_behavior) = OPTIONAL];

    // Optional. Sample value that is used when previewing the template in the
    // UI.
    optional string sample_value = 2 [(google.api.field_behavior) = OPTIONAL];
  }

  // Represents a url variable defined in a creative template.
  //
  // Use [UrlCreativeTemplateVariableValue][] to specify the value for this
  // variable when creating a [TemplateCreative][] from a
  // [CreativeTemplate][google.ads.admanager.v1.CreativeTemplate].
  message UrlCreativeTemplateVariable {
    // Optional. Default value to be filled in when creating creatives from the
    // creative template.
    optional string default_value = 1 [(google.api.field_behavior) = OPTIONAL];

    // Optional. Sample value that is used when previewing the template in the
    // UI.
    optional string sample_value = 2 [(google.api.field_behavior) = OPTIONAL];

    // Optional. The type of URL that this variable represents. Different types
    // of URLs may be handled differently at rendering time.
    optional CreativeTemplateVariableUrlTypeEnum.CreativeTemplateVariableUrlType
        url_type = 4 [(google.api.field_behavior) = OPTIONAL];
  }

  // The specific type of variable represented by this
  // [CreativeTemplateVariable][google.ads.admanager.v1.CreativeTemplateVariable].
  // Exactly one must be set.
  oneof SubType {
    // Optional. Represents a file asset variable defined in a creative
    // template.
    AssetCreativeTemplateVariable asset_variable = 5
        [(google.api.field_behavior) = OPTIONAL];

    // Optional. Represents a list variable defined in a creative template.
    ListStringCreativeTemplateVariable list_string_variable = 7
        [(google.api.field_behavior) = OPTIONAL];

    // Optional. Represents a long variable defined in a creative template.
    LongCreativeTemplateVariable long_variable = 8
        [(google.api.field_behavior) = OPTIONAL];

    // Optional. Represents a string variable defined in a creative template.
    StringCreativeTemplateVariable string_variable = 9
        [(google.api.field_behavior) = OPTIONAL];

    // Optional. Represents a url variable defined in a creative template.
    UrlCreativeTemplateVariable url_variable = 10
        [(google.api.field_behavior) = OPTIONAL];
  }

  // Required. Label that is displayed to users when creating from the creative
  // template. This has a maximum length of 127 characters.
  optional string label = 1 [(google.api.field_behavior) = REQUIRED];

  // Output only. Unique name used to identify the variable. This attribute is
  // assigned by Google when a creative template variable is created.
  optional string unique_display_name = 2
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Required. A descriptive help text that is displayed to users along with the
  // label. This attribute has a maximum length of 255 characters.
  optional string description = 3 [(google.api.field_behavior) = REQUIRED];

  // Optional. `True` if this variable is required to be filled in by users when
  // creating a creative from the creative template.
  optional bool required = 4 [(google.api.field_behavior) = OPTIONAL];
}