com.enremmeta.rtb.api

Interface Tag

All Superinterfaces:

KVKeysValues, Lot49Constants, Lot49Plugin, RtbConstants

All Known Implementing Classes:

SharedSetUp.Tag_2002002_tagMarker_1001001_fake, TagImpl

public interface Tag
extends Lot49Plugin

Specifies configuration of a "tag".

To keep the terminology straight, we define a "tag" to comprise two things:

• Web tag - this is really what most users would think of. It is run in the browser - a piece of HTML/JS/VAST, etc. It is probably generated by an ad server.
• Bid tag - a class implementing current interface. It is a piece of code run in the builder that is responsible for the following major functions (with default implementation provided by methods in TagImpl):

  Functionality	Where implemented
  Holding the parameters of the web tag and creative (e.g., MIME types, dimensions, etc.)	Various fields.
  Checking whether the specified impression request is a match	canBid(OpenRtbRequest, Impression)
  Generating "web tag" to be sent to the browser.	getTag(OpenRtbRequest, Impression, Bid, boolean)
  Generating Bid bid to be sent in the response to the bid request, containing the mentioned web tag as markup or as a reference	getBid(OpenRtbRequest, Impression)

  Thus, in the simplest case, the author of this bid tag just needs to fill in the required fields and override getTagTemplate(OpenRtbRequest, Impression, Bid). However, for more advanced functionality, any method can be overridden.

The naming convention for class names (and, therefore, filenames) to name them Tag_<TagID>_<TagName>_<AdId>_<AdName> where

Author:

Gregory Golberg (grisha@alum.mit.edu) Copyright © Enremmeta LLC 2014. All Rights Reserved. This code is licensed under Affero GPL 3.0

See Also:

Ad

Field Summary

Fields inherited from interface com.enremmeta.rtb.constants.Lot49Constants

