This module supports the conversion of multiple bidder currencies into a single currency used by the publisher’s ad server. In previous versions of Prebid, this was accomplished by using BidderSettings.bidCpmAdjustment, but that’s a static value not changed except when the web development team makes a manual update.
Publishers may continue to use the bidCpmAdjustment approach, or may begin using this optional module, gaining automatic updates as currency exchange rates fluctuate. Here’s how it works at a high level:
The numbered circles in this diagram are explained below.
Ad server line items must be created so that the price bucket boundaries match
what will be provided at runtime. Before this feature, many publishers using
non-USD currencies didn’t benefit from Prebid’s
default granularities – they had to set up custom price buckets. Now the 5 default
granularities can be scaled to other currencies with a granularityMultiplier
.
For example, the default Prebid “low granularity” bucket is:
USD$0.50 increments, capped at USD$5 |
The following config translates the “low granularity” bucket with a conversion rate of 108 yen to 1 US dollar. It also defines the default conversion rate as being 110 yen to the dollar.
This results in a granularity rule that’s scaled up to make sense in Yen:
¥54 increments, capped at ¥540 |
Notes:
The multiplier doesn’t have to be an exact exchange rate. Rather, it can be designed to make sense for the publisher. e.g. maybe a multiplier of 100 gives nice rounded buckets with good enough bucket distribution. If the ad server currency is close in value to USD, you may consider leaving the granularityMultiplier at 1. Basically, the goal of the granularityMultiplier is to scale up the default Prebid buckets where they would otherwise cap out too low for some currencies. e.g. Capping out at 5 yen makes the “low” granularity bucket pretty useless.
The Prebid config in the page needs to match the assumptions made when defining the
ad server line items. The setConfig
example above does two important things:
There are other options explained below, but these are the key ones needed to understand how the currency feature works.
When the bids come back, the bidder adapter identifies which currency the bid is in. If an adapter doesn’t define the bid currency, it’s assumed to be USD.
Note that before Prebid 1.0, adapters may not properly register the currency of their bids. See the `bidderCurrencyDefault` config setting below for an interim solution.
The platform will detect whether a conversion is needed from the bid currency to the ad server currency and is pretty smart about using the conversion file to do so: if a direct conversion isn’t available, it will try to find a one-hop conversion. e.g. if the bid is in AUD and needs to be converted to BRL, it could convert to AUD-USD first, then USD-BRL.
All price granularities, including custom granularities, are scaled by the value of the granularityMultiplier, which defaults to 1.
As noted above, this is done to make Prebid’s granularity buckets useful to all currencies.
For instance, if the current conversion rate is ¥110 to the dollar, then a bid of USD$1.55 would be converted to ¥170.50, which gets put into the low granularity bucket hb_pb=162.
Finally, the scaled and quantized bids are sent to the ad server, where they will match the line items set up initially.
No other part of the Prebid process has changed due to currency support: creation of AdUnits, creative display, analytics, etc.
Running through a full set of numbers may help understand how components of this feature come together.
Say the line items are set up to align with the Prebid low price granularity option with a granularityMultiplier of 108: ¥54 increments up to ¥540. This is the table of all values in the low granularity setting:
USD | JPY | Line Item Target |
---|---|---|
0.00 | 0 | hb_pb=0 |
0.50 | 54 | hb_pb=54 |
1.00 | 108 | hb_pb=108 |
1.50 | 162 | hb_pb=162 |
2.00 | 216 | hb_pb=216 |
2.50 | 270 | hb_pb=270 |
3.00 | 324 | hb_pb=324 |
3.50 | 378 | hb_pb=378 |
4.00 | 432 | hb_pb=432 |
4.50 | 486 | hb_pb=486 |
5.00 | 540 | hb_pb=540 |
The bids take place and a bunch of responses come back. Some of the bids require conversion, and they’re all run through the low price granularity. The current conversion rate from USD to JPY is 110.
Bidder | Bid | Bid Currency | Bid Converted to JPY | Result of price granularity |
---|---|---|---|---|
A | 1.55 | USD | 170.50 | hb_pb_a=162 |
B | 151 | JPY | 151 | hb_pb_b=108 |
C | 0.90 | ? (USD assumed) | 99.9 | hb_pb_b=54 |
Adding the currency module to a page is done with a call to the setConfig API with one or more parameters. The simplest recommended implementation would be:
Note that the defaultRates
attribute is optional, but recommended in case there’s an issue loading the currency file.
In this example, the publisher is providing their own conversionRateFile
:
And finally, here’s an example where the conversion rate is specified right in the config, so the external file won’t be loaded:
Follow the basic build instructions on the Gihub repo’s main README. To include the module, an additional option must be added to the the gulp build command:
This command will build the following files:
After testing, get your javascript file(s) out to your Content Delivery Network (CDN) as normal.
Note that there are more dynamic ways of combining these components for publishers or integrators ready to build a more advanced infrastructure.
No additional functions are provided with this module. Rather, the setConfig() call takes a currency object that may contain several parameters:
Param | Type | Description | Example |
---|---|---|---|
adServerCurrency | string |
ISO 4217 3-letter currency code. If this value is present, the currency conversion feature is activated. | “EUR” |
granularityMultiplier | decimal |
How much to scale the price granularity calculations. Defaults to 1. | 108 |
conversionRateFile | URL |
Optional path to a file containing currency conversion data. See below for the format. Prebid.org hosts a file as described in the next section. | https://example.com/rates.json |
rates | object | This optional argument allows you to specify the rates with a JSON object, subverting the need for the conversionRateFile parameter. If this argument is specified, the conversion rate file will not be loaded. | { ‘USD’: { ‘CNY’: 6.8842, ‘GBP’: 0.7798, ‘JPY’: 110.49 } } |
defaultRates | object |
An optional but highly recommended parameter that defines a default rate that can be used if the currency file cannot be loaded. This option isn’t used when the rates parameter is supplied. |
{ ‘USD’: { ‘GPB’: 0.75 }} |
bidderCurrencyDefault | object |
This is an optional argument to provide publishers a way to define which currency is used by a particular bidder. This option was provided as a transition until such a time that most bidder adapters define currency on bid response and is kept for legacy 0.x integrations. | { “bidderXYZ”: “GBP” } |
Prebid.org hosts a conversion file at https://cdn.jsdelivr.net/gh/prebid/currency-file@1/latest.json. The currencies currently supported are: AUD, BGN, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HRK, HUF, IDR, ILS, INR, ISK, JPY, KRW, MXN, MYR, NOK, NZD, PHP, PLN, RON, RUB, SEK, SGD, THB, TRY, USD, ZAR.
The currencies on this list could change if the underlying API source changes. If a desired currency isn’t on this list, you will need to generate and host your own conversion file.
Publishers may host their own currency conversion file, whether because the community file doesn’t support a particular currency, because more precision is needed, or because they want control over the freshness of the conversion data.
The file format expected by the Prebid platform is illustrated by the example below.
{
"dataAsOf":"2018-03-13",
"conversions":{
"USD":{ // from USD to other currencies
"AUD":1.321,
"BRL":3.1253,
"CAD":1.3431,
"CHF":0.99613,
"CNY":6.8852,
...
},
"GPB": { // can optionally supply direct conversions
... // from multiple currencies
}
}
}
Does loading the currency conversion file slow down the auction?
No, the auction is not delayed by the loading of the currency file. Since it’s a simple flat file on a global CDN and cachable for 24 hours, we expect that the file will be loaded well before bids return.
What happens if the file doesn’t load on time or not at all or doesn’t contain a necessary conversion?
If the currency feature is turned on and the conversion file’s not back by the time the system
needs to convert a bid, the defaultRates
will be used. If there aren’t any defaultRates
, bids are queued
until the currency file has loaded.
If the Prebid timeout occurs while bids are still on the queue, they will be skipped rather than passed to the ad server.
A bid is also skipped if the file (or defaultRates
) doesn’t contain a conversion from the bid currency
to the ad server currency.
Can I use the Google Ad Manager Secondary Currency Feature instead?
Of course, use of Prebid currency feature is optional.
Why isn’t my currency supported in Prebid’s file?
The data in Prebid’s hosted currency file comes from a free source. This source is reliable, but it doesn’t contain currencies for all countries of the world.
If there’s a currency conversion you need that’s not included, there are several options: