// Copyright 2020, Beeswax.IO Inc.
//
// Protocol buffer defining ad log objects such as
// Bids, Impressions, Clicks, Conversions etc.

// The "auctionid" uniquely identifies each bid request in the system and
// should be used to join with other events in the system like RequestLogMessage,
// ImpressionLogMessage, ClickLogMessage, ActivityLogMessage, etc.

// The "user_id" uniquely identifies the user in the system and should be used
// for User-level targeting, modeling, etc.

syntax = "proto2";
package logs;

option java_package = "com.beeswax.logs";

import "beeswax/bid/adcandidate.proto";
import "beeswax/bid/request.proto";
import "beeswax/base/eventid.proto";
import "beeswax/currency/currency.proto";
import "beeswax/openrtb/openrtb.proto";
import "beeswax/openrtb/openrtb_common.proto";

// Next Tag: 6
// RequestLogMessage is created for every incoming bid request from the exchange.
message RequestLogMessage {
  // The unique identifier of the auction per buzz_key.
  // There can be multiple impression definitions in a single bid request from the
  // inventory source; each one Beeswax actually bids on creates a unique auctionid.
  optional base.EventId auctionid = 1;
  optional openrtb.Enums.Inventory.Source inventory_source = 2;
  optional openrtb.BidRequest bidrequest = 3;
  // All the adcandidates that matched targeting, creative attribute
  // and budget filtering and finally sent to the exchange.
  repeated bid.Adcandidate adcandidates = 4;
  // Only data from the winning bid is populated for agent_data.
  optional bid.BidAgentResponse.AgentData agent_data = 5;
}

// Next Tag: 18
// ImpressionLogMessage is created for every won auction.
message ImpressionLogMessage {
  // The unique identifier of the auction per buzz_key.
  // There can be multiple impression definitions in a single bid request from the
  // inventory source; each one Beeswax actually bids on creates a unique auctionid.
  optional base.EventId auctionid = 1;
  // NOTE: auction_id_str is an opaque unique id. Clients should not rely on the meaning
  // of elements within it or on the format of the id.
  optional string auctionid_str = 12;
  // The unique identifier of the bid request per buzz_key. This represents a BidRequest
  // received from an inventory source, which can contain 1 or more impression definitions.
  optional string requestid_str = 17;
  optional base.AdGroupId adgroupid = 2;
  optional uint64 creative_id = 10;
  optional uint64 advertiser_id = 11;

  // Exchange bid price is the final price submitted to exchange.
  optional uint64 exchange_bid_price_micros_usd = 9;
  // Represents the bid price obtained from the bid agent.
  optional uint64 bid_price_micros_usd = 3;
  optional openrtb.Enums.Inventory.Source inventory_source = 4;
  optional string user_id = 5;
  // On GDPR requests, user_id field is omitted and user_id_hashed is populated instead.
  optional string user_id_hashed = 13;

  // Represents the winning price in the auction.
  optional uint64 win_price_micros_usd = 6;
  optional uint64 rx_timestamp_usecs = 7;
  // Represents the win price in the bidder's currency, with the given exchange rate
  optional currency.CurrencyTransaction win_price = 16;

  optional openrtb.Enums.Inventory.DataCenter data_center = 8;

  // When this field is set to true, it implies that Beeswax has determined that
  //  this request needs to comply with the GDPR terms and conditions.
  optional bool is_gdpr = 14 [default = false];
  // The raw IAB consent string or "daisybit" as provided in the incoming bid request.
  optional string gdpr_consent_string = 15;
}

// Next Tag: 14
// ClickLogMessage is created for clicks received.
message ClickLogMessage {
  // The unique identifier of the auction per buzz_key.
  // There can be multiple impression definitions in a single bid request from the
  // inventory source; each one Beeswax actually bids on creates a unique auctionid.
  optional base.EventId auctionid = 1;
  // NOTE: auction_id_str is an opaque unique id. Clients should not rely on the meaning
  // of elements within it or on the format of the id.
  optional string auctionid_str = 9;
  // The unique identifier of the bid request per buzz_key. This represents a BidRequest
  // received from an inventory source, which can contain 1 or more impression definitions.
  optional string requestid_str = 13;
  optional base.AdGroupId adgroupid = 2;
  optional uint64 creative_id = 7;
  optional uint64 advertiser_id = 8;

  optional openrtb.Enums.Inventory.Source inventory_source = 3;
  optional string user_id = 4;
  // On GDPR requests, user_id field is omitted and user_id_hashed is populated instead.
  optional string user_id_hashed = 11;

  // Represents optional data sent by the customer.
  optional string user_data = 5;
  optional uint64 rx_timestamp_usecs = 6;

  enum Type {
    UNKNOWN = 0;
    REGULAR = 1;  // clicks received from creatives
    COMPANION = 2; // clicks received from companion click through url
  }
  optional Type click_type = 10 [default = REGULAR];

  // When this field is set to true, it implies that Beeswax has determined that
  //  this request needs to comply with the GDPR terms and conditions.
  optional bool is_gdpr = 12 [default = false];
}

// Next Tag: 14
// ActivityLogMessage is created for video and activity events
// like video "START", "SKIP", etc.
message ActivityLogMessage {
  // The unique identifier of the auction per buzz_key.
  // There can be multiple impression definitions in a single bid request from the
  // inventory source; each one Beeswax actually bids on creates a unique auctionid.
  optional base.EventId auctionid = 1;
  // NOTE: auction_id_str is an opaque unique id. Clients should not rely on the meaning
  // of elements within it or on the format of the id.
  optional string auctionid_str = 10;
  // The unique identifier of the bid request per buzz_key. This represents a BidRequest
  // received from an inventory source, which can contain 1 or more impression definitions.
  optional string requestid_str = 13;
  optional base.AdGroupId adgroupid = 2;
  optional uint64 creative_id = 8;
  optional uint64 advertiser_id = 9;

  optional openrtb.Enums.Inventory.Source inventory_source = 3;
  enum Type {
    START = 1;        // Video Playback Start
    Q1 = 2;           // Video Playback 25% complete
    MID = 3;          // Video Playback 50% complete
    Q3 = 4;           // Video Playback 75% complete
    COMPLETE = 5;     // Video Playback complete
    SKIP = 6;         // Video Playback skipped
    MUTE = 7;         // Video Playback muted
    UNMUTE  = 8;      // Video Playback unmuted
    PAUSE = 9;        // Video Playback paused
    RESUME = 10;      // Video Playback resumed
    FULLSCREEN = 11;  // Video Playback full screen
    CLOSE = 12;       // Video Playback closed
    COMPANION_VIEW = 13; // Companion view

    // Deprecated. Companion click will be tracked as ClickEvent instead of ActivityEvent
    // This should be eventually removed by end of Q2 of 2017
    DEPRECATED_COMPANION_CLICK = 14;  // Companion click
  }
  optional Type type = 4;
  optional string user_id = 5;
  // On GDPR requests, user_id field is omitted and user_id_hashed is populated instead.
  optional string user_id_hashed = 11;

  // Represents optional data sent by the customer.
  optional string user_data = 6;
  optional uint64 rx_timestamp_usecs = 7;

  // When this field is set to true, it implies that Beeswax has determined that
  //  this request needs to comply with the GDPR terms and conditions.
  optional bool is_gdpr = 12 [default = false];

}

// Next Tag: 11
// Conversion tag urls can be created using the Buzz API.
// Whenever a conversion tag fires, Beeswax records that event into a
// ConversionLogMessage.
// Currently, there are two scenarios in which a conversion tag may fire.
// 1. Conversion Events
//   This occurs whenever the customer trafficks the conversion tag on a site/app
//   and the tag fires whenever a user visits the site/app. For example, a conversion tag
//   may be trafficked on the shopping cart page of a retail portal.
//   For conversion events, the following fields are always expected to be populated:
//   a) tag_id
//   b) user_id
//
// 2 Postback Events
//  In this scenario, the conversion attribution is determined by a third party and the
//  conversion tag is used by the third party to credit a particular impression/click for
//  the conversion. For postback events, the following fields are always expected to be
//  populated:
//   a) tag_id
//   b) auctionid
//
message ConversionLogMessage {
  optional string user_id = 1;
  // Customer defined transaction value e.g. Price in shopping cart.
  optional string value = 2;
  // Usually, the number of items purchased
  optional string order = 3;
  // Customer defined unique join key. Also works as cache buster.
  optional string ord = 4;
  // Event Id corresponding to the tag created via the Buzz API
  optional int32 tag_id = 5;
  // Unique buzz_key of the customer.
  optional string buzz_key = 6;
  // Timestamp (usecs) at which event was received by Beeswax.
  optional uint64 rx_timestamp = 7;
  // auction id (Filled only for postback events)
  optional string auctionid = 8;

  // When this field is set to true, it implies that Beeswax has determined that
  //  this request needs to comply with the GDPR terms and conditions.
  optional bool is_gdpr = 10 [default = false];
}

// Next Tag: 7
// AdLogMessage serves as a wrapper type and holds all ad log objects.
// This message gets logged to the AWS Kinesis streams.

// Note: BeeswaxIO DOES NOT aggregate the ad log objects on same "auction_id";
// All events are logged to Kinesis as and when they arrive in the system.
message AdLogMessage {
  optional RequestLogMessage request = 1;
  optional ImpressionLogMessage impression = 2;
  // click field will be deprecated, start using clicks (field 6) instead
  optional ClickLogMessage click = 3 [deprecated = true];
  repeated ActivityLogMessage activity = 4;
  optional ConversionLogMessage conversion = 5;
  // List of all possible clicks, regular and companion
  repeated ClickLogMessage clicks = 6;
}