openrtb_ext

package
v0.0.0-...-97a8816 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 3, 2018 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Overview

Package openrtb_ext defines all the input validation for Prebid Server's extensions to the OpenRTB 2.5 spec.

Most of these are defined by simple contract classes.

One notable exception is the bidder params, which have more complex validation rules. These are validated by a BidderParamValidator, which relies on the json-schemas from static/bidder-params/{bidder}.json

Index

Constants

View Source
const (
	BidTypeBanner BidType = "banner"
	BidTypeVideo          = "video"
	BidTypeAudio          = "audio"
	BidTypeNative         = "native"
)
View Source
const (
	HbpbConstantKey TargetingKey = "hb_pb"

	// HbEnvKey exists to support the Prebid Universal Creative. If it exists, the only legal value is mobile-app.
	// It will exist only if the incoming bidRequest defiend request.app instead of request.site.
	HbEnvKey TargetingKey = "hb_env"

	// HbBidderConstantKey is the name of the Bidder. For example, "appnexus" or "rubicon".
	HbBidderConstantKey TargetingKey = "hb_bidder"
	HbSizeConstantKey   TargetingKey = "hb_size"
	HbDealIdConstantKey TargetingKey = "hb_deal"

	// HbCacheKey and HbVastCacheKey store UUIDs which can be used to fetch things from prebid cache.
	// Callers should *never* assume that either of these exist, since the call to the cache may always fail.
	//
	// HbVastCacheKey's UUID will fetch the entire bid JSON, while HbVastCacheKey will fetch just the VAST XML.
	// HbVastCacheKey will only ever exist for Video bids.
	HbCacheKey     TargetingKey = "hb_cache_id"
	HbVastCacheKey TargetingKey = "hb_uuid"

	// This is not a key, but values used by the HbEnvKey
	HbEnvKeyApp string = "mobile-app"
)

Variables

View Source
var BidderMap = map[string]BidderName{
	"adkernelAdn":     BidderAdkernelAdn,
	"adtelligent":     BidderAdtelligent,
	"adform":          BidderAdform,
	"appnexus":        BidderAppnexus,
	"beachfront":      BidderBeachfront,
	"audienceNetwork": BidderFacebook,
	"brightroll":      BidderBrightroll,
	"conversant":      BidderConversant,
	"eplanning":       BidderEPlanning,
	"ix":              BidderIx,
	"lifestreet":      BidderLifestreet,
	"openx":           BidderOpenx,
	"pubmatic":        BidderPubmatic,
	"pulsepoint":      BidderPulsepoint,
	"rhythmone":       BidderRhythmone,
	"rubicon":         BidderRubicon,
	"somoaudience":    BidderSomoaudience,
	"sovrn":           BidderSovrn,
	"33across":        Bidder33Across,
}

BidderMap stores all the valid OpenRTB 2.x Bidders in the project. This map *must not* be mutated.

Functions

This section is empty.

Types

type BidType

type BidType string

BidType describes the allowed values for bidresponse.seatbid.bid[i].ext.prebid.type

func BidTypes

func BidTypes() []BidType

func ParseBidType

func ParseBidType(bidType string) (BidType, error)

type BidderName

type BidderName string

BidderName may refer to a bidder ID, or an Alias which is defined in the request.

const (
	BidderAdkernelAdn  BidderName = "adkernelAdn"
	BidderAdtelligent  BidderName = "adtelligent"
	BidderAdform       BidderName = "adform"
	BidderAppnexus     BidderName = "appnexus"
	BidderBeachfront   BidderName = "beachfront"
	BidderBrightroll   BidderName = "brightroll"
	BidderConversant   BidderName = "conversant"
	BidderEPlanning    BidderName = "eplanning"
	BidderFacebook     BidderName = "audienceNetwork"
	BidderIx           BidderName = "ix"
	BidderLifestreet   BidderName = "lifestreet"
	BidderOpenx        BidderName = "openx"
	BidderPubmatic     BidderName = "pubmatic"
	BidderPulsepoint   BidderName = "pulsepoint"
	BidderRhythmone    BidderName = "rhythmone"
	BidderRubicon      BidderName = "rubicon"
	BidderSomoaudience BidderName = "somoaudience"
	BidderSovrn        BidderName = "sovrn"
	Bidder33Across     BidderName = "33across"
)

These names _must_ coincide with the bidder code in Prebid.js, if an adapter also exists in that project. Please keep these (and the BidderMap) alphabetized to minimize merge conflicts among adapter submissions.

func BidderList

func BidderList() []BidderName

BidderList returns the values of the BidderMap

func (BidderName) MarshalJSON

func (name BidderName) MarshalJSON() ([]byte, error)

func (*BidderName) String

func (name *BidderName) String() string

type BidderParamValidator

type BidderParamValidator interface {
	Validate(name BidderName, ext json.RawMessage) error
	// Schema returns the JSON schema used to perform validation.
	Schema(name BidderName) string
}

The BidderParamValidator is used to enforce bidrequest.imp[i].ext.{anyBidder} values.

This is treated differently from the other types because we rely on JSON-schemas to validate bidder params.

func NewBidderParamsValidator

func NewBidderParamsValidator(schemaDirectory string) (BidderParamValidator, error)

NewBidderParamsValidator makes a BidderParamValidator, assuming all the necessary files exist in the filesystem. This will error if, for example, a Bidder gets added but no JSON schema is written for them.

type CookieStatus

type CookieStatus string

CookieStatus describes the allowed values for bidresponse.ext.usersync.{bidder}.status

const (
	CookieNone      CookieStatus = "none"
	CookieExpired   CookieStatus = "expired"
	CookieAvailable CookieStatus = "available"
)

type ExtApp

type ExtApp struct {
	Prebid ExtAppPrebid `json:"prebid"`
}

ExtApp defines the contract for bidrequest.app.ext

type ExtAppPrebid

type ExtAppPrebid struct {
	Source  string `json:"source"`
	Version string `json:"version"`
}

ExtAppPrebid further defines the contract for bidrequest.app.ext.prebid. We are only enforcing that these two properties be strings if they are provided. They are optional with no current constraints on value, so we don't need a custom UnmarshalJSON() method at this time.

type ExtBid

type ExtBid struct {
	Prebid *ExtBidPrebid   `json:"prebid,omitempty"`
	Bidder json.RawMessage `json:"bidder,omitempty"`
}

ExtBid defines the contract for bidresponse.seatbid.bid[i].ext

type ExtBidPrebid

type ExtBidPrebid struct {
	Cache     *ExtBidPrebidCache `json:"cache,omitempty"`
	Targeting map[string]string  `json:"targeting,omitempty"`
	Type      BidType            `json:"type"`
}

ExtBidPrebid defines the contract for bidresponse.seatbid.bid[i].ext.prebid

type ExtBidPrebidCache

type ExtBidPrebidCache struct {
	Key string `json:"key"`
	Url string `json:"url"`
}

ExtBidPrebidCache defines the contract for bidresponse.seatbid.bid[i].ext.prebid.cache

type ExtBidResponse

type ExtBidResponse struct {
	Debug *ExtResponseDebug `json:"debug,omitempty"`
	// ExtResponseErrors defines the contract for bidresponse.ext.errors
	Errors map[BidderName][]ExtBidderError `json:"errors,omitempty"`
	// ExtResponseTimeMillis defines the contract for bidresponse.ext.responsetimemillis
	ResponseTimeMillis map[BidderName]int `json:"responsetimemillis,omitempty"`
	// ExtResponseUserSync defines the contract for bidresponse.ext.usersync
	Usersync map[BidderName]*ExtResponseSyncData `json:"usersync,omitempty"`
}

ExtBidResponse defines the contract for bidresponse.ext

type ExtBidderError

type ExtBidderError struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
}

ExtBidderError defines an error object to be returned, consiting of a machine readable error code, and a human readable error message string.

type ExtHttpCall

type ExtHttpCall struct {
	Uri          string `json:"uri"`
	RequestBody  string `json:"requestbody"`
	ResponseBody string `json:"responsebody"`
	Status       int    `json:"status"`
}

ExtHttpCall defines the contract for a bidresponse.ext.debug.httpcalls.{bidder}[i]

type ExtImp

type ExtImp struct {
	Prebid    *ExtImpPrebid    `json:"prebid"`
	Appnexus  *ExtImpAppnexus  `json:"appnexus"`
	Rubicon   *ExtImpRubicon   `json:"rubicon"`
	Adform    *ExtImpAdform    `json:"adform"`
	Rhythmone *ExtImpRhythmone `json:"rhythmone"`
}