AD_FILENAME_PREFIX, AUCTION_RESULTS_PATH_ADX, AUCTION_RESULTS_PATH_OPENX, AUCTION_RESULTS_PATH_PUBMATIC, BID_OUTCOME_CONTROL, BID_OUTCOME_INTERNAL_AUCTION_LOSS, BID_OUTCOME_SUBMITTED, BID_PRICE_CALCULATOR_FILENAME_PREFIX, COOKIE_PREFIX_A, DECISION_BIDS_MADE, DECISION_BIDS_NEEDED, DECISION_BIDS_POSSIBLE, DECISION_BRANDSAFETY, DECISION_BROWSER, DECISION_BUDGET, DECISION_CATEGORY, DECISION_DATE, DECISION_DAY, DECISION_DEVICE, DECISION_DOMAIN_REQUIRED, DECISION_DOMAIN_UNMATCHED, DECISION_EVALUATION_ERROR, DECISION_EXCHANGE, DECISION_EXPERIMENT_CONTROL_SET, DECISION_FLOOR, DECISION_FREQ_CAP, DECISION_GEO, DECISION_HOST, DECISION_HOUR, DECISION_INTEGRAL, DECISION_INTEGRAL_URL, DECISION_INTERNAL_AUCTION, DECISION_IP_BLACKLISTED, DECISION_LANGUAGE, DECISION_LOADING_ERROR, DECISION_NO_IMPRESSIONS, DECISION_NO_USER, DECISION_OS, DECISION_PACING, DECISION_PRIVATE_DEAL, DECISION_PROBABILITY, DECISION_PROVIDER, DECISION_SSP, DECISION_TAG, DECISION_TIMEOUT_EXPERIMENT_STATUS, DECISION_TIMEOUT_FC, DECISION_TIMEOUT_INTEGRAL, DECISION_TIMEOUT_UNKNOWN, DECISION_TIMEOUT_USERDATA, DECISION_TRAQ, DECISION_URL, DECISION_USER_UNKNOWN, DECISION_VALIDATION, DECISION_VIEWABILITY, DECISION_WRONG_USER, DEFAULT_CLICK_PATH_ABSOLUTE, DEFAULT_CLICK_PATH_RELATIVE, DEFAULT_IMPRESSION_PATH_ABSOLUTE, DEFAULT_IMPRESSION_PATH_RELATIVE, DEFAULT_NURL_PATH_ABSOLUTE, DEFAULT_NURL_PATH_RELATIVE, DEFAULT_PIXEL_PATH_ABSOLUTE, DEFAULT_PIXEL_PATH_RELATIVE, DEFAULT_PROUST_PATH_ABSOLUTE, DEFAULT_PROUST_PATH_RELATIVE, DEFAULT_REDIR_PATH_ABSOLUTE, DEFAULT_REDIR_PATH_RELATIVE, DEFAULT_TEST_PATH_RELATIVE, EXCHANGE_ADAPTV, EXCHANGE_ADX, EXCHANGE_BIDSWITCH, EXCHANGE_BRX, EXCHANGE_LIVERAIL, EXCHANGE_LOT49_INTERNAL_AUCTION, EXCHANGE_OPENX, EXCHANGE_PUBMATIC, EXCHANGE_SMAATO, EXCHANGE_SPOTXCHANGE, EXCHANGE_TEST1, EXCHANGE_TEST2, LOT49_VERSION_KEY, LOT49_VERSION_VALUE, MEDIA_TYPE_APPLICATION_JAVASCRIPT, MEDIA_TYPE_APPLICATION_SHOCKWAVE_FLASH, MEDIA_TYPE_VIDEO_FLV, MEDIA_TYPE_VIDEO_MP4, MOD_UID_COOKIE_LENGTH_MAX, MOD_UID_COOKIE_LENGTH_MIN, MOD_UID_LOG_LENGTH, NAME, NURL_ONLY_TAG, NURL_ONLY_WIN_NOTIFICATION, NURL_STANDART, QUERY_STRING_EXCHANGE_CLICK_THROUGH_ENCODED_MACRO, QUERY_STRING_EXCHANGE_CLICK_THROUGH_MACRO, QUERY_STRING_LOT49_CLICK_THROUGH_MACRO, REL_PATH_DEBUG_NURL, ROOT_PATH_ADMIN, ROOT_PATH_AUCTIONS, ROOT_PATH_STATS, TAG_DECISION_API, TAG_DECISION_DIMENSIONS, TAG_DECISION_DURATION, TAG_DECISION_MIME, TAG_DECISION_NOT_BANNER, TAG_DECISION_NOT_VIDEO, TAG_DECISION_PROTOCOL, TAG_DECISION_REQUEST_DISALLOWS_MARKUP, TAG_DECISION_SSL_REQUIRED, TAG_DECISION_VIDEO_LINEARITY, TAG_FILENAME_PREFIX, TEST_MOD_UID_COOKIE_1, TEST_MOD_UID_COOKIE_2, TEST_MOD_UID_COOKIE_3, TEST_MOD_UID_COOKIE_4, TEST_MOD_UID_LOG_1, TEST_MOD_UID_LOG_2, TEST_MOD_UID_LOG_3, TEST_MOD_UID_LOG_4

Fields inherited from interface com.enremmeta.rtb.api.KVKeysValues

B_TOOK_CARE_OF_IT_ERROR, B_TOOK_CARE_OF_IT_LOSS, B_TOOK_CARE_OF_IT_WIN, BID_AMOUNT_DISPLAY_PREFIX, BID_AMOUNT_PREFIX, BID_COUNT_DISPLAY_PREFIX, BID_COUNT_PREFIX, BID_PREFIX, BID_PRICE_PREFIX, BID_REQUEST_PREFIX, BIDDER_COUNT_KEY, BUDGET_CHUNK_SIZE_PREFIX, BUDGET_MAP_KEY, BUDGET_PREFIX, BUDGET_UNLIMITED, COOKIE_TS_CLICK, COOKIE_TS_IMPRESSION, DEBUG_NURL_PREFIX, DECISION_DISPLAY_PREFIX, ENDS_ON_PREFIX, ENV_AWS_REGION, ENV_DYNAMO_ENDPOINT, ENV_EC2_ENDPOINT, ENV_ELB_ENDPOINT, ENV_LOT49_CONFIG_FILE, ENV_LOT49_HOME, ENV_LOT49_MAGIC, ENV_STS_ENDPOINT, LOWER_BID_PROBABILITY, NURL_PREFIX, OWNER_KEY_PREFIX, PACING_ASAP, PACING_LOG_PREFIX, PREFIX_VERSION, PREVIOUS_SPEND_AMOUNT_PREFIX, SEGMENT_PREFIX, SPEND_AMOUNT_DISPLAY_PREFIX, SPEND_AMOUNT_PREFIX, STARTS_ON_PREFIX, USER_DATA_SCORE_KEY, USER_PREFIX_V1, WIN_COUNT_DISPLAY_PREFIX, WIN_COUNT_PREFIX, WIN_RATE_STARTED_TS

Fields inherited from interface com.enremmeta.rtb.constants.RtbConstants

API_MRAID, API_ORMMA, API_VPAID_1, API_VPAID_2, AUCTION_TYPE_FIRST_PRICE, AUCTION_TYPE_FIXED_PRICE, AUCTION_TYPE_SECOND_PRICE_PLUS, AUCTION_TYPE_UNKNOWN, BR_HTML5_1_0_VALUE, BR_HTML5_2_0_VALUE, CONNECTION_TYPE_CELL_2G, CONNECTION_TYPE_CELL_3G, CONNECTION_TYPE_CELL_4G, CONNECTION_TYPE_CELL_UNKNOWN, CONNECTION_TYPE_ETHERNET, CONNECTION_TYPE_UNKNOWN, CONNECTION_TYPE_WIFI, CONTENT_CONTEXT_APP, CONTENT_CONTEXT_GAME, CONTENT_CONTEXT_MUSIC, CONTENT_CONTEXT_OTHER, CONTENT_CONTEXT_TEXT, CONTENT_CONTEXT_UNKNOWN, CONTENT_CONTEXT_VIDEO, DEVICE_TYPE_CONNECTED_DEVICE, DEVICE_TYPE_CONNECTED_TV, DEVICE_TYPE_MOBILE_TABLET, DEVICE_TYPE_PC, DEVICE_TYPE_PHONE, DEVICE_TYPE_STB, DEVICE_TYPE_TABLET, ETHNICITY_AFRICAN_AMERICAN, ETHNICITY_ASIAN, ETHNICITY_HISPANIC, ETHNICITY_OTHER, ETHNICITY_WHITE, LINEARITY_LINEAR, LINEARITY_NON_LINEAR, MARITAL_DIVORCED, MARITAL_MARRIED, MARITAL_SINGLE, VIDEO_PLAYBACK_AUTO_SOUND_OFF, VIDEO_PLAYBACK_AUTO_SOUND_ON, VIDEO_PLAYBACK_CLICK_TO_PLAY, VIDEO_PLAYBACK_MOUSEOVER, VIDEO_PROTOCOL_VAST_1, VIDEO_PROTOCOL_VAST_2, VIDEO_PROTOCOL_VAST_3, VIDEO_PROTOCOL_VAST_WRAPPER_1, VIDEO_PROTOCOL_VAST_WRAPPER_2, VIDEO_PROTOCOL_VAST_WRAPPER_3

Method Summary

