Documentation
¶
Overview ¶
Package prices provides embeddable price scopes for advertisement campaigns and separate actions performed on them.
Three prices ¶
Every action of an advertisement resolves to three different money values:
- PotentialPrice – the maximum price the advertiser could have paid for the action. It is based on the declared maximum bid and is not reduced by any factor. Used to track the discrepancy between the expected and the real price.
- AdvertiserPrice – the price which will be charged from the advertiser. It is the current (post auction) bid as is, with no reduction by any correction factor: the advertiser covers the full cost of running traffic across every connected network, discrepancies included, so none of it is ever deducted from their charge.
- PublisherPrice – the price which the system has to pay to the publisher. It is the same bid reduced by the source and the target discrepancy correction factors and by the system commission share, or a fixed price of the target if it defines one. Whatever these factors remove stays with the network.
The following invariant always holds for non-fixed publisher prices and factors in the 0..1 range:
PublisherPrice <= AdvertiserPrice <= PotentialPrice
Network profit ¶
NetworkProfit is the difference between what the advertiser was charged and what the publisher was paid:
NetworkProfit = AdvertiserPrice - PublisherPrice
Since none of the correction factors ever reduce AdvertiserPrice, NetworkProfit captures both the system commission share and whatever the source/target discrepancy corrections deducted from the publisher payout.
Units ¶
Impression and view bids are stored in CPM units, i.e. the price of 1000 actions, which is the unit used by the external API and by RTB protocols. Click and lead bids are stored as the price of a single action. The action dispatch methods of the PriceScope always operate with the price of one single action, so consumers never convert the units themselves. Use PriceFromCPM and CPMFromPrice if the conversion is required outside of the scope.
No auction rules here ¶
The package performs honest unconditional calculations for every action which has a bid defined. It intentionally knows nothing about pricing models, auction types or which of the simultaneously active models should actually be charged – that is the responsibility of the auction and RTB integration modules.
Embedding ¶
Each pricing model is a small standalone scope with unique field and method names, so any number of them can be embedded into the same structure without selector conflicts:
type Campaign struct {
prices.CPMScope
prices.CPCScope
}
Use the composite PriceScope to get all models at once together with the generic action dispatch and the three price calculations.
Index ¶
- Variables
- func AdvertiserPrice(scope PriceProvider, _ Factors, action adtype.Action) billing.Money
- func BidUpPrice(price billing.Money, factors Factors) billing.Money
- func CPMFromPrice(price billing.Money) billing.Money
- func NetworkProfit(scope PriceProvider, factors Factors, action adtype.Action) billing.Money
- func PotentialPrice(scope PriceProvider, action adtype.Action) billing.Money
- func PriceFromCPM(cpm billing.Money) billing.Money
- func PublisherPrice(scope PriceProvider, factors Factors, action adtype.Action) billing.Money
- type CPAScope
- type CPCScope
- type CPMScope
- type CPMVScope
- type Factors
- type FixedPurchasePricer
- type PriceProvider
- type PriceScope
- func (ps *PriceScope) AdvertiserPricePerAction(action adtype.Action, factors Factors) billing.Money
- func (ps *PriceScope) EffectiveCPM() billing.Money
- func (ps *PriceScope) HasAction(action adtype.Action) bool
- func (ps *PriceScope) MaxPricePerAction(action adtype.Action) billing.Money
- func (ps *PriceScope) NetworkProfitPerAction(action adtype.Action, factors Factors) billing.Money
- func (ps *PriceScope) PotentialPricePerAction(action adtype.Action) billing.Money
- func (ps *PriceScope) PrepareBidPerAction(action adtype.Action, price billing.Money) billing.Money
- func (ps *PriceScope) PricePerAction(action adtype.Action) billing.Money
- func (ps *PriceScope) PublisherPricePerAction(action adtype.Action, factors Factors) billing.Money
- func (ps *PriceScope) SetBidPerAction(action adtype.Action, price billing.Money) error
- func (ps *PriceScope) SetBidPrice(action adtype.Action, price billing.Money, factors Factors, ...) error
- type StaticFactors
Constants ¶
This section is empty.
Variables ¶
var ErrNegativeBidPrice = errors.New("bid price must not be negative")
ErrNegativeBidPrice returns in case of the attempt to set a negative bid price.
var ErrUnsupportedAction = errors.New("action is not supported by the price scope")
ErrUnsupportedAction returns in case of the attempt to set a bid price for the action which is not supported by the price scope.
Functions ¶
func AdvertiserPrice ¶
AdvertiserPrice returns the price which will be charged from the advertiser for the action. The advertiser covers the full cost of running the campaign across every connected network, discrepancies included, so none of the source/target discrepancy correction factors (nor the commission) are subtracted here. The factors argument is accepted only for a uniform signature with the other calculators and is intentionally ignored.
Formula:
AdvertiserPrice = Price
func BidUpPrice ¶
BidUpPrice returns the advertiser-side bid that must be stored so that PublisherPrice recovers the given net price after source/target discrepancy corrections and the system commission are deducted. It is the true inverse of the reduce path used by PublisherPrice (not a (1+factor) markup).
Formula:
BidUpPrice = Price / (1-SourceCorrectionFactor) / (1-TargetCorrectionFactor) / (1-CommissionShareFactor)
func CPMFromPrice ¶
CPMFromPrice converts the price of one single action into the CPM value.
func NetworkProfit ¶
NetworkProfit returns the profit of the network for the action: the difference between what the advertiser was charged and what the publisher was paid. It is the system commission share plus whatever the source and the target discrepancy corrections have deducted from the publisher payout, since none of that is ever subtracted from the advertiser charge.
Formula:
NetworkProfit = AdvertiserPrice - PublisherPrice
func PotentialPrice ¶
func PotentialPrice(scope PriceProvider, action adtype.Action) billing.Money
PotentialPrice returns the maximal price which the advertiser could have paid for the action. The difference with the AdvertiserPrice is the discrepancy of the current placement.
Formula:
PotentialPrice = MaxPrice
func PriceFromCPM ¶
PriceFromCPM converts the CPM value into the price of one single action.
func PublisherPrice ¶
PublisherPrice returns the price which the system has to pay to the publisher for the action: the price reduced by the source and the target discrepancy correction factors and by the system commission share. Whatever these factors remove stays with the network, see NetworkProfit. If the factors value implements the FixedPurchasePricer interface and defines a positive price of the action, that price is used as is.
Formula:
PublisherPrice = Price - SourceCorrectionFactor[%] - TargetCorrectionFactor[%] - CommissionShareFactor[%]
Types ¶
type CPAScope ¶
type CPAScope struct {
// MaxLeadPrice is the maximum price of one lead which the advertiser agreed to
// pay. The zero value means that there is no upper limit.
MaxLeadPrice billing.Money `json:"max_lead_price,omitempty"`
// LeadPrice is the current price of one lead.
// Always less than or equal to the MaxLeadPrice if the last one is defined.
LeadPrice billing.Money `json:"lead_price,omitempty"`
}
CPAScope prices the lead action. Unlike the CPM based scopes both values are stored as the price of one single lead.
The scope can be embedded into any structure which holds the price of the lead action:
type Campaign struct {
prices.CPAScope
}
func (*CPAScope) PrepareLeadPrice ¶
PrepareLeadPrice returns the price of one lead limited by the MaxLeadPrice.
type CPCScope ¶
type CPCScope struct {
// MaxBidCPC is the maximum price of one click which the advertiser agreed to
// pay. The zero value means that there is no upper limit.
MaxBidCPC billing.Money `json:"max_bid_cpc,omitempty"`
// BidCPC is the current price of one click which is used in the auction.
// Always less than or equal to the MaxBidCPC if the last one is defined.
BidCPC billing.Money `json:"bid_cpc,omitempty"`
}
CPCScope prices the click action. Unlike the CPM based scopes both values are stored as the price of one single click.
The scope can be embedded into any structure which holds the price of the click action:
type Campaign struct {
prices.CPCScope
}
func (*CPCScope) PrepareBidCPC ¶
PrepareBidCPC returns the price of one click limited by the MaxBidCPC.
type CPMScope ¶
type CPMScope struct {
// MaxBidCPM is the maximum price of 1000 impressions which the advertiser
// agreed to pay. The zero value means that there is no upper limit.
MaxBidCPM billing.Money `json:"max_bid_cpm,omitempty"`
// BidCPM is the current price of 1000 impressions which is used in the auction.
// Always less than or equal to the MaxBidCPM if the last one is defined.
BidCPM billing.Money `json:"bid_cpm,omitempty"`
}
CPMScope prices the impression action. Both values are stored in CPM units, which is the price of 1000 impressions.
The scope can be embedded into any structure which holds the price of the impression action:
type Campaign struct {
prices.CPMScope
}
func (*CPMScope) PrepareBidCPM ¶
PrepareBidCPM returns the price of 1000 impressions limited by the MaxBidCPM.
type CPMVScope ¶
type CPMVScope struct {
// MaxBidCPMV is the maximum price of 1000 views which the advertiser agreed
// to pay. The zero value means that there is no upper limit.
MaxBidCPMV billing.Money `json:"max_bid_cpmv,omitempty"`
// BidCPMV is the current price of 1000 views which is used in the auction.
// Always less than or equal to the MaxBidCPMV if the last one is defined.
BidCPMV billing.Money `json:"bid_cpmv,omitempty"`
}
CPMVScope prices the view action. Both values are stored in CPM units, which is the price of 1000 views.
The scope can be embedded into any structure which holds the price of the view action:
type Campaign struct {
prices.CPMVScope
}
func (*CPMVScope) PrepareBidCPMV ¶
PrepareBidCPMV returns the price of 1000 views limited by the MaxBidCPMV.
type Factors ¶
type Factors interface {
CommissionShareFactor() float64
// SourceCorrectionFactor of the advertisement source which is excluded as a
// potential discrepancy
SourceCorrectionFactor() float64
// TargetCorrectionFactor of the target endpoint which is excluded as a
// potential discrepancy
TargetCorrectionFactor() float64
}
Factors provides the commission and the discrepancy correction values resolved from the request context: the ad source, the target (zone/smartlink/access point) and the account. All values are percents in the range from 0 to 1.
type FixedPurchasePricer ¶
type FixedPurchasePricer interface {
// FixedPurchasePrice returns the fixed price of the action or 0 if not defined
FixedPurchasePrice(action adtype.Action) billing.Money
}
FixedPurchasePricer is an optional extension of the Factors interface for the targets which define a fixed price of the traffic acceptance. If the value passed to PublisherPrice implements it and returns a positive price, that price overrides any calculation.
type PriceProvider ¶
type PriceProvider interface {
// PricePerAction returns the current price of one action
PricePerAction(action adtype.Action) billing.Money
// MaxPricePerAction returns the maximal possible price of one action
MaxPricePerAction(action adtype.Action) billing.Money
}
PriceProvider is the minimal contract required by the price calculators. It is implemented by PriceScope and can be implemented by any other type which stores the price of the action.
type PriceScope ¶
type PriceScope struct {
CPMScope // Impression pricing
CPMVScope // View pricing
CPCScope // Click pricing
CPAScope // Lead pricing
// ECPM of the advertisement which is used for the internal auction ranking.
// For the CPM model it is equal to the BidCPM, for all the other models it has
// to be predicted from the statistics and assigned by the optimizer module.
ECPM billing.Money `json:"ecpm,omitempty"`
}
PriceScope combines all the pricing models of the advertisement. Any number of them can be defined and used at the same time – the scope does not restrict the combination and does not decide which of them has to be charged.
The scope is designed to be embedded into any campaign or advertisement type:
type Campaign struct {
prices.PriceScope
}
All the dispatch methods operate with the price of one single action, so the CPM units of the impression and the view scopes stay an implementation detail.
func (*PriceScope) AdvertiserPricePerAction ¶
AdvertiserPricePerAction returns the price which will be charged from the advertiser for the action. See AdvertiserPrice.
func (*PriceScope) EffectiveCPM ¶
func (ps *PriceScope) EffectiveCPM() billing.Money
EffectiveCPM returns the CPM value which is used for the internal auction ranking. Fallbacks to the impression bid if the ECPM is not predicted.
func (*PriceScope) HasAction ¶
func (ps *PriceScope) HasAction(action adtype.Action) bool
HasAction returns true if the pricing of the action is defined for the scope.
func (*PriceScope) MaxPricePerAction ¶
func (ps *PriceScope) MaxPricePerAction(action adtype.Action) billing.Money
MaxPricePerAction returns the maximal possible price of one action.
func (*PriceScope) NetworkProfitPerAction ¶
NetworkProfitPerAction returns the profit of the network for the action. See NetworkProfit.
func (*PriceScope) PotentialPricePerAction ¶
func (ps *PriceScope) PotentialPricePerAction(action adtype.Action) billing.Money
PotentialPricePerAction returns the maximal price which the advertiser could have paid for the action. See PotentialPrice.
func (*PriceScope) PrepareBidPerAction ¶
PrepareBidPerAction returns the price of one action limited by the maximal price of the action.
func (*PriceScope) PricePerAction ¶
func (ps *PriceScope) PricePerAction(action adtype.Action) billing.Money
PricePerAction returns the current price of one action.
func (*PriceScope) PublisherPricePerAction ¶
PublisherPricePerAction returns the price which the system has to pay to the publisher for the action. See PublisherPrice.
func (*PriceScope) SetBidPerAction ¶
SetBidPerAction sets the current price of one action. The value is clamped by the maximal price of the action if the last one is defined.
func (*PriceScope) SetBidPrice ¶
func (ps *PriceScope) SetBidPrice(action adtype.Action, price billing.Money, factors Factors, withCommission bool) error
SetBidPrice sets the current bid price for the given action. If withCommission is true, the price is treated as the net amount that must remain after the discrepancy corrections and the commission share are deducted downstream (see PublisherPrice) and is therefore grossed up via BidUpPrice before being stored. If withCommission is false, the price is stored as given. The stored value is then clamped by the maximal price of the action if the last one is defined.
type StaticFactors ¶
type StaticFactors struct {
// Commission share which the system gets from the publisher revenue
Commission float64 `json:"commission,omitempty"`
// Source correction factor of the advertisement source
Source float64 `json:"source,omitempty"`
// Target correction factor of the target endpoint
Target float64 `json:"target,omitempty"`
}
StaticFactors is a plain value implementation of the Factors interface.
func (StaticFactors) CommissionShareFactor ¶
func (f StaticFactors) CommissionShareFactor() float64
CommissionShareFactor implementation of the Factors interface.
func (StaticFactors) SourceCorrectionFactor ¶
func (f StaticFactors) SourceCorrectionFactor() float64
SourceCorrectionFactor implementation of the Factors interface.
func (StaticFactors) TargetCorrectionFactor ¶
func (f StaticFactors) TargetCorrectionFactor() float64
TargetCorrectionFactor implementation of the Factors interface.