// 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.datamanager.v1;

import "google/ads/datamanager/v1/device_info.proto";
import "google/ads/datamanager/v1/user_data.proto";
import "google/ads/datamanager/v1/viewability_info.proto";
import "google/api/field_behavior.proto";
import "google/protobuf/timestamp.proto";

option csharp_namespace = "Google.Ads.DataManager.V1";
option go_package = "cloud.google.com/go/datamanager/apiv1/datamanagerpb;datamanagerpb";
option java_multiple_files = true;
option java_outer_classname = "AdEventProto";
option java_package = "com.google.ads.datamanager.v1";
option php_namespace = "Google\\Ads\\DataManager\\V1";
option ruby_package = "Google::Ads::DataManager::V1";

// An ad event.
message AdEvent {
  // The type of the event.
  enum EventType {
    // Unspecified event type.
    EVENT_TYPE_UNSPECIFIED = 0;

    // View event.
    EVENT_TYPE_VIEW = 1;

    // Click event.
    EVENT_TYPE_CLICK = 2;
  }

  // Additional classification about the type of ad event.
  enum EventSubtype {
    // Unspecified event subtype.
    EVENT_SUBTYPE_UNSPECIFIED = 0;

    // Impression event.
    EVENT_SUBTYPE_IMPRESSION = 1;

    // Engaged view event.
    EVENT_SUBTYPE_ENGAGED_VIEW = 2;

    // Onsite click event.
    EVENT_SUBTYPE_ONSITE_CLICK = 3;

    // Outbound click event.
    EVENT_SUBTYPE_OUTBOUND_CLICK = 4;
  }

  // Required. The ID of the advertiser for the ad event.
  //
  // This must match the ID sent in the linking flow.
  string advertiser_id = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. The type of the event.
  EventType event_type = 2 [(google.api.field_behavior) = REQUIRED];

  // Optional. Additional classification about the type of ad event.
  //
  // A raw string is accepted to handle values other than the pure enums.
  // The enum is preferred if possible.
  oneof event_subtype_oneof {
    // Enum value for event subtype.
    EventSubtype event_subtype = 3;

    // String value for event subtype.
    string event_subtype_string = 4;
  }

  // Required. The time the event occurred.
  google.protobuf.Timestamp timestamp = 5
      [(google.api.field_behavior) = REQUIRED];

  // Optional. An ID created and managed by the caller that uniquely identifies
  // this event.
  //
  // Required if you want to deduplicate ad events that are included
  // in multiple requests. Otherwise, this field is optional.
  string event_id = 6 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Multiple pieces of user-provided data, representing the user the
  // event is associated with.
  //
  // It is possible to provide multiple instances of the same type of data (e.g.
  // email address). The more data provided, the more likely a match will be
  // found.
  UserData user_data = 7 [(google.api.field_behavior) = OPTIONAL];

  // Required. Information gathered about the device being used when the ad
  // event happened.
  DeviceInfo device_info = 8 [(google.api.field_behavior) = REQUIRED];

  // Optional. The device ID of the device that the ad was served to.
  string mobile_device_id = 9 [(google.api.field_behavior) = OPTIONAL];

  // Required. The ID of the associated campaign.
  string campaign_id = 10 [(google.api.field_behavior) = REQUIRED];

  // Required. The name of the associated campaign.
  string campaign_name = 11 [(google.api.field_behavior) = REQUIRED];

  // Optional. The ID of the associated ad group.
  string ad_group_id = 12 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The ID of the associated ad within the group.
  string ad_id = 13 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The type of the ad served.
  //
  // A raw string is accepted to handle values other than the pure enums.
  // The enum is preferred if possible.
  oneof ad_type_oneof {
    // Enum value for ad type.
    AdType ad_type = 14;

    // String value for ad type.
    string ad_type_string = 15;
  }

  // Optional. The type of the ad served.
  //
  // A raw string is accepted to handle values other than the pure enums.
  // The enum is preferred if possible.
  oneof ad_format_oneof {
    // Enum value for ad format.
    AdFormat ad_format = 16;

    // String value for ad format.
    string ad_format_string = 17;
  }

  // Optional. The placement of the ad served.
  //
  // A raw string is accepted to handle values other than the pure enums.
  // The enum is preferred if possible.
  oneof ad_placement_oneof {
    // Enum value for ad placement.
    AdPlacement ad_placement = 18;

    // String value for ad placement.
    string ad_placement_string = 19;
  }

  // Optional. The height of the ad in pixels.
  int32 ad_height = 20 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The width of the ad in pixels.
  int32 ad_width = 21 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The ISO 3166-2 country plus subdivision.
  string region_code = 22 [(google.api.field_behavior) = OPTIONAL];

  // Required. The platform source of the ad, akin to the Google Analytics
  // source.
  string source = 23 [(google.api.field_behavior) = REQUIRED];

  // Required. The medium of the ad, akin to the Google Analytics medium.
  string medium = 24 [(google.api.field_behavior) = REQUIRED];

  // Optional. The type of targeting used to serve the ad.
  //
  // A raw string is accepted to handle values other than the pure enums.
  // The enum is preferred if possible.
  oneof targeting_type_oneof {
    // Enum value for targeting type.
    TargetingType targeting_type = 25;

    // String value for targeting type.
    string targeting_type_string = 26;
  }

  // Optional. The type of the platform on which the ad was served.
  //
  // A raw string is accepted to handle values other than the pure enums.
  // The enum is preferred if possible.
  oneof platform_type_oneof {
    // Enum value for platform type.
    PlatformType platform_type = 27;

    // String value for platform type.
    string platform_type_string = 28;
  }

  // Optional. Further detail of the platform on which the ad was served.
  //
  // A raw string is accepted to handle values other than the pure enums.
  // The enum is preferred if possible.
  oneof platform_oneof {
    // Enum value for platform.
    Platform platform = 29;

    // String value for platform.
    string platform_string = 30;
  }

  // Optional. The partner-assumed attribution status for this ad event.
  //
  // This acts only as a signal for how the partner assumed attribution played
  // out, and does not force an end result in final reports.
  AttributionHint attribution_hint = 31
      [(google.api.field_behavior) = OPTIONAL];

  // Required. Details of the viewability of the ad served.
  ViewabilityInfo viewability_info = 32
      [(google.api.field_behavior) = REQUIRED];

  // Optional. Represents if the row is allowed to be used for measurement
  // purposes, as governed by applicable privacy laws within regional
  // jurisdiction.
  optional bool measurement_allowed = 33
      [(google.api.field_behavior) = OPTIONAL];
}

// The type of the ad served.
enum AdType {
  // Unspecified ad type.
  AD_TYPE_UNSPECIFIED = 0;

  // Display ad.
  AD_TYPE_DISPLAY = 1;

  // Text ad.
  AD_TYPE_TEXT = 2;

  // Image ad.
  AD_TYPE_IMAGE = 3;

  // Rich media ad.
  AD_TYPE_RICH_MEDIA = 4;

  // HTML ad.
  AD_TYPE_HTML = 5;

  // Audio ad.
  AD_TYPE_AUDIO = 6;

  // Video ad.
  AD_TYPE_VIDEO = 7;
}

// The format of the ad served.
enum AdFormat {
  // Unspecified ad format.
  AD_FORMAT_UNSPECIFIED = 0;

  // AR ad.
  AD_FORMAT_AR = 1;

  // Audio ad.
  AD_FORMAT_AUDIO = 2;

  // Banner ad.
  AD_FORMAT_BANNER = 3;

  // Bumper ad.
  AD_FORMAT_BUMPER = 4;

  // Carousel ad.
  AD_FORMAT_CAROUSEL = 5;

  // Collection ad.
  AD_FORMAT_COLLECTION = 6;

  // Image ad.
  AD_FORMAT_IMAGE = 7;

  // Interactive ad.
  AD_FORMAT_INTERACTIVE = 8;