ExtImp defines the contract for bidrequest.imp[i].ext

type ExtImp33across

type ExtImp33across struct {
	SiteId    string `json:"siteId"`
	ZoneId    string `json:"zoneId,omitempty"`
	ProductId string `json:"productId,omitempty"`
}

ExtImp33across defines the contract for bidrequest.imp[i].ext.33across

type ExtImpAdform

type ExtImpAdform struct {
	MasterTagId string `json:"mid"`
	PriceType   string `json:"priceType,omitempty"`
}

type ExtImpAdkernelAdn

type ExtImpAdkernelAdn struct {
	PublisherID int    `json:"pubId"`
	Host        string `json:"host,omitempty"`
}

ExtImpAdkernelAdn defines the contract for bidrequest.imp[i].ext.adkernelAdn

type ExtImpAdtelligent

type ExtImpAdtelligent struct {
	SourceId    int     `json:"aid"`
	PlacementId int     `json:"placementId,omitempty"`
	SiteId      int     `json:"siteId,omitempty"`
	BidFloor    float64 `json:"bidFloor,omitempty"`
}

ExtImpAdtelligent defines the contract for bidrequest.imp[i].ext.adtelligent

type ExtImpAppnexus

type ExtImpAppnexus struct {
	LegacyPlacementId       int                     `json:"placementId"`
	LegacyInvCode           string                  `json:"invCode"`
	LegacyTrafficSourceCode string                  `json:"trafficSourceCode"`
	PlacementId             int                     `json:"placement_id"`
	InvCode                 string                  `json:"inv_code"`
	Member                  string                  `json:"member"`
	Keywords                []*ExtImpAppnexusKeyVal `json:"keywords"`
	TrafficSourceCode       string                  `json:"traffic_source_code"`
	Reserve                 float64                 `json:"reserve"`
	Position                string                  `json:"position"`
	UsePmtRule              *bool                   `json:"use_pmt_rule"`
	// At this time we do no processing on the private sizes, so just leaving it as a JSON blob.
	PrivateSizes json.RawMessage `json:"private_sizes"`
}

ExtImpAppnexus defines the contract for bidrequest.imp[i].ext.appnexus

type ExtImpAppnexusKeyVal

type ExtImpAppnexusKeyVal struct {
	Key    string   `json:"key,omitempty"`
	Values []string `json:"value,omitempty"`
}

ExtImpAppnexusKeyVal defines the contract for bidrequest.imp[i].ext.appnexus.keywords[i]

type ExtImpBeachfront

type ExtImpBeachfront struct {
	AppId    string  `json:"appId"`
	BidFloor float64 `json:"bidfloor"`
}

type ExtImpBrightroll

type ExtImpBrightroll struct {
	Publisher string `json:"publisher"`
}

ExtImpBrightroll defines the contract for bidrequest.imp[i].ext.brightroll

type ExtImpEPlanning

type ExtImpEPlanning struct {
	ExchangeID string `json:"exchange_id"`
}

ExtImpEPlanning defines the contract for bidrequest.imp[i].ext.eplanning

type ExtImpOpenx

type ExtImpOpenx struct {
	Unit         string                 `json:"unit"`
	DelDomain    string                 `json:"delDomain"`
	CustomFloor  float64                `json:"customFloor"`
	CustomParams map[string]interface{} `json:"customParams"`
}

ExtImpOpenx defines the contract for bidrequest.imp[i].ext.openx

type ExtImpPrebid

type ExtImpPrebid struct {
	StoredRequest *ExtStoredRequest `json:"storedrequest"`
}

ExtImpPrebid defines the contract for bidrequest.imp[i].ext.prebid

type ExtImpPubmatic

type ExtImpPubmatic struct {
	PublisherId string                  `json:"publisherId"`
	AdSlot      string                  `json:"adSlot"`
	WrapExt     json.RawMessage         `json:"wrapper,omitempty"`
	Keywords    []*ExtImpPubmaticKeyVal `json:"keywords,omitempty"`
}

type ExtImpPubmaticKeyVal

type ExtImpPubmaticKeyVal struct {
	Key    string   `json:"key,omitempty"`
	Values []string `json:"value,omitempty"`
}

ExtImpAppnexusKeyVal defines the contract for bidrequest.imp[i].ext.appnexus.keywords[i]

type ExtImpRhythmone

