// Copyright 2021 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.googleads.v7.common;

import "google/ads/googleads/v7/enums/user_identifier_source.proto";
import "google/api/annotations.proto";

option csharp_namespace = "Google.Ads.GoogleAds.V7.Common";
option go_package = "google.golang.org/genproto/googleapis/ads/googleads/v7/common;common";
option java_multiple_files = true;
option java_outer_classname = "OfflineUserDataProto";
option java_package = "com.google.ads.googleads.v7.common";
option objc_class_prefix = "GAA";
option php_namespace = "Google\\Ads\\GoogleAds\\V7\\Common";
option ruby_package = "Google::Ads::GoogleAds::V7::Common";

// Proto file describing offline user data.

// Address identifier of offline data.
message OfflineUserAddressInfo {
  // First name of the user, which is hashed as SHA-256 after normalized
  // (Lowercase all characters; Remove any extra spaces before, after, and in
  // between).
  optional string hashed_first_name = 7;

  // Last name of the user, which is hashed as SHA-256 after normalized (lower
  // case only and no punctuation).
  optional string hashed_last_name = 8;

  // City of the address. Only accepted for Store Sales Direct data.
  optional string city = 9;

  // State code of the address. Only accepted for Store Sales Direct data.
  optional string state = 10;

  // 2-letter country code in ISO-3166-1 alpha-2 of the user's address.
  optional string country_code = 11;

  // Postal code of the user's address.
  optional string postal_code = 12;
}

// Hashed user identifying information.
message UserIdentifier {
  // Source of the user identifier when the upload is from Store Sales third
  // party partners.
  google.ads.googleads.v7.enums.UserIdentifierSourceEnum.UserIdentifierSource user_identifier_source = 6;

  // Exactly one must be specified.
  oneof identifier {
    // Hashed email address using SHA-256 hash function after normalization.
    string hashed_email = 7;

    // Hashed phone number using SHA-256 hash function after normalization
    // (E164 standard).
    string hashed_phone_number = 8;

    // Mobile device ID (advertising ID/IDFA).
    string mobile_id = 9;

    // Advertiser-assigned user ID for Customer Match upload, or
    // third-party-assigned user ID for SSD.
    string third_party_user_id = 10;

    // Address information.
    OfflineUserAddressInfo address_info = 5;
  }
}

// Attribute of the store sales transaction.
message TransactionAttribute {
  // Timestamp when transaction occurred. Required.
  // The format is "YYYY-MM-DD HH:MM:SS[+/-HH:MM]", where [+/-HH:MM] is an
  // optional timezone offset from UTC. If the offset is absent, the API will
  // use the account's timezone as default.
  // Examples: "2018-03-05 09:15:00" or "2018-02-01 14:34:30+03:00"
  optional string transaction_date_time = 8;

  // Transaction amount in micros. Required.
  optional double transaction_amount_micros = 9;

  // Transaction currency code. ISO 4217 three-letter code is used. Required.
  optional string currency_code = 10;

  // The resource name of conversion action to report conversions to.
  // Required.
  optional string conversion_action = 11;

  // Transaction order id.
  // Accessible only to customers on the allow-list.
  optional string order_id = 12;

  // Store attributes of the transaction.
  // Accessible only to customers on the allow-list.
  StoreAttribute store_attribute = 6;

  // Value of the custom variable for each transaction.
  // Accessible only to customers on the allow-list.
  optional string custom_value = 13;
}

// Store attributes of the transaction.
message StoreAttribute {
  // Store code from
  // https://support.google.com/business/answer/3370250#storecode
  optional string store_code = 2;
}

// User data holding user identifiers and attributes.
message UserData {
  // User identification info. Required.
  repeated UserIdentifier user_identifiers = 1;

  // Additional transactions/attributes associated with the user.
  // Required when updating store sales data.
  TransactionAttribute transaction_attribute = 2;

  // Additional attributes associated with the user. Required when updating
  // customer match attributes. These have an expiration of 540 days.
  UserAttribute user_attribute = 3;
}

// User attribute, can only be used with CUSTOMER_MATCH_WITH_ATTRIBUTES job
// type.
message UserAttribute {
  // Advertiser defined lifetime value for the user.
  optional int64 lifetime_value_micros = 1;

  // Advertiser defined lifetime value bucket for the user. The valid range for
  // a lifetime value bucket is from 1 (low) to 10 (high), except for remove
  // operation where 0 will also be accepted.
  optional int32 lifetime_value_bucket = 2;
}

// Metadata for customer match user list.
message CustomerMatchUserListMetadata {
  // The resource name of remarketing list to update data.
  // Required for job of CUSTOMER_MATCH_USER_LIST type.
  optional string user_list = 2;
}

// Metadata for Store Sales Direct.
message StoreSalesMetadata {
  // This is the fraction of all transactions that are identifiable (i.e.,
  // associated with any form of customer information).
  // Required.
  // The fraction needs to be between 0 and 1 (excluding 0).
  optional double loyalty_fraction = 5;

  // This is the ratio of sales being uploaded compared to the overall sales
  // that can be associated with a customer. Required.
  // The fraction needs to be between 0 and 1 (excluding 0). For example, if you
  // upload half the sales that you are able to associate with a customer, this
  // would be 0.5.
  optional double transaction_upload_fraction = 6;

  // Name of the store sales custom variable key. A predefined key that
  // can be applied to the transaction and then later used for custom
  // segmentation in reporting.
  // Accessible only to customers on the allow-list.
  optional string custom_key = 7;

  // Metadata for a third party Store Sales upload.
  StoreSalesThirdPartyMetadata third_party_metadata = 3;
}

// Metadata for a third party Store Sales.
// This product is only for customers on the allow-list. Please contact your
// Google business development representative for details on the upload
// configuration.
message StoreSalesThirdPartyMetadata {
  // Time the advertiser uploaded the data to the partner. Required.
  // The format is "YYYY-MM-DD HH:MM:SS".
  // Examples: "2018-03-05 09:15:00" or "2018-02-01 14:34:30"
  optional string advertiser_upload_date_time = 7;

  // The fraction of transactions that are valid. Invalid transactions may
  // include invalid formats or values.
  // Required.
  // The fraction needs to be between 0 and 1 (excluding 0).
  optional double valid_transaction_fraction = 8;

  // The fraction of valid transactions that are matched to a third party
  // assigned user ID on the partner side.
  // Required.
  // The fraction needs to be between 0 and 1 (excluding 0).
  optional double partner_match_fraction = 9;

  // The fraction of valid transactions that are uploaded by the partner to
  // Google.
  // Required.
  // The fraction needs to be between 0 and 1 (excluding 0).
  optional double partner_upload_fraction = 10;

  // Version of partner IDs to be used for uploads. Required.
  optional string bridge_map_version_id = 11;

  // ID of the third party partner updating the transaction feed.
  optional int64 partner_id = 12;
}