  // Interstitial ad.
  AD_FORMAT_INTERSTITIAL = 9;

  // In-feed ad.
  AD_FORMAT_IN_FEED = 10;

  // In-stream ad.
  AD_FORMAT_IN_STREAM = 11;

  // In-stream skippable ad.
  AD_FORMAT_IN_STREAM_SKIPPABLE = 12;

  // In-stream non-skippable ad.
  AD_FORMAT_IN_STREAM_NON_SKIPPABLE = 13;

  // Native ad.
  AD_FORMAT_NATIVE = 14;

  // Shorts ad.
  AD_FORMAT_SHORTS = 15;

  // Story ad.
  AD_FORMAT_STORY = 16;

  // Sponsored ad.
  AD_FORMAT_SPONSORED = 17;

  // Video ad.
  AD_FORMAT_VIDEO = 18;
}

// The placement of the ad served.
enum AdPlacement {
  // Unspecified ad placement.
  AD_PLACEMENT_UNSPECIFIED = 0;

  // Discover placement.
  AD_PLACEMENT_DISCOVER = 1;

  // Feed placement.
  AD_PLACEMENT_FEED = 2;

  // Footer placement.
  AD_PLACEMENT_FOOTER = 3;

  // Header placement.
  AD_PLACEMENT_HEADER = 4;

  // Home placement.
  AD_PLACEMENT_HOME = 5;

  // In-content placement.
  AD_PLACEMENT_IN_CONTENT = 6;

  // Promoted placement.
  AD_PLACEMENT_PROMOTED = 7;

  // Search placement.
  AD_PLACEMENT_SEARCH = 8;

  // Story placement.
  AD_PLACEMENT_STORY = 9;
}

// The type of targeting used to serve the ad.
enum TargetingType {
  // Unspecified targeting type.
  TARGETING_TYPE_UNSPECIFIED = 0;

  // Audience targeting.
  TARGETING_TYPE_AUDIENCE = 1;

  // Contextual targeting.
  TARGETING_TYPE_CONTEXTUAL = 2;

  // Demographic targeting.
  TARGETING_TYPE_DEMOGRAPHIC = 3;

  // Device targeting.
  TARGETING_TYPE_DEVICE = 4;

  // Geo targeting.
  TARGETING_TYPE_GEO = 5;

  // Interest targeting.
  TARGETING_TYPE_INTEREST = 6;

  // Purchase intent targeting.
  TARGETING_TYPE_PURCHASE_INTENT = 7;

  // Remarketing targeting.
  TARGETING_TYPE_REMARKETING = 8;
}

// The type of the platform on which the ad was served.
enum PlatformType {
  // Unspecified platform type.
  PLATFORM_TYPE_UNSPECIFIED = 0;

  // Mobile platform.
  PLATFORM_TYPE_MOBILE = 1;

  // Desktop platform.
  PLATFORM_TYPE_DESKTOP = 2;

  // CTV platform.
  PLATFORM_TYPE_CTV = 3;

  // Phone platform.
  PLATFORM_TYPE_PHONE = 4;

  // Tablet platform.
  PLATFORM_TYPE_TABLET = 5;
}

// Further detail of the platform on which the ad was served.
enum Platform {
  // Unspecified platform.
  PLATFORM_UNSPECIFIED = 0;

  // iOS platform.
  PLATFORM_IOS = 1;

  // Android platform.
  PLATFORM_ANDROID = 2;

  // Web platform.
  PLATFORM_WEB = 3;
}

// The partner-assumed attribution status for this ad event.
enum AttributionHint {
  // Unknown attribution status.
  ATTRIBUTION_HINT_UNSPECIFIED = 0;

  // Converted status.
  ATTRIBUTION_HINT_CONVERTED = 1;

  // Not converted status.
  ATTRIBUTION_HINT_NOT_CONVERTED = 2;
}