type ExtImpRhythmone struct {
	PlacementId string `json:"placementId"`
	Zone        string `json:"zone"`
	Path        string `json:"path"`
	S2S         bool
}

ExtImpRhythmone defines the contract for bidrequest.imp[i].ext.rhythmone

type ExtImpRubicon

type ExtImpRubicon struct {
	AccountId int                `json:"accountId"`
	SiteId    int                `json:"siteId"`
	ZoneId    int                `json:"zoneId"`
	Inventory json.RawMessage    `json:"inventory"`
	Visitor   json.RawMessage    `json:"visitor"`
	Video     rubiconVideoParams `json:"video"`
}

ExtImpRubicon defines the contract for bidrequest.imp[i].ext.rubicon

type ExtImpSomoaudience

type ExtImpSomoaudience struct {
	PlacementHash string  `json:"placement_hash"`
	BidFloor      float64 `json:"bid_floor,omitempty"`
}

type ExtImpSovrn

type ExtImpSovrn struct {
	TagId    string  `json:"tagId,omitempty"`
	Tagid    string  `json:"tagid,omitempty"`
	BidFloor float64 `json:"bidfloor"`
}

type ExtRegs

type ExtRegs struct {

	// GDPR should be "1" if the caller believes the user is subject to GDPR laws, "0" if not, and undefined
	// if it's unknown. For more info on this parameter, see: https://iabtechlab.com/wp-content/uploads/2018/02/OpenRTB_Advisory_GDPR_2018-02.pdf
	GDPR *int8 `json:"gdpr,omitempty"`
}

ExtRegs defines the contract for bidrequest.regs.ext

type ExtRequest

type ExtRequest struct {
	Prebid ExtRequestPrebid `json:"prebid"`
}

ExtRequest defines the contract for bidrequest.ext

type ExtRequestPrebid

type ExtRequestPrebid struct {
	Aliases              map[string]string      `json:"aliases,omitempty"`
	BidAdjustmentFactors map[string]float64     `json:"bidadjustmentfactors,omitempty"`
	Cache                *ExtRequestPrebidCache `json:"cache,omitempty"`
	StoredRequest        *ExtStoredRequest      `json:"storedrequest,omitempty"`
	Targeting            *ExtRequestTargeting   `json:"targeting,omitempty"`
}

ExtRequestPrebid defines the contract for bidrequest.ext.prebid

type ExtRequestPrebidCache

type ExtRequestPrebidCache struct {
	Bids    *ExtRequestPrebidCacheBids `json:"bids"`
	VastXML *ExtRequestPrebidCacheVAST `json:"vastxml"`
}

ExtRequestPrebidCache defines the contract for bidrequest.ext.prebid.cache

func (*ExtRequestPrebidCache) UnmarshalJSON

func (ert *ExtRequestPrebidCache) UnmarshalJSON(b []byte) error

UnmarshalJSON prevents nil bids arguments.

type ExtRequestPrebidCacheBids

type ExtRequestPrebidCacheBids struct{}

ExtRequestPrebidCacheBids defines the contract for bidrequest.ext.prebid.cache.bids

type ExtRequestPrebidCacheVAST

type ExtRequestPrebidCacheVAST struct{}

ExtRequestPrebidCacheVAST defines the contract for bidrequest.ext.prebid.cache.vastxml

type ExtRequestTargeting

type ExtRequestTargeting struct {
	PriceGranularity  PriceGranularity `json:"pricegranularity"`
	IncludeWinners    bool             `json:"includewinners"`
	IncludeBidderKeys bool             `json:"includebidderkeys"`
}

ExtRequestTargeting defines the contract for bidrequest.ext.prebid.targeting

func (*ExtRequestTargeting) UnmarshalJSON

func (ert *ExtRequestTargeting) UnmarshalJSON(b []byte) error

Make an unmarshaller that will set a default PriceGranularity

type ExtResponseDebug

type ExtResponseDebug struct {
	// HttpCalls defines the contract for bidresponse.ext.debug.httpcalls
	HttpCalls map[BidderName][]*ExtHttpCall `json:"httpcalls,omitempty"`
	// Request after resolution of stored requests and debug overrides
	ResolvedRequest *openrtb.BidRequest `json:"resolvedrequest,omitempty"`
}

ExtResponseDebug defines the contract for bidresponse.ext.debug

type ExtResponseSyncData