Modifier and Type	Method and Description
String	canBid(OpenRtbRequest req, Impression imp) Can this tag be served in response to the provided impression? If null is returned, the answer is yes, otherwise, the string with a reason of why not is returned (for use in logging and troubleshooting).
default String	encode(String s) URLEncode a string
Ad	getAd()
int	getApi()
Bid	getBid(OpenRtbRequest req, Impression imp) Return the fully filled out Bid object, including the tag in the ad markup field.
String	getCb() Cachebuster.
String	getClickRedir(OpenRtbRequest req, Bid bid)
String	getClickUrl(OpenRtbRequest req, Bid bid) Generates a link to the Lot49 click tracker.
String	getCustomImpPassThruData() Custom impression pass-through data.
String	getDesc() Human-readable description
Dimension	getDimension()
int	getDuration() Duration of this ad if it is a video ad.
ExchangeTargeting	getExchangeTargeting()
String	getId() ID of this tag.
String	getImpRedir()
long	getImpressionsConsidered(String exchange)
String	getImpressionUrl(OpenRtbRequest req, Bid bid, boolean nurl) Generates a link to the Lot49 impression tracker.
MarkupType	getMarkupType()
String	getMime()
List<String>	getMimes()
String	getName() Human-readable name.
String	getNUrl(OpenRtbRequest req, Bid bid, String nurlId) Generates a link to NUrl.
SortedMap<String,SortedMap<String,AtomicLong>>	getOptoutsByExchange()
String	getProto(OpenRtbRequest req)
int	getProtocol()
String	getTag(OpenRtbRequest req, Impression imp, Bid bid, boolean nurl) Get the actual tag to send in the ad markup field of the bid (or in the response to nurl), based on the template.
String	getTagTemplate(OpenRtbRequest req, Impression imp, Bid bid) Tag template.
String	getTagVersion()
void	incrOptout(OpenRtbRequest req, String name)
void	init()
boolean	isBanner()
boolean	isLinear()
boolean	isSslCapable()
boolean	isVideo()
boolean	isVpaid()
List<String>	validate()

Method Detail

getDimension

Dimension getDimension()

isBanner

boolean isBanner()

isVideo

boolean isVideo()

getMime

String getMime()

getMimes

List<String> getMimes()

isLinear

boolean isLinear()

isVpaid

boolean isVpaid()

canBid

String canBid(OpenRtbRequest req,
              Impression imp)

Can this tag be served in response to the provided impression? If null is returned, the answer is yes, otherwise, the string with a reason of why not is returned (for use in logging and troubleshooting).

This will always return null if req is a test request.

Parameters:

req - parent request

imp - impression to evaluate

getDuration

int getDuration()

Duration of this ad if it is a video ad.

getOptoutsByExchange

SortedMap<String,SortedMap<String,AtomicLong>> getOptoutsByExchange()

getTagVersion

String getTagVersion()

incrOptout

void incrOptout(OpenRtbRequest req,
                String name)

getImpressionsConsidered

long getImpressionsConsidered(String exchange)

getCb

String getCb()

Cachebuster.

getProto

String getProto(OpenRtbRequest req)

isSslCapable

boolean isSslCapable()

getMarkupType

MarkupType getMarkupType()

getDesc

String getDesc()

Human-readable description

getCustomImpPassThruData

String getCustomImpPassThruData()

Custom impression pass-through data.

Returns:

getId

String getId()

ID of this tag.

Specified by:

getId in interface Lot49Plugin

getImpressionUrl

String getImpressionUrl(OpenRtbRequest req,
                        Bid bid,
                        boolean nurl)

Generates a link to the Lot49 impression tracker.

In case of a non-NUrl-requiring exchange, this URL will include a wp query parameter whose value is the exchange-specific winning price macro.

If impRedir is not null, this URL will include r query parameter whose value is URL-encoded impRedir.

See Also:

Lot49Constants.DEFAULT_CLICK_PATH_ABSOLUTE, Lot49Config.getStatsUrl(), StatsSvc.click(UriInfo, String, String, String, String, String, String, String, String, String, String, String, String, HttpServletRequest, String, String)

getNUrl

String getNUrl(OpenRtbRequest req,
               Bid bid,
               String nurlId)

Generates a link to NUrl.

In case of a NUrl-requiring exchange, this URL will include a wp query parameter whose value is the exchange-specific winning price macro.

getApi

int getApi()

getClickUrl

String getClickUrl(OpenRtbRequest req,
                   Bid bid)

Generates a link to the Lot49 click tracker. If clickRedir is not null, this URL will include r query parameter whose value is URL-encoded clickRedir.

See Also:

Lot49Constants.DEFAULT_CLICK_PATH_ABSOLUTE, Lot49Config.getStatsUrl(), StatsSvc.click(UriInfo, String, String, String, String, String, String, String, String, String, String, String, String, HttpServletRequest, String, String)

getImpRedir

String getImpRedir()

getAd

Ad getAd()

getName

String getName()

Human-readable name.

Specified by:

getName in interface Lot49Plugin

