Currency Module

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:

1. A Prebid.js package is built that contains the extra currency module code
2. Config in the page defines the currency used by the Publisher’s ad server and other configuration parameters.
3. The existence of this configuration causes the Prebid platform to load a currency conversion file while the bids are taking place. Alternately, the conversion rates can be provided in the page.
4. At runtime, bids are converted to the ad server currency as needed.
5. Default rates can be provided in case the file cannot be loaded.
6. When requestBids is called, the Currency Module will delay the auction up to the supplied amount of time in currency.auctionDelay or as soon as the dynamic endpoint returns data, whichever is first.

Currency Architecture

The numbered circles in this diagram are explained below.

1. Line Item Creation

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:

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.

pbjs.setConfig({
    "priceGranularity": "low",
    "currency": {
       "adServerCurrency": "JPY",
       "granularityMultiplier": 108,
       "defaultRates": { "USD": { "JPY": 110 }}
    }
});

This results in a granularity rule that’s scaled up to make sense in Yen:

Notes:

• The multiplier may not make sense for markets where the currency value is close to USD, e.g. GBP and EUR. In those scenarios, just leave the granularityMultiplier at 1.
• There’s not yet an open source tool that creates line items in this way.
• The multiplier chosen (108 in this example) is a snapshot in time. The line item boundaries are static – the number of bids in each bucket may shift as currency exchange rates fluctuate. This is normal – changes to buckets can be done by updating the line items, though this shouldn’t happen often.

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.

2. Prebid Configuration

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:

1. adServerCurrency - defining this turns on the currency feature:
   1. loads the currency conversion file
   2. converts bids as needed
   3. scales the price granularity buckets
2. granularityMultiplier - this scales Prebid’s default granularity buckets by the same factor used to create the ad server line items. It defaults to 1.

There are other options explained below, but these are the key ones needed to understand how the currency feature works.

3. Bid Conversion

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.

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.

4. Mapping Bids to Price Bucket

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.

5. Ad Request and Decision

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.

Full Example

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:

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.

Page integration

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:

pbjs.setConfig({
    "currency": {
       "adServerCurrency": "JPY",
       "granularityMultiplier": 108,
       "defaultRates": { "USD": { "JPY": 110 }}
    }
});

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:

pbjs.setConfig({
"currency": {
      // enables currency feature
      "adServerCurrency": "GBP",
      "granularityMultiplier": 1, // 0.50 increment up to 5 is fine for GBP
      // optionally override the default rate file
      "conversionRateFile": "URL_TO_RATE_FILE",
      // optionally provide a default rate in case the file can't be read
      "defaultRates": { "USD": { "GPB": 0.75 }}
      // optionally sets the auction defer time if the file has not been loaded yet
      "auctionDelay": 1000
   }
});

And finally, here’s an example where the conversion rate is specified right in the config, so the external file won’t be loaded:

pbjs.setConfig({
    "currency": {
       "adServerCurrency": "JPY",
       "granularityMultiplier": 108,
       "rates": { "USD": { "JPY": 110.21 }}
    }
});

Building the Prebid package with Currency Support

Step 1: Bundle the module code

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:

gulp build --modules=currency,exampleBidAdapter

This command will build the following files:

• build/dist/prebid-core.js - the base Prebid code
• build/dist/currency.js - additional code for the currency feature
• build/dist/exampleBidAdapter.js - a specified bidder adapter
• build/dist/prebid.js - a combined file with the base Prebid core code, bidder adapter code, and the currency module code.

Step 2: Publish the package(s) to the CDN

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.

Functions

No additional functions are provided with this module. Rather, the setConfig() call takes a currency object that may contain several parameters:

Currency Rate Conversion File

Prebid.org’s currency file

Prebid.org hosts a conversion file at 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.

Format

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
      }
  }
}

FAQ

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:

1. Use the ‘defaultRates` feature
2. Build and host a currency conversion file that includes the desired currencies
3. Find a reliable, free, no-strings source of conversation data that we can integrate into our hosted file, then post an issue on the github forum.