// 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/cart_data.proto";
import "google/ads/datamanager/v1/consent.proto";
import "google/ads/datamanager/v1/device_info.proto";
import "google/ads/datamanager/v1/encrypted_user_id.proto";
import "google/ads/datamanager/v1/experimental_field.proto";
import "google/ads/datamanager/v1/user_data.proto";
import "google/ads/datamanager/v1/user_properties.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 = "EventProto";
option java_package = "com.google.ads.datamanager.v1";
option php_namespace = "Google\\Ads\\DataManager\\V1";
option ruby_package = "Google::Ads::DataManager::V1";

// An event representing a user interaction with an advertiser's website or app.
message Event {
  // Optional. Reference string used to determine the destination. If empty, the
  // event will be sent to all
  // [destinations][google.ads.datamanager.v1.IngestEventsRequest.destinations]
  // in the request.
  repeated string destination_references = 1
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. The unique identifier for this event. Required for events sent as
  // an additional data source for tag conversions.
  string transaction_id = 2 [(google.api.field_behavior) = OPTIONAL];

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

  // Optional. The last time the event was updated.
  google.protobuf.Timestamp last_updated_timestamp = 4
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Pieces of user provided data, representing the user the event is
  // associated with.
  UserData user_data = 5 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Information about whether the associated user has provided
  // different types of consent.
  Consent consent = 6 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Identifiers and other information used to match the conversion
  // event with other online activity (such as ad clicks).
  AdIdentifiers ad_identifiers = 7 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The currency code associated with all monetary values within this
  // event.
  string currency = 8 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The conversion value associated with the event, for value-based
  // conversions.
  optional double conversion_value = 9 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The conversion quantity associated with the event, for
  // counting-based conversions.
  optional double conversion_count = 23
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Signal for where the event happened (web, app, in-store, etc.).
  EventSource event_source = 10 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Information gathered about the device being used (if any) when
  // the event happened.
  DeviceInfo event_device_info = 11 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Information about the transaction and items associated with the
  // event.
  CartData cart_data = 12 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Additional key/value pair information to send to the conversion
  // containers (conversion action or FL activity).
  repeated CustomVariable custom_variables = 13
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. A list of key/value pairs for experimental fields that may
  // eventually be promoted to be part of the API.
  repeated ExperimentalField experimental_fields = 14
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Advertiser-assessed information about the user at the time that
  // the event happened.
  UserProperties user_properties = 15 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The name of the event. Required for GA4 events.
  string event_name = 16 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A unique identifier for the user instance of a web client for
  // this GA4 web stream.
  string client_id = 17 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A unique identifier for a user, as defined by the advertiser.
  string user_id = 18 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A bucket of any [event
  // parameters](https://developers.google.com/analytics/devguides/collection/protocol/ga4/reference/events)
  // to be included within the event that were not already specified using other
  // structured fields.
  repeated EventParameter additional_event_parameters = 19
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. The same type of data provided in user_data, but explicitly
  // flagged as being provided as owned by a third-party and not first-party
  // advertiser data.
  UserData third_party_user_data = 20 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Information gathered about the location of the user when this
  // event occurred.
  EventLocation event_location = 21 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A unique identifier for the user instance of an app client for
  // this GA4 app stream.
  string app_instance_id = 22 [(google.api.field_behavior) = OPTIONAL];
}

// Identifiers and other information used to match the conversion event with
// other online activity (such as ad clicks).
message AdIdentifiers {
  // Optional. Session attributes for event attribution and modeling.
  string session_attributes = 1 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The Google click ID (gclid) associated with this event.
  string gclid = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The click identifier for clicks associated with app events and
  // originating from iOS devices starting with iOS14.
  string gbraid = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The click identifier for clicks associated with web events and
  // originating from iOS devices starting with iOS14.
  string wbraid = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Information gathered about the device being used (if any) at the
  // time of landing onto the advertiser’s site after interacting with the ad.
  DeviceInfo landing_page_device_info = 5
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. The mobile identifier for advertisers. This would be IDFA on iOS,
  // AdID on Android, or other platforms’ identifiers for advertisers.
  string mobile_device_id = 6 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The display click ID associated with this event.
  string dclid = 7 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The impression ID associated with this event.
  string impression_id = 8 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The match ID field used to join this event with a previous event.
  string match_id = 9 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Any number of encrypted user IDs.
  repeated EncryptedUserId encrypted_user_ids = 10
      [(google.api.field_behavior) = OPTIONAL];
}

// Custom variable for ads conversions.
message CustomVariable {
  // Optional. The name of the custom variable to set. If the variable is not
  // found for the given destination, it will be ignored.
  string variable = 1 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The value to store for the custom variable.
  string value = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Reference string used to determine which of the
  // [Event.destination_references][google.ads.datamanager.v1.Event.destination_references]
  // the custom variable should be sent to. If empty, the
  // [Event.destination_references][google.ads.datamanager.v1.Event.destination_references]
  // will be used.
  repeated string destination_references = 3
      [(google.api.field_behavior) = OPTIONAL];
}

// Event parameter for GA4 events.
message EventParameter {
  // Required. The name of the parameter to use.
  string parameter_name = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. The string representation of the value of the parameter to set.
  string value = 2 [(google.api.field_behavior) = REQUIRED];
}

// The location where the event occurred.
message EventLocation {
  // Optional. Required for Store Sales. The identifier to represent a physical
  // store where the event happened.
  string store_id = 1 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The name of the city where the event occurred.
  string city = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The ISO 3166-2 subdivision code where the event occurred.
  string subdivision_code = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The 2-letter CLDR region code of the user's address.
  string region_code = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The subcontinent code in UN M49 format where the event occurred.
  string subcontinent_code = 5 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The continent code in UN M49 format where the event occurred.
  string continent_code = 6 [(google.api.field_behavior) = OPTIONAL];
}

// The source of the event.
enum EventSource {
  // Unspecified EventSource. Should never be used.
  EVENT_SOURCE_UNSPECIFIED = 0;

  // The event was generated from a web browser.
  WEB = 1;

  // The event was generated from an app.
  APP = 2;

  // The event was generated from an in-store transaction.
  IN_STORE = 3;

  // The event was generated from a phone call.
  PHONE = 4;

  // The event was generated from a message.
  MESSAGE = 6;

  // The event was generated from other sources.
  OTHER = 5;
}