getTag

String getTag(OpenRtbRequest req,
              Impression imp,
              Bid bid,
              boolean nurl)

Get the actual tag to send in the ad markup field of the bid (or in the response to nurl), based on the template.

The provider of the template needs to understand the mechanism of macro substitution. The substitutions occur in the following order, each one going over the entire text of the template.

1. No macro substitutions will be done to clickRedir or impRedir fields. If necessary, override the method appropriately.
2. All occurrences of Macros.MACRO_LOT49_IMPRESSION will be replaced by the URL to the Lot49 impression tracker.
3. TODO Proust
4. Unless the exchange sends actual macros in a call to NUrl, the following click macro substitutions occur:
   1. All occurrences of Macros.MACRO_LOT49_CLICK_CHAIN_ENC are replaced as follows:
      • If there is an exchange click macro, then it is replaced with Macros.MACRO_LOT49_EXCHANGE_CLICK_ENC followed by Macros.MACRO_LOT49_CLICK_ENC_ENC.
      • If the exchange click macro does not exist, then this will be replaced by Macros.MACRO_LOT49_CLICK_ENC
      NOTE The replacement macros, in turn, can be replaced in later passes.
   2. All occurrences of Macros.MACRO_LOT49_CLICK_ENC_ENC will be replaced as Macros.MACRO_LOT49_CLICK (see below), except the replacement will be doubly URL-encoded.
   3. All occurrences of Macros.MACRO_LOT49_CLICK_ENC will be replaced as Macros.MACRO_LOT49_CLICK (see below), except the replacement will be URL-encoded.
   4. All occurrences of Macros.MACRO_LOT49_CLICK will be replaced by the URL to the Lot49 click tracker. If clickRedir is not null, this URL will include r query parameter whose value is URL-encoded clickRedir.
   5. All occurrences of Macros.MACRO_LOT49_EXCHANGE_CLICK_ENC will be replaced by the exchange-specific version thereof.
   6. All occurrences of Macros.MACRO_LOT49_EXCHANGE_CLICK will be replaced by the exchange-specific version thereof.
5. Otherwise, the values for Macros.MACRO_LOT49_CLICK_ENC_ENC , Macros.MACRO_LOT49_CLICK_ENC and Macros.MACRO_LOT49_CLICK are generated, but not replaced. Instead, they are added to the NUrl, and will be substituted at NUrl invocation.

See Also:

ExchangeAdapter.isMacrosInNurl(), getTagTemplate(OpenRtbRequest, Impression, Bid), getImpressionUrl(OpenRtbRequest, Bid, boolean), getClickUrl(OpenRtbRequest, Bid), getBid(OpenRtbRequest, Impression)

getTagTemplate

String getTagTemplate(OpenRtbRequest req,
                      Impression imp,
                      Bid bid)

Tag template. This is pretty much the web tag that is intended to be sent to the browser, but what makes it a template is the fact that it may be parameterized by the following:

1. Any of the fields of the class (that is, anything that has a no-argument getter, e.g. getMime().
2. Any of the local variables which are up to the author of the class overriding this method to define and compute.
3. Macros. The difference of these from the others is that the above substitutions are done during the invocation of this method, whereas the macros are substituted during the actual tag generation. It is at that point, for example, that click and impression tracking URLs are constructed.

   IMPORTANT It is up to the author of the implementing class to understand properly the web tag generation order and insert macros appropriately and encode URLs as needed

See Also:

getTag(OpenRtbRequest, Impression, Bid, boolean), getBid(OpenRtbRequest, Impression)

encode

default String encode(String s)

URLEncode a string

validate

List<String> validate()

getProtocol

int getProtocol()

init

void init()

getExchangeTargeting

ExchangeTargeting getExchangeTargeting()

getBid

Bid getBid(OpenRtbRequest req,
           Impression imp)

Return the fully filled out Bid object, including the tag in the ad markup field.

See Also:

getTag(OpenRtbRequest, Impression, Bid, boolean), getTagTemplate(OpenRtbRequest, Impression, Bid)

getClickRedir

String getClickRedir(OpenRtbRequest req,
                     Bid bid)