Currency conversion utility function

[bszekely1]

Type of issue

The overall objective of Prebid is provide global attributes for those that are common across bid adapters, examples being bidfloor, video attributes, etc. This ticket is specific to support for bid floor. When the currency of the bid floor is different than the currency of the bid adapter supports, there needs to be a method bid adapters can call to convert the currency.

Goals

• Provide a method for PBS bid adapters to convert auction currency of bid floor object

Proposed Design

If the currency conversion feature is enabled in a host PBS instance, Bid Adapters need a utility function to convert currencies of different types. Below are the technical requirements:

1. As an input, the utility function sold take the impression ID and the desired currency
   • The currency conversion function should look up the floor associated with that impression object and convert as needed
2. If the currency feature is not enabled in a PBS instance, the currency conversion utility function should not be available
   • It is the job of the Bid Adapter to check if the utility function exists
     3.If the input currency in the utility function is the same as the set currency, no conversion is necessary
3. if the input currency in the utility function is different, conversion should occur, rounding the converted currency up after a precision of 4 decimal points
4. The response object should include both the converted floor and currency if conversion was applied
   • If desired currency is not available in the currency feature, return the original floor and currency
5. Response should be a JSON object

Interfaces

Request

convertBidFloor(imp.id, currency)

Response

{
 "currency": "USD",
 "bidFloor":  0.3344
}

Other information

[bretg]

We discussed in last week's Prebid Server committee meeting and have a simplified proposal:

provide a simple utility function:

   pbsConvertCurrency(fromCurrency, toCurrency, value)

bid adapters can make use of this function as needed. e.g. if they only support floors in USD, they can convert non-USD imp[].bidfloor values.

[BraslavskiyAndrey]

Hi @bretg, @bszekely1
I need one clarification. PBS has two currency sources, external currency service and currencies from bidrequest.prebid.currencies. If we want to use both, like for bid price currency coversion, utility function will look like:

pbsConvertCurrency(value, bidRequest, fromCurrency, toCurrency)

or if BidAdapter will be responsible for retrieving bidrequest.prebid.currency, utility function will be the same as for bid price:

pbsConvertCurrency(value, requestCurrencies, boolean prioritizePbsRates, fromCurrency, toCurrency)

where prioritizePbsRatescan be retrieved from bidRequest.prebid.currency.usepbsrates or hardcoded by bidAdapter.

If PBS should not use request currencies for converting bidfloor for bidadapters,
pbsConvertCurrency(fromCurrency, toCurrency, value)
should be fine

[bretg]

Good call @BraslavskiyAndrey - this sounds good:

pbsConvertCurrency(value, bidRequest, fromCurrency, toCurrency)

[BraslavskiyAndrey]

prebid/prebid-server-java#968

To make conversion in adapter possible next steps should be done:

1. In you AdapterConfiguration (for example RubiconConfiguration.class )class add next

    @Autowired
    private CurrencyConversionService currencyConversionService;

and pass it to the bidder constructor. Call currencyConversionService method

convertCurrency(BigDecimal price, BidRequest bidRequest, String fromCurrency, String toCurrency)

it will thow PrebidException class if conversion failed with a reason in a message

[SyntaxNode]

Implemented in PBS-Go 0.166.0.

Adapters now have access to a helper method for performing currency conversions with the following signature:

// ConvertCurrency converts a given amount from one currency to another, or returns:
//  - Error if the `from` or `to` arguments are malformed or unknown ISO-4217 codes.
//  - ConversionNotFoundError if the conversion mapping is unknown to Prebid Server
//    and not provided in the bid request.
ConvertCurrency(value float64, from, to string) (float64, error)

The helper method already incorporates both server level and request level currency rates. It is accessible from the requestInfo object as follows:

func (a *adapter) MakeRequests(request *openrtb2.BidRequest, requestInfo *adapters.ExtraRequestInfo) ([]*adapters.RequestData, []error) {
	...
	convertedValue, err := requestInfo.ConvertCurrency(1.42, "USD", "EUR")
	if err != nil {
		// handle error
	}
	...
}