package i18n_ssp.api;
// OpenRTB Native 1.0: Common asset element types of native advertising.
// This list is non-exhaustive and intended to be extended by the buyers
// and sellers as the format evolves. An implementing exchange may not
// support all asset variants or introduce new ones unique to that system.
enum DataAssetType {
// Sponsored By message where response should contain the brand name
// of the sponsor.
// Format: Text; Max length: 25 or longer.
SPONSORED = 1;
// Descriptive text associated with the product or service being advertised.
// Format: Text; Max length: 140 or longer.
DESC = 2;
// Rating of the product being offered to the user.
// For example an app's rating in an app store from 0-5.
// Format: Number (1-5 digits) formatted as string.
RATING = 3;
// Number of social ratings or "likes" of product being offered to the user.
// Format: Number formatted as string.
LIKES = 4;
// Number downloads/installs of this product.
// Format: Number formatted as string.
DOWNLOADS = 5;
// Price for product / app / in-app purchase.
// Value should include currency symbol in localised format.
// Format: Number formatted as string.
PRICE = 6;
// Sale price that can be used together with price to indicate a discounted
// price compared to a regular price. Value should include currency symbol
// in localised format.
// Format: Number formatted as string.
SALEPRICE = 7;
// Phone number.
// Format: Formatted string.
PHONE = 8;
// Address.
// Format: Text.
ADDRESS = 9;
// Additional descriptive text associated with the product or service
// being advertised.
// Format: Text.
DESC2 = 10;
// Display URL for the text ad.
// Format: Text.
DISPLAYURL = 11;
// Text describing a 'call to action' button for the destination URL.
// Format: Text.
CTATEXT = 12;
// Exchange-specific values above 500.
}
message Device{
enum DeviceType {
PHONE = 1;
TABLET = 2;
};
enum ConnectionType {
UNKNOWN = 0; //
ETHERNET = 1;
WIFI = 2;
CN_UNKNOWN = 3; //Cellular Network – Unknown Generation
CN_2G = 4; //Cellular Network – 2G
CN_3G = 5; //Cellular Network – 3G
CN_4G = 6; //Cellular Network – 4G
};
message Geo {
enum GeoType{
GPS = 1;
IP = 2;
FromUser = 3;
}
optional float lat = 1; //Latitude from -90.0 to +90.0, where negative is south.
optional float lon = 2; //Longitude from -180.0 to +180.0, where negative is west
optional GeoType type = 3; //Source of location data; recommended when passing lat/lon
optional string country = 4; //Country code using ISO-3166-1-alpha-3.
optional string region = 5; //Region code using ISO-3166-2; 2-letter state code if USA.
optional string city = 6; //City using United Nations Code for Trade & Transport Locations.
}
optional string ua = 1; //Browser user agent string
optional Geo geo = 2; //Location of the device assumed to be the user’s current location defined by a Geo object
optional int64 dnt = 3; //Standard “Do Not Track” flag as set in the header by thebrowser, where 0 = tracking is unrestricted, 1 = do not track.
optional string ip = 4; // IPv4 address closest to device.
optional string ipv6 = 5; // IP address closest to device as IPv6.
optional DeviceType devicetype = 6; // The general type of device.
optional string make = 7; // Device make
optional string model = 8; // Device model
optional string os = 9; // Device operating system
optional string osv = 10; // Device operating system version
optional string hwv = 11; // Hardware version of the device
optional int64 h = 12; // Physical height of the screen in pixels
optional int64 w = 13; // Physical width of the screen in pixels
optional int64 ppi = 14; //Screen size as pixels per linear inch.
optional float pxratio = 15; //The ratio of physical pixels to device independent pixels.
optional string carrier = 16; //Carrier or ISP (e.g., “VERIZON”). “WIFI” is often used in mobile to indicate high bandwidth (e.g., video friendly vs. cellular)..
optional ConnectionType connectiontype = 17; //Network connection type.
optional string didsha1 = 18; //Hardware device ID (e.g., IMEI); hashed via SHA1.
optional string didmd5 = 19; //Hardware device ID (e.g., IMEI); hashed via MD5.
optional string dpidsha1 = 20; //Platform device ID (e.g., Android ID); hashed via SHA1.
optional string dpidmd5 = 21; //Platform device ID (e.g., Android ID); hashed via MD5.
optional string macidsha1 = 22; //MAC address of the device; hashed via SHA1.
optional string macidmd5 = 23; //MAC address of the device; hashed via MD5
optional string ifa = 24; //ID sanctioned for advertiser use in the clear (i.e., not hashed)
optional string language = 25; // Browser language using ISO-639-1-alpha-2.
}
message Publisher{
optional int64 id = 1;//Exchange-specific publisher ID
optional string name = 2; //Publisher name
repeated string cat = 3;//Array of IAB content categories that describe the publisher
optional string domain = 4; //Highest level domain of the publisher
}
message App{
required int64 id = 1;//Exchange-specific app ID.
required string name = 2;// App name
optional string bundle = 3;//Application bundle or package name
optional string domain = 4;//Domain of the app
optional string storeurl = 5;//App store URL for an installed app
repeated string cat = 6;//Array of IAB content categories of the app
optional string ver = 7;//Application version.
optional int64 privacypolicy = 8; //Indicates if the app has a privacy policy, where 0 = no, 1 = yes.
optional int64 paid = 9;//0 = app is free, 1 = the app is a paid version
optional Publisher publisher = 10; //Details about the Publisher of the app.
//optional Content content = 11;//Details about the Content within the app.
optional string keywords = 12; //Comma separated list of keywords about the app.
}
enum VideoProtocol{
VAST1 = 1; //1 VAST 1.0
VAST2 = 2; // 2 VAST 2.0
VAST3 = 3; //3 VAST 3.0
VAST1WRAPPER = 4; //4 VAST 1.0 Wrapper
VAST2WRAPPER = 5; //5 VAST 2.0 Wrapper
VAST3WRAPPER = 6; //6 VAST 3.0 Wrapper
}
enum PlayMethod{
AUTO_PLAY_ON = 1;
AUTO_PLAY_OFF = 2;
CLICK_TO_PLAY = 3;
}
enum ImageAssetType {
// Icon image.
// Max height: at least 50; Aspect ratio: 1:1.
ICON = 1;
// Logo image for the brand/app.
// To be deprecated in a future version - use type 1 / ICON.
// DEPRECATED in 1.2
LOGO = 2;
// Large image preview for the ad.
// At least one of 2 size variants required:
// Small Variant: max height: 200+, max width: 200+, 267, or 382,
// aspect ratio: 1:1, 4:3, or 1.91:1.
// Large Variant: max height: 627+, max width: 627+, 836, or 1198,
// aspect ratio: 1:1, 4:3, or 1.91:1.
MAIN = 3;
// Exchange-specific values above 500.
}
message Imp{
enum Position {
BelowTheFold = 3; //
};
message Banner{
required int64 w = 1 ; //Width of the impression in pixels.
required int64 h = 2; //Height of the impression in pixels.
optional Position pos = 3; //Ad position on screen.
};
message Asset{
message Title{
optional int64 len = 1; //Maximum length of the text in the title element
};
message Img{
optional ImageAssetType type = 1; // Supported images type IDs:1 - Icon 2 - Logo 3 - Main
optional uint32 w = 2; //Width of the impression in pixels.
optional uint32 wmin = 3; //Maximum width of the impression in pixels
optional uint32 h = 4; //Height of the impression in pixels.
optional uint32 hmin = 5; //Minimum width of the impression in pixels
repeated string mimes = 6; //Whitelist of content MIME types supported. Popular MIME types include, but are not limited to “image/jpg” “image/gif”.
};
message Video{
repeated string mimes = 1; //Content MIME types supported. Popular MIME types may include “video/x-ms-wmv” for Windows Media and “video/x-flv” for Flash Video.
optional int64 minduration = 2; //Minimum video ad duration in seconds.
optional int64 maxduration = 3; //Maximum video ad duration in seconds.
repeated VideoProtocol protocols = 4; //An array of video protocols the publisher can accept in the bid response.
};
// OpenRTB Native 1.0: The Data Object is to be used for all non-core
// elements of the native unit such as Ratings, Review Count, Stars,
// Download count, descriptions etc. It is also generic for future of Native
// elements not contemplated at the time of the writing of this document.
message Data {
// Type ID of the element supported by the publisher. The publisher can
// display this information in an appropriate format.
// REQUIRED by the OpenRTB Native specification.
required DataAssetType type = 1;
// Maximum length of the text in the element's response. Longer strings
// may be truncated and ellipsized by Ad Exchange or the publisher during
// rendering.
optional int32 len = 2;
}
required int64 id = 1;
required uint32 required = 2; //Set to 1 if asset is required(exchange will not accept a bid without it)
optional Title title = 3; //
optional Img img = 4; //
optional Video video = 5; //
optional Data data = 6; //
};
message Native{
enum Layout {
NEWSFEED = 3;
CONTENTSTREAM = 6;
};
optional string ver = 1; //Version of the Dynamic Native Ads API to which request complies
optional Layout layout = 2; //The Layout ID of the native ad
repeated Asset assets = 3; //???An array of Asset Objects. Any bid must comply with a native ad that matches this array of elements.
};
message Video {
repeated string mimes = 1; //Content MIME types supported. Popular MIME types may include “video/x-ms-wmv” for Windows Media and “video/x-flv” for Flash Video.
optional int64 minduration = 2; //Minimum video ad duration in seconds.
optional int64 maxduration = 3; //Maximum video ad duration in seconds.
repeated VideoProtocol protocols = 4; //Array of supported video bid response protocols
required int64 w = 5; //Width of the video player in pixels.
required int64 h = 6; //Height of the video player in pixels.
optional int64 startdelay = 7; //indicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placement
optional int64 minbitrate = 8; //Minimum bit rate in Kbps
optional int64 maxbitrate = 9; //Maximum bit rate in Kbps
optional uint32 boxingallowed = 10; //Indicates if letter-boxing of 4:3 content into a 16:9 window is allowed, where 0 = no, 1 = yes.
optional PlayMethod playbackmethod = 11; //Allowed playback methods. If none specified, assume all are allowed
}
required string id = 1; //A unique identifier for this impression within the context of the bid request (typically, starts with 1 and increments.)
optional Banner banner = 2; //A Banner object; required if this impression is offered as a banner ad opportunity
optional Native native = 3; //A Native object; required if this impression is offered as a native ad opportunity.
optional Video video = 4; //A Video object; required if this impression is offered as a video ad opportunity.
required float bidfloor = 5;//Minimum bid for this impression expressed in CPM
required string bidfloorcur = 6; //Currency specified using ISO-4217 alpha codes. This may be different from bid currency returned by bidder if this is allowed by the exchange.
};
message User{
required string id = 1; //Exchange-specific ID for the user
optional int64 yob = 2; //Year of birth as a 4-digit integer.
optional string gender = 3; //Gender, where “M” = male, “F” = female, “O” = known to be other (i.e., omitted is unknown).
}
message BidRequest {
required string id = 1; //Unique ID of the bid request, provided by the exchange.
repeated Imp imp = 2; //Array of Imp objects representing the impressions offered.
optional App app = 3; //Details via an App object about the publisher’s app (i.e., non-browser applications).
optional Device device = 4; //Details via a Device object about the user’s device to which the impression will be delivered.
optional User user = 5; //Details via a User object about the human user of the device; the advertising audience.
optional uint32 test = 6; //Indicator of test mode in which auctions are not billable, where 0 = live mode, 1 = test mode.
optional uint32 at = 7; //Auction type, where 1 = First Price, 2 = Second Price Plus.
optional uint32 tmax = 8; //Maximum time in milliseconds to submit a bid to avoid
repeated string cur = 9; //Array of allowed currencies for bids on this bid request using ISO-4217 alpha codes.
repeated string wlang = 10;// White list of languages for creatives using ISO-639-1-alpha-2. Omission implies no specific restrictions, but buyers would be advised to consider language attribute in the Device
};
message Bid{
message Title{
required string text = 1; //The text associated with the text element.
};
message Img{
optional ImageAssetType type = 1; // Supported images type IDs:1 - Icon 2 - Logo 3 - Main
required string url = 2; //URL of the image asset
required int64 h = 3; //Height of the image in pixels.
required int64 w = 4; //Width of the image in pixels.
};
message Video{
required string vasttag = 1; //VAST xml
};
message Link{
required string url = 1; //Landing URL of the clickable link.
repeated string clicktrackers = 2; //List of third-party tracker URLs to be fired on click of the URL.
};
// OpenRTB Native 1.0: Corresponds to the Data Object in the request, with
// the value filled in. The Data Object is to be used for all miscellaneous
// elements of the native unit such as Brand Name, Ratings, Review Count,
// Stars, Downloads, etc. It is also generic for future of native elements
// not contemplated at the time of the writing of this document.
message Data {
// The type of data element being submitted from the DataAssetTypes enum.
// REQUIRED in 1.2 for assetsurl or dcourl responses.
// Implemented in 1.2.
optional DataAssetType type = 1;
// The length of the data element being submitted. Where applicable, must
// comply with the recommended maximum lengths in the DataAssetType enum.
// REQUIRED in 1.2 for assetsurl or dcourl responses.
// Implemented in 1.2.
optional int32 len = 2;
// The formatted string of data to be displayed. Can contain a formatted
// value such as "5 stars" or "$10" or "3.4 stars out of 5".
// REQUIRED by the OpenRTB Native specification.
required string value = 3;
}
message Asset{
required int64 id = 1; //Unique asset ID, assigned by exchange, must match one of the asset IDs in request
optional Title title = 2;
optional Img img = 3;
optional Video video = 4;
optional Data data = 5;
};
message Creative{
repeated Asset assets = 1; //List of native ad’s assets.
required Link link = 2; //Destination Link. This is default link object for the ad.
repeated string imptrackers = 3; //Array of impression tracking URLs, expected to return a 1x1 image or 204 response - typically only passed when using 3rd party trackers
};
required string id = 1; //Bidder generated bid ID to assist with logging/tracking.
required string impid = 2; //ID of the Imp object in the related bid request.
required float price = 3; //Bid price expressed as CPM although the actual transaction is for a unit impression only
required int64 adid = 4; //ID of a preloaded ad to be served if the bid wins.
optional string nurl = 5; //Win notice URL called by the exchange if the bid wins; optional means of serving ad markup.
optional string cid = 6; //Campaign ID to assist with ad quality checking; the collection of creatives for which iurl should be representative.
optional string crid = 7; //Creative ID to assist with ad quality checking.
optional string cat = 8; // AB content categories of the creative.
repeated int64 attr = 9; //Set of attributes describing the creative.
optional string language = 10;
required Creative creative = 11;
}
message SeatBid{
repeated Bid bid = 1; //Array of 1+ Bid objects each related to an impression. Multiple bids can relate to the same impression.
optional string seat = 2; //ID of the buyer seat on whose behalf this bid is made.
}
message BidResponse{
required string id = 1; //ID of the bid request to which this is a response.
repeated SeatBid seatbid = 2; //Array of seatbid objects; 1+ required if a bid is to be made.
required string cur = 3; //Bid currency using ISO-4217 alpha codes
}