/**
 * This group of objects represent concepts that are interacting, presenting, enclosing, or are 
 * otherwise relating to the world in which impressions live. These include the user, their device,
 * their location, the channel (e.g., site, app, digital out-of-home) with which they are 
 * interacting, the channel's publisher, its content, and any regulations that are in effect
 * (e.g., COPPA, GDPR).
 */
syntax = "proto2";

import "google/protobuf/any.proto";
import "com/iabtechlab/adcom/v1/enums/enums.proto";

package com.iabtechlab.adcom.v1.context;

// Make it fast.
option optimize_for = SPEED;


/**
 * A distribution channel is an abstraction of the various types of entities or channels through 
 * which ads are distributed. Examples include websites, mobile apps, and digital out-of-home (DOOH)
 * systems. This generalized class contains those attributes and relationships that are common to 
 * all distribution channels and as such, all of its attributes and relationships are inherited by 
 * each of its derived classes.
 */
message DistributionChannel {
  // Vendor specific unique identifier of the distribution channel.
  // Recommended.
  optional string id = 1;

  // Displayable name of the distribution channel.
  optional string name = 2;

  // Details about the publisher of the distribution channel.
  // Refer to Object: Publisher.
  optional Publisher pub = 3;

  // Details about the content within the distribution channel.
  // Refer to Object: Content.
  optional Content content = 4;

  // The DistributionChannel implementation details.
  oneof channel_oneof {
    Site site = 5;
    App app = 6;
    DOOH dooh = 7;
  }


  /**
   * This object is used to define an ad supported website, in contrast to a non-browser 
   * application, for example. 
   */
  message Site {
    // Domain of the site (e.g., "mysite.foo.com").
    optional string domain = 1;

    // Array of content categories describing the site using IDs from the taxomony indicated in
    // "cattax".
    repeated string cat = 2;

    // Array of content categories describing the current section of the site using IDs from the
    // taxonomy indicated in "cattax".
    repeated string sectcat = 3;

    // Array of content categories describing the current page or view of the site using IDs from
    // the taxonomy indicated in "cattax".
    repeated string pagecat = 4;

    // The taxonomy in use for the "cat", "sectcat", "pagecat" attributes.
    // Refer to List: com.iabtechlab.adcom.v1.enums.CategoryTaxonomy.
    optional int32 cattax = 5;

    // Indicates if the site has a privacy policy, where false = no, true = yes.
    optional bool privpolicy = 6;

    // Comma-separated list of keywords about the site.
    optional string keywords = 7;

    // URL of the page within the site.
    optional string page = 8;

    // Referrer URL that casued navigation to the current page.
    optional string ref = 9;

    // Search string that caused navigation to the current page.
    optional string search = 10;

    // Indicates if the site has been programmed to optimize layout when viewed on mobile devices,
    // where false = no, true = yes.
    optional bool mobile = 11;

    // Indicates if the page is built with AMP HTML, where false = no, true = yes.
    optional bool amp = 12;

    // Optional vendor-specific extensions.
    extensions 100 to 9999;
  }


  /**
   * This object is used to define an ad supported non-browser application, in contrast to a typical
   * website.
   */
  message App {
    // Domain of the app (e.g., "mygame.foo.com")
    optional string domain = 1;

    // Array of content categories describing the app using IDs from the taxomony indicated in
    // "cattax".
    repeated string cat = 2;

    // Array of content categories describing the current section of the app using IDs from the
    // taxonomy indicated in "cattax".
    repeated string sectcat = 3;

    // Array of content categories describing the current page or view of the app using IDs from
    // the taxonomy indicated in "cattax".
    repeated string pagecat = 4;

    // The taxonomy in use for the "cat", "sectcat", "pagecat" attributes.
    // Refer to List: com.iabtechlab.adcom.v1.enums.CategoryTaxonomy.
    optional int32 cattax = 5;

    // Indicates if the site has a privacy policy, where false = no, true = yes.
    optional bool privpolicy = 6;

    // Comma-separated list of keywords about the app.
    optional string keywords = 7;

    // Bundle or package name of the app (e.g., "com.foo.mygame") and should NOT be app store IDs
    // (e.g., Apple iTunes, Google Play)
    optional string bundle = 8;

    // The ID of the app in an app store (e.g., Apple iTunes, Google Play).
    optional string storeid = 9;

    // App store URL for an installed app; for IQG 2.1 compliance.
    optional string storeurl = 10;

    // Application version.
    optional string ver = 11;

    // Indicator of whether or not this is a paid app, where false = free, true = paid.
    // Default = false
    optional bool paid = 12;

    // Optional vendor-specific extensions.
    extensions 100 to 9999;
  }


  /**
   * This object is used to define an ad supported digital out-of-home (DOOH) experience such as a 
   * public kiosk or digital billboard.
   */
  message DOOH {
    // The type of out-of-home venue.
    // Refer to List: abtechlab.adcom.v1.enums.DOOHVenueType.
    optional int32 venue = 1;

    // Indicates whether the DOOH placement is in a fixed location (e.g., kiosk, billboard,
    // elevator) or is movable (e.g., taxi), where 1 = fixed, 2 = movable.
    optional int32 fixed = 2;

    // The exposure time in seconds per view that the creative will be displayed before refreshing
    // to the next creative.
    optional int32 etime = 3;

    // Minimum DPI for text-based creative elements to display clearly.
    optional int32 dpi = 4;

    // Optional vendor-specific extensions.
    extensions 100 to 9999;
  }
}