type ExtResponseSyncData struct {
	Status CookieStatus `json:"status"`
	// Syncs must have length > 0
	Syncs []*ExtUserSync `json:"syncs"`
}

ExtResponseSyncData defines the contract for bidresponse.ext.usersync.{bidder}

type ExtSite

type ExtSite struct {
	// AMP should be 1 if the request comes from an AMP page, and 0 if not.
	AMP int8 `json:"amp"`
}

ExtSite defines the contract for bidrequest.site.ext

func (*ExtSite) UnmarshalJSON

func (es *ExtSite) UnmarshalJSON(b []byte) error

type ExtStoredRequest

type ExtStoredRequest struct {
	ID string `json:"id"`
}

ExtStoredRequest defines the contract for bidrequest.imp[i].ext.prebid.storedrequest

type ExtUser

type ExtUser struct {

	// Consent is a GDPR consent string. See "Advised Extensions" of
	// https://iabtechlab.com/wp-content/uploads/2018/02/OpenRTB_Advisory_GDPR_2018-02.pdf
	Consent string `json:"consent,omitempty"`

	Prebid *ExtUserPrebid `json:"prebid,omitempty"`

	// DigiTrust breaks the typical Prebid Server convention of namespacing "global" options inside "ext.prebid.*"
	// to match the recommendation from the broader digitrust community.
	// For more info, see: https://github.com/digi-trust/dt-cdn/wiki/OpenRTB-extension#openrtb-2x
	DigiTrust *ExtUserDigiTrust `json:"digitrust,omitempty"`
}

ExtUser defines the contract for bidrequest.user.ext

type ExtUserDigiTrust

type ExtUserDigiTrust struct {
	ID   string `json:"id"`   // Unique device identifier
	KeyV int    `json:"keyv"` // Key version used to encrypt ID
	Pref int    `json:"pref"` // User optout preference
}

ExtUserDigiTrust defines the contract for bidrequest.user.ext.digitrust More info on DigiTrust can be found here: https://github.com/digi-trust/dt-cdn/wiki/Integration-Guide

type ExtUserPrebid

type ExtUserPrebid struct {
	BuyerUIDs map[string]string `json:"buyeruids,omitempty"`
}

ExtUserPrebid defines the contract for bidrequest.user.ext.prebid

type ExtUserSync

type ExtUserSync struct {
	Url  string       `json:"url"`
	Type UserSyncType `json:"type"`
}

ExtUserSync defines the contract for bidresponse.ext.usersync.{bidder}.syncs[i]

type GranularityRange

type GranularityRange struct {
	Min       float64 `json:"min"`
	Max       float64 `json:"max"`
	Increment float64 `json:"increment"`
}

GranularityRange struct defines a range of prices used by PriceGranularity

type PriceGranularity

type PriceGranularity struct {
	Precision int                `json:"precision,omitempty"`
	Ranges    []GranularityRange `json:"ranges,omitempty"`
}

PriceGranularity defines the allowed values for bidrequest.ext.prebid.targeting.pricegranularity

func PriceGranularityFromString

func PriceGranularityFromString(gran string) PriceGranularity

PriceGranularityFromString converts a legacy string into the new PriceGranularity

func (*PriceGranularity) UnmarshalJSON

func (pg *PriceGranularity) UnmarshalJSON(b []byte) error

UnmarshalJSON : custom unmarshaller to handle legacy string granularites.

type PriceGranularityRaw

type PriceGranularityRaw PriceGranularity

type TargetingKey

type TargetingKey string

TargetingKeys are used throughout Prebid as keys which can be used in an ad server like DFP. Clients set the values we assign on the request to the ad server, where they can be substituted like macros into Creatives.

Removing one of these, or changing the semantics of what we store there, will probably break the line item setups for many publishers.

These are especially important to Prebid Mobile. It's much more cumbersome for a Mobile App to update code than it is for a website. As a result, they rely heavily on these targeting keys so that any changes can be made on Prebid Server and the Ad Server's line items.

func (TargetingKey) BidderKey

func (key TargetingKey) BidderKey(bidder BidderName, maxLength int) string

type UserSyncType

type UserSyncType string

UserSyncType describes the allowed values for bidresponse.ext.usersync.{bidder}.syncs[i].type

const (
	UserSyncIframe UserSyncType = "iframe"
	UserSyncPixel  UserSyncType = "pixel"
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL