prices

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Nov 15, 2026 License: Apache-2.0 Imports: 3 Imported by: 5

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

Constants

This section is empty.

Variables

View Source
var ErrNegativeBidPrice = errors.New("bid price must not be negative")

ErrNegativeBidPrice returns in case of the attempt to set a negative bid price.

View Source
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

func AdvertiserPrice(scope PriceProvider, _ Factors, action adtype.Action) billing.Money

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

func BidUpPrice(price billing.Money, factors Factors) billing.Money

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

func CPMFromPrice(price billing.Money) billing.Money

CPMFromPrice converts the price of one single action into the CPM value.

func NetworkProfit

func NetworkProfit(scope PriceProvider, factors Factors, action adtype.Action) billing.Money

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

func PriceFromCPM(cpm billing.Money) billing.Money

PriceFromCPM converts the CPM value into the price of one single action.

func PublisherPrice

func PublisherPrice(scope PriceProvider, factors Factors, action adtype.Action) billing.Money

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) HasCPA

func (s *CPAScope) HasCPA() bool

HasCPA returns true if the lead pricing is defined for the scope.

func (*CPAScope) PrepareLeadPrice

func (s *CPAScope) PrepareLeadPrice(price billing.Money) billing.Money

PrepareLeadPrice returns the price of one lead limited by the MaxLeadPrice.

func (*CPAScope) SetLeadPrice

func (s *CPAScope) SetLeadPrice(price billing.Money) error

SetLeadPrice sets the current price of one lead. The value is clamped by the MaxLeadPrice if the last one is defined.

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) HasCPC

func (s *CPCScope) HasCPC() bool

HasCPC returns true if the click pricing is defined for the scope.

func (*CPCScope) PrepareBidCPC

func (s *CPCScope) PrepareBidCPC(bid billing.Money) billing.Money

PrepareBidCPC returns the price of one click limited by the MaxBidCPC.

func (*CPCScope) SetBidCPC

func (s *CPCScope) SetBidCPC(bid billing.Money) error

SetBidCPC sets the current price of one click. The value is clamped by the MaxBidCPC if the last one is defined.

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) HasCPM

func (s *CPMScope) HasCPM() bool

HasCPM returns true if the impression pricing is defined for the scope.

func (*CPMScope) PrepareBidCPM

func (s *CPMScope) PrepareBidCPM(bid billing.Money) billing.Money

PrepareBidCPM returns the price of 1000 impressions limited by the MaxBidCPM.

func (*CPMScope) SetBidCPM

func (s *CPMScope) SetBidCPM(bid billing.Money) error

SetBidCPM sets the current price of 1000 impressions. The value is clamped by the MaxBidCPM if the last one is defined.

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) HasCPMV

func (s *CPMVScope) HasCPMV() bool

HasCPMV returns true if the view pricing is defined for the scope.

func (*CPMVScope) PrepareBidCPMV

func (s *CPMVScope) PrepareBidCPMV(bid billing.Money) billing.Money

PrepareBidCPMV returns the price of 1000 views limited by the MaxBidCPMV.

func (*CPMVScope) SetBidCPMV

func (s *CPMVScope) SetBidCPMV(bid billing.Money) error

SetBidCPMV sets the current price of 1000 views. The value is clamped by the MaxBidCPMV if the last one is defined.

type Factors

type Factors interface {
	// CommissionShareFactor which the system gets from the publisher revenue
	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

func (ps *PriceScope) AdvertiserPricePerAction(action adtype.Action, factors Factors) billing.Money

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

func (ps *PriceScope) NetworkProfitPerAction(action adtype.Action, factors Factors) billing.Money

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

func (ps *PriceScope) PrepareBidPerAction(action adtype.Action, price billing.Money) billing.Money

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

func (ps *PriceScope) PublisherPricePerAction(action adtype.Action, factors Factors) billing.Money

PublisherPricePerAction returns the price which the system has to pay to the publisher for the action. See PublisherPrice.

func (*PriceScope) SetBidPerAction

func (ps *PriceScope) SetBidPerAction(action adtype.Action, price billing.Money) error

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.

Jump to

Keyboard shortcuts

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