/**
 * This object describes the publisher of the media in which ads will be displayed.
 */
message Publisher {
  // Vendor-specific unique publisher identifier, as used in ads.txt files.
  // Recommended.
  optional string id = 1;

  // Displayable name of the publisher.
  optional string name = 2;

  // Highest level domain of the publisher (e.g., "publisher.com").
  optional string domain = 3;

  // Array of content categories that describe the publisher using IDs from the taxonomy indicated
  // in "cattax".
  repeated string cat = 4;

  // The taxonomy in use for the "cat" attribute.
  // Refer to List: com.iabtechlab.adcom.v1.enums.CategoryTaxonomy.
  optional int32 cattax = 5;

  // Optional vendor-specific extensions.
  extensions 100 to 9999;
}


/**
 * This object describes the content in which an impression can appear, which may be syndicated or 
 * non-syndicated content. This object may be useful when syndicated content contains impressions 
 * and does not necessarily match the publisher's general content. An exchange may or may not have 
 * knowledge of the page where the content is running as a result of the syndication method (e.g., 
 * a video impression embedded in an iframe on an unknown web property or device). 
 */
message Content {
  // ID uniquely identifiying the content.
  optional string id = 1;

  // Episode number.
  optional int32 episode = 2;

  // Content title. Video examples: "Search Committee" (television), "Star Wars, A New Hope" (movie),
  // or "Endgame" (made for web). Non-video Example: "Why an Antarctic Glacier Is Melting So Quickly"
  // (Time magazine article).
  optional string title = 3;

  // Content series. Video examples: "The Office" (television), "Star Wars" (movie), or "Arby 'N'
  // The Chief" (made for web). non-video example: "Ecocentric" (Time Magazine blog).
  optional string series = 4;

  // Content season (e.g., "Season 3").
  optional string season = 5;

  // Artist credited with the content.
  optional string artist = 6;

  // Genre that best describes the content (e.g., rock, pop, etc).
  optional string genre = 7;

  // Album to which the content belongs; typically for audio.
  optional string album = 8;

  // International Standard Recording Code conforming to ISO-3901.
  optional string isrc = 9;

  // URL of the content, for buy-sdie contextualization or review.
  optional string url = 10;

  // Array of content categories describing the content using IDs from the taxonomy indicated in
  // "cattax".
  repeated string cat = 11;

  // The taxonomy in use for the "cat" attribute.
  // Refer to List: com.iabtechlab.adcom.v1.enums.CategoryTaxonomy.
  optional int32 cattax = 12;

  // Produciton quality.
  // Refer to List: com.iabtechlab.adcom.v1.enums.ProductionQuality.
  optional int32 prodq = 13;

  // Type of content (game, video, text, etc.).
  // Refer to List: com.iabtechlab.adcom.v1.enums.ContentContext.
  optional int32 context = 14;

  // Content rating (e.g., MPAA).
  optional string rating = 15;

  // User rating of the content (e.g., number of stars, likes, etc.).
  optional string urating = 16;

  // Media rating per IQG guidelines.
  // Refer to List: com.iabtechlab.adcom.v1.enums.MediaRating.
  optional int32 mrating = 17;

  // Array of kewyords describing the content.
  // TOOD(@joelpm): deviates but makes more sense to me.
  repeated string keywords = 18;

  // Indication of live content, where false = not live, true = live (e.g. stream, live blog).
  optional bool live = 19;

  // Source relationship, where 0 = indirect, 1 = direct.
  optional bool srcrel = 20;

  // Length of content in seconds; typically for video or audio.
  optional int32 len = 21;

  // Content language using ISO-639-1-alpha-2.
  optional string lang = 22;

  // Indicator of whether or not the content is embedded off-site from the site or app described
  // in those objects (e.g., an embedded video player), where false = no, true = yes.
  optional bool embed = 23;

  // Details about the content producer.
  // Refer to Object: Producer.
  optional Producer producer = 24;

  // Additional user data. Each "Data" object represents a different data source.
  // Refer to Object: Data.
  repeated Data data = 25;

  // Optional vendor-specific extensions.
  extensions 100 to 9999;
}


/**
 * This object defines the producer of the content in which ad will be displayed. This is 
 * particularly useful when the content is syndicated and may be distributed through different 
 * publishers and thus when the producer and publisher are not necessarily the same entity.
 */
message Producer {
  // Vendor-specific unique producer identifer. Useful if content is syndicated and may be posted
  // a site using using embed tags.
  // Recommended.
  optional string id = 1;

  // Displayable name of the producer.
  optional string name = 2;

  // Highest level domain of the producer (e.g., "producer.com").
  optional string domain = 3;

  // Array of content categories that describe the producer using IDs from the taxonomy indicated
  // in "cattax".
  repeated string cat = 4;

  // The taxonomy in use for the "cat" attributed.
  // Refer to List: com.iabtechlab.adcom.v1.enums.CategoryTaxonomy.
  optional int32 cattax = 5;

  // Optional vendor-specific extensions.
  extensions 100 to 9999;
}


/**
 * See the definition of ExtendedId.
 */
message UniversalId {
  // Cookie or platform-native identifier.
  optional string id = 1;

  // Type of user agent the match is from. It is highly recommended to set this,
  // as many DSPs separate app-native IDs from browser-based IDs and require a type
  // value for ID resolution. Refer to List: Agent Types.
  optional int32 atype = 2;

  // Extensions.
  extensions 100 to 9999;
}


/**
 * Extended identifiers support in the OpenRTB specification allows buyers to
 * use audience data in real-time bidding.  The exchange should ensure that
 * business agreements allow for the sending of this data.  Note, it is
 * assumed that exchanges and DSPs will collaborate with the appropriate
 * regulatory agencies and ID vendor(s) to ensure compliance.
 */
message ExtendedId {
  // Source or technology provider responsible for the set of included IDs.
  // Expressed as a top-level domain.
  optional string source = 1;

  // Array of extended ID UID objects from the given source.
  repeated UniversalId uids = 2;

  // Extensions.
  extensions 100 to 9999;
}


/**
 * This object contains information known or derived about the human user of the device (i.e., the 
 * audience for advertising). The user ID is a vendor-specific artifact and may be subject to 
 * rotation or other privacy policies. However, this user ID must be stable long enough to serve 
 * reasonably as the basis for frequency capping and retargeting.
 */
message User {
  // Vendor-specific ID for th euser. At least one of "id" or "buyeruid" is strongly recommended.
  optional string id = 1;

  // Buyer-specific ID for the user as mapped by an exchange for the buyer. At least one of "id" or
  // "buyeruid" is strongly recommended.
  optional string buyeruid = 2;

  // Year of birth as a 4-digit integer.
  optional int32 yob = 3;

  // Gender, where "M" = male, "F" = female, "O" = known to be other (i.e., omitted is unknown).
  optional string gender = 4;

  // Comma separated list of keywords, interests, or intent.
  optional string keywords = 5;

  // GDPR content string if applicable, complying with the IAB standard Consent String Format in
  // the Transparency and Consent Framework technical specifications.
  optional string consent = 6;

  // Location of the user's home base (i.e., not necessarily their current location).
  // Refer to Object: Geo.
  optional Geo geo = 7;

  // Additional user data. Each "Data" object represents a different data source.
  // Refer to Object: Data.
  repeated Data data = 8;

  // Extended (third-party) identifiers for this user. Refer to Object: Extended Identifiers.
  repeated ExtendedId eids = 9;

  // Optional vendor-specific extensions.
  extensions 100 to 9999;
}


/**
 * This object provides information pertaining to the device through which the user is interacting.
 * Device information includes its hardware, platform, location, and carrier data. The device can 
 * refer to a mobile handset, a desktop computer, set top box, or other digital device.
 */
message Device {
  // The general type of device.
  // Refer to List: com.iabtechlab.adcom.v1.enums.DeviceTypes.
  optional int32 type = 1;

  // Browser user agent string.
  optional string ua = 2;

  // ID sanctioned for advertiser use in the clear (i.e., not hashed).
  optional string ifa = 3;

  // Standard "Do Not Track" flag as set in the header by the browser, where false = tracking is
  // unrestricted, true = do not track.
  optional bool dnt = 4;

  // "Limit Ad Tracking" signal commercially endorsed (e.g., iOS, Android), where false = tracking
  // is unrestricted, true = tracking must be limited per commercial guidelines.
  optional bool lmt = 5;

  // Device make (e.g., "Apple").
  optional string make = 6;

  // Device model (e.g., "iPhone").
  optional string model = 7;

  // Device operating system.
  // Refer to List: com.iabtechlab.adcom.v1.enums.OperatingSystem.
  optional int32 os = 8;

  // Device operating system version (e.g., “3.1.2”).
  optional string osv = 9;

  // Hardware version of the device (e.g. "5S" for iPhone 5S).
  optional string hwv = 10;

  // Physical height of the screen in pixels.
  optional int32 h = 11;

  // Physical width of the screen in pixels.
  optional int32 w = 12;

  // Screen size as pixels per linear inch.
  optional int32 ppi = 13;

  // The ratio of pixels to device independent pixels.
  optional float pxratio = 14;

  // Support for Javascript, where false = no, true = yes.
  optional bool js = 15;

  // Browser language using ISO-639-1-alpha-2.
  optional string lang = 16;

  // IPv4 address closest to device.
  optional string ip = 17;

  // IPv6 address closest to device.
  optional string ipv6 = 18;

  // The value of the x-frowarded-for header.
  optional string xff = 19;

  // Indicator of truncation of any of the IP attributes (i.e., "ip", "ipv6", "xff", where true =
  // yes, false = no (e.g., from 1.2.3.4 to 1.2.3.0).
  // Refer to tools.ietf.org/html/rfc6235#section-4.1.1 for more information on IP truncation.
  optional bool iptr = 20;

  // Carrier or ISP (e.g., "VERIZON") using exchange curated string names which should be published
  // to bidders a priori.
  optional string carrier = 21;

  // Mobile carrier as the concatenated MCC-MNC code (e.g., "310-005" identifies Verizon Wireless 
  // CDMA in the USA). Refer to en.wikipedia.org/wiki/Mobile_country_code for further information 
  // and references. Note that the dash between the MCC and MNC parts is required to remove parsing
  // ambiguity.
  optional string mccmnc = 22;

  // MCC and MNC of the SIM card using the same format as "mccmnc". When both values are available,
  // a difference between them reveals that a user is roaming.
  optional string mccmncsim = 23;

  // Network connection type.
  // Refer to List: com.iabtechlab.adcom.v1.enums.ConnectionType.
  optional int32 contype = 24;

  // Indicates if the geolocation API will be available to Javascript code running in display ad,
  // where false = no, true = yes.
  optional bool geofetch = 25;

  // Location of the device (i.e., typically the user's current location).
  // Refer to Object: Geo.
  optional Geo geo = 26;

  // Optional vendor-specific extensions.
  extensions 100 to 9999;
}


/**
 * This object encapsulates various methods for specifying a geographic location. When subordinate 
 * to a "Device" object, it indicates the location of the device which can also be interpreted as 
 * the user's current location. When subordinate to a "User" object, it indicates the location of 
 * the user's home base (i.e., not necessarily their current location).
 *
 * The "lat" and "lon" attributes should only be passed if they conform to the accuracy depicted in
 * the "type" attribute. For example, the centroid of a large region (e.g., postal code) should not
 * be passed.
 */
message Geo {
  // Source of location data; recommended when passing lat/lon.
  // Refer to List: com.iabtechlab.adcom.v1.enums.LocationType.
  optional int32 type = 1;

  // Latitude from -90.0 to +90.0, where negative is south.
  optional float lat = 2;

  // Longitude from -180.0 to +180.0, where negative is west.
  optional float lon = 3;

  // Estimated location accuracy in meters; recommended when lat/lon are specified and derived from
  // a device's location services (i.e., type = 1). Note that this is the accuracy as reported from
  // the device. Consult OS specific documentation (e.g., Android, iOS) for exact interpretation.
  optional int32 accur = 4;

  // Number of seconds since this geolocation fix was established. Note that devices may cache 
  // location data across multiple fetches. Ideally, this value should be from the time the actual 
  // fix was taken.
  optional int32 lastfix = 5;

  // Service or provider used to determine geolocation from IP address if applicable (i.e.,
  // "type" = 2).
  // Refer to List: com.iabtechlab.adcom.v1.enums.LocationService.
  optional int32 ipserv = 6;

  // Country code using ISO-3166-1-alpha-2. 
  // Note that alpha-3 codes may be encountered and vendors are encouraged to be tolerant of them.
  optional string country = 7;

  // Region code using ISO-3166-2; 2-letter state code if USA
  optional string region = 8;

  // Regional marketing areas such as Nielsen's DMA codes or other similar taxonomy to be agreed 
  // among vendors prior to use. 
  // Note that DMA is a trademarked asset of The Nielsen Company. Vendors are encouraged to ensure 
  // their use of DMAs is properly licensed.
  optional string metro = 9;

  // City using United Nations Code for Trade & Transport Locations "UN/LOCODE" with the space 
  // between country and city suppressed (e.g., Boston MA, USA = "USBOS"). Refer to UN/LOCODE
  // Code List.
  optional string city = 10;

  // ZIP or postal code.
  optional string zip = 11;

  // Local time as the number of +/- of minutes from UTC.
  optional int32 utcoffset = 12;

  // Optional vendor-specific extensions.
  extensions 100 to 9999;
}


/**
 * The data and segment objects together allow additional data about the related object (e.g., 
 * user, content) to be specified. This data may be from multiple sources whether from the exchange
 * itself or third parties as specified by the "id" attribute. When in use, vendor-specific IDs 
 * should be communicated a priori among the parties.
 */
message Data {
  // Vendor-specific ID for the data provider.
  optional string id = 1;

  // Vendor-specific displayable name for the data provider.
  optional string name = 2;

  // Array of "Segment" objects that contain the actual data values.
  // Refer to Object: Segment.
  repeated Segment segment = 3;

  // Optional vendor-specific extensions.
  extensions 100 to 9999;
}


/**
 * Segment objects are essentially key-value pairs that convey specific units of data. The parent 
 * "Data" object is a collection of such values from a given data provider. When in use, vendor-
 * specific IDs should be communicated a priori among the parties.
 */
message Segment {
  // ID of the data segment specific to the data provider.
  optional string id = 1;

  // Displayable name of the data segment specific to the data provider.
  optional string name = 2;

  // String representation of the data segment value.
  optional string value = 3;

  // Optional vendor-specific extensions.
  extensions 100 to 9999;
}


/**
 * This object contains any known legal, governmental, or industry regulations that are in effect.
 */
message Regs {
  // Flag indicating if COPPA regulations apply, where false = no, true = yes. 
  // The Children's Online Privacy Protection Act (COPPA) was established by the U.S. Federal Trade
  // Commission.
  optional bool coppa = 1;

  // Flag indicating if GDPR regulations apply, where false = no, true = yes.
  // The General Data Protection Regulation (GDPR) is a regulation of the European Union.
  optional bool gdpr = 2;

  // Optional vendor-specific extensions.
  extensions 100 to 9999;
}


/**
 * This object allows lists of restrictions on ad responses to be specified including specific
 * content categories, advertisers, ads pertaining to specific apps, or creative attributes.
 */
message Restrictions {
  // Block list of content categories using IDs from the taxonomy indicated in cattax.
  repeated string bcat = 1;

  // The taxonomy in use for the bcat attribute. Refer to List: Category Taxonomies.
  optional int32 cattax = 2;

  // Block list of advertisers by their domains (e.g., “ford.com”).
  repeated string badv = 3;

  // Block list of apps for which ads are disallowed. These should be bundle or package names
  // (e.g., “com.foo.mygame”) and should NOT be app store IDs (e.g., not iTunes store IDs).
  repeated string bapp = 4;

  // Block list of creative attributes. Refer to List: Creative Attributes.
  repeated int32 battr = 5;

  // Optional vendor-specific extensions.
  extensions 100 to 9999;
}