currency module

modules/currency.js

@@ -0,0 +1,255 @@
+import bidfactory from 'src/bidfactory';
+import { STATUS } from 'src/constants';
+import { ajax } from 'src/ajax';
+import * as utils from 'src/utils';
+import bidmanager from 'src/bidmanager';
+import { config } from 'src/config';
+
+const DEFAULT_CURRENCY_RATE_URL = 'http://currency.prebid.org/latest.json';
+const CURRENCY_RATE_PRECISION = 4;
+
+var bidResponseQueue = [];
+var conversionCache = {};
+var currencyRatesLoaded = false;
+var adServerCurrency = 'USD';
+
+// Used as reference to the original bidmanager.addBidResponse
+var originalBidResponse;
+
+export var currencySupportEnabled = false;
+export var currencyRates = {};
+var bidderCurrencyDefault = {};
+
+/**
+ * Configuration function for currency
+ * @param  {string} [config.adServerCurrency = 'USD']
+ *  ISO 4217 3-letter currency code that represents the target currency. (e.g. 'EUR').  If this value is present,
+ *  the currency conversion feature is activated.
+ * @param  {number} [config.granularityMultiplier = 1]
+ *  A decimal value representing how mcuh to scale the price granularity calculations.
+ * @param  {object} config.bidderCurrencyDefault
+ *  An optional argument to specify bid currencies for bid adapters.  This option is provided for the transitional phase
+ *  before every bid adapter will specify its own bid currency.  If the adapter specifies a bid currency, this value is
+ *  ignored for that bidder.
+ *
+ *  example:
+ *  {
+ *    rubicon: 'USD'
+ *  }
+ * @param  {string} [config.conversionRateFile = 'http://currency.prebid.org/latest.json']
+ *  Optional path to a file containing currency conversion data.  Prebid.org hosts a file that is used as the default,
+ *  if not specified.
+ * @param  {object} [config.rates]
+ *  This optional argument allows you to specify the rates with a JSON object, subverting the need for a external
+ *  config.conversionRateFile parameter.  If this argument is specified, the conversion rate file will not be loaded.
+ *
+ *  example:
+ *  {
+ *    'GBP': { 'CNY': 8.8282, 'JPY': 141.7, 'USD': 1.2824 },
+ *    'USD': { 'CNY': 6.8842, 'GBP': 0.7798, 'JPY': 110.49 }
+ *  }
+ */
+export function setConfig(config) {
+  let url = DEFAULT_CURRENCY_RATE_URL;
+
+  if (typeof config.rates === 'object') {
+    currencyRates.conversions = config.rates;
+    currencyRatesLoaded = true;
+  }
+
+  if (typeof config.adServerCurrency === 'string') {
+    utils.logInfo('enabling currency support', arguments);
+
+    adServerCurrency = config.adServerCurrency;
+    if (config.conversionRateFile) {
+      utils.logInfo('currency using override conversionRateFile:', config.conversionRateFile);
+      url = config.conversionRateFile;
+    }
+    initCurrency(url);
+  } else {
+    // currency support is disabled, setting defaults
+    utils.logInfo('disabling currency support');
+    resetCurrency();
+  }
+  if (typeof config.bidderCurrencyDefault === 'object') {
+    bidderCurrencyDefault = config.bidderCurrencyDefault;
+  }
+}
+config.getConfig('currency', config => setConfig(config.currency));
+
+function initCurrency(url) {
+  conversionCache = {};
+  currencySupportEnabled = true;
+
+  if (!originalBidResponse) {
+    utils.logInfo('Installing addBidResponse decorator for currency module', arguments);
+
+    originalBidResponse = bidmanager.addBidResponse;
+    bidmanager.addBidResponse = addBidResponseDecorator(bidmanager.addBidResponse);
+  }
+
+  if (!currencyRates.conversions) {
+    ajax(url, function (response) {
+      try {
+        currencyRates = JSON.parse(response);
+        utils.logInfo('currencyRates set to ' + JSON.stringify(currencyRates));
+        currencyRatesLoaded = true;
+        processBidResponseQueue();
+      } catch (e) {
+        utils.logError('failed to parse currencyRates response: ' + response);
+      }
+    });
+  }
+}
+
+function resetCurrency() {
+  if (originalBidResponse) {
+    utils.logInfo('Uninstalling addBidResponse decorator for currency module', arguments);
+
+    bidmanager.addBidResponse = originalBidResponse;
+    originalBidResponse = undefined;
+  }
+
+  adServerCurrency = 'USD';
+  conversionCache = {};
+  currencySupportEnabled = false;
+  currencyRatesLoaded = false;
+  currencyRates = {};
+  bidderCurrencyDefault = {};
+}
+
+export function addBidResponseDecorator(fn) {
+  return function(adUnitCode, bid) {
+    if (!bid) {
+      return fn.apply(this, arguments); // if no bid, call original and let it display warnings
+    }
+
+    let bidder = bid.bidderCode || bid.bidder;
+    if (bidderCurrencyDefault[bidder]) {
+      let currencyDefault = bidderCurrencyDefault[bidder];
+      if (bid.currency && currencyDefault !== bid.currency) {
+        utils.logWarn(`Currency default '${bidder}: ${currencyDefault}' ignored. adapter specified '${bid.currency}'`);
+      } else {
+        bid.currency = currencyDefault;
+      }
+    }
+
+    // default to USD if currency not set
+    if (!bid.currency) {
+      utils.logWarn('Currency not specified on bid.  Defaulted to "USD"');
+      bid.currency = 'USD';
+    }
+
+    // execute immediately if the bid is already in the desired currency
+    if (bid.currency === adServerCurrency) {
+      return fn.apply(this, arguments);
+    }
+
+    bidResponseQueue.push(wrapFunction(fn, this, arguments));
+    if (!currencySupportEnabled || currencyRatesLoaded) {
+      processBidResponseQueue();
+    }
+  }
+}
+
+function processBidResponseQueue() {
+  while (bidResponseQueue.length > 0) {
+    (bidResponseQueue.shift())();
+  }
+}
+
+function wrapFunction(fn, context, params) {
+  return function() {
+    var bid = params[1];
+    if (bid !== undefined && 'currency' in bid && 'cpm' in bid) {
+      var fromCurrency = bid.currency;
+      try {
+        var conversion = getCurrencyConversion(fromCurrency);
+        bid.originalCpm = bid.cpm;
+        bid.originalCurrency = bid.currency;
+        if (conversion !== 1) {
+          bid.cpm = (parseFloat(bid.cpm) * conversion).toFixed(4);
+          bid.currency = adServerCurrency;
+        }
+      } catch (e) {
+        utils.logWarn('Returning NO_BID, getCurrencyConversion threw error: ', e);
+        params[1] = bidfactory.createBid(STATUS.NO_BID, {
+          bidder: bid.bidderCode || bid.bidder,
+          bidId: bid.adId
+        });
+      }
+    }
+    return fn.apply(context, params);
+  };
+}
+
+function getCurrencyConversion(fromCurrency) {
+  var conversionRate = null;
+  var rates;
+
+  if (fromCurrency in conversionCache) {
+    conversionRate = conversionCache[fromCurrency];
+    utils.logMessage('Using conversionCache value ' + conversionRate + ' for fromCurrency ' + fromCurrency);
+  } else if (currencySupportEnabled === false) {
+    if (fromCurrency === 'USD') {
+      conversionRate = 1;
+    } else {
+      throw new Error('Prebid currency support has not been enabled and fromCurrency is not USD');
+    }
+  } else if (fromCurrency === adServerCurrency) {
+    conversionRate = 1;
+  } else {
+    var toCurrency = adServerCurrency;
+
+    if (fromCurrency in currencyRates.conversions) {
+      // using direct conversion rate from fromCurrency to toCurrency
+      rates = currencyRates.conversions[fromCurrency];
+      if (!(toCurrency in rates)) {
+        // bid should fail, currency is not supported
+        throw new Error('Specified adServerCurrency in config \'' + toCurrency + '\' not found in the currency rates file');
+      }
+      conversionRate = rates[toCurrency];
+      utils.logInfo('getCurrencyConversion using direct ' + fromCurrency + ' to ' + toCurrency + ' conversionRate ' + conversionRate);
+    } else if (toCurrency in currencyRates.conversions) {
+      // using reciprocal of conversion rate from toCurrency to fromCurrency
+      rates = currencyRates.conversions[toCurrency];
+      if (!(fromCurrency in rates)) {
+        // bid should fail, currency is not supported
+        throw new Error('Specified fromCurrency \'' + fromCurrency + '\' not found in the currency rates file');
+      }
+      conversionRate = roundFloat(1 / rates[fromCurrency], CURRENCY_RATE_PRECISION);
+      utils.logInfo('getCurrencyConversion using reciprocal ' + fromCurrency + ' to ' + toCurrency + ' conversionRate ' + conversionRate);
+    } else {
+      // first defined currency base used as intermediary
+      var anyBaseCurrency = Object.keys(currencyRates.conversions)[0];
+
+      if (!(fromCurrency in currencyRates.conversions[anyBaseCurrency])) {
+        // bid should fail, currency is not supported
+        throw new Error('Specified fromCurrency \'' + fromCurrency + '\' not found in the currency rates file');
+      }
+      var toIntermediateConversionRate = 1 / currencyRates.conversions[anyBaseCurrency][fromCurrency];
+
+      if (!(toCurrency in currencyRates.conversions[anyBaseCurrency])) {
+        // bid should fail, currency is not supported
+        throw new Error('Specified adServerCurrency in config \'' + toCurrency + '\' not found in the currency rates file');
+      }
+      var fromIntermediateConversionRate = currencyRates.conversions[anyBaseCurrency][toCurrency];
+
+      conversionRate = roundFloat(toIntermediateConversionRate * fromIntermediateConversionRate, CURRENCY_RATE_PRECISION);
+      utils.logInfo('getCurrencyConversion using intermediate ' + fromCurrency + ' thru ' + anyBaseCurrency + ' to ' + toCurrency + ' conversionRate ' + conversionRate);
+    }
+  }
+  if (!(fromCurrency in conversionCache)) {
+    utils.logMessage('Adding conversionCache value ' + conversionRate + ' for fromCurrency ' + fromCurrency);
+    conversionCache[fromCurrency] = conversionRate;
+  }
+  return conversionRate;
+}
+
+function roundFloat(num, dec) {
+  var d = 1;
+  for (let i = 0; i < dec; i++) {
+    d += '0';
+  }
+  return Math.round(num * d) / d;
+}

src/bidmanager.js

@@ -178,7 +178,11 @@ exports.addBidResponse = function (adUnitCode, bid) {
       bid.renderer.setRender(adUnitRenderer.render);
     }
 
-    const priceStringsObj = getPriceBucketString(bid.cpm, config.getConfig('customPriceBucket'));
+    const priceStringsObj = getPriceBucketString(
+      bid.cpm,
+      config.getConfig('customPriceBucket'),
+      config.getConfig('currency.granularityMultiplier')
+    );
     bid.pbLg = priceStringsObj.low;
     bid.pbMg = priceStringsObj.med;
     bid.pbHg = priceStringsObj.high;

src/config.js

@@ -7,7 +7,7 @@
  * Defining and access properties in this way is now deprecated, but these will
  * continue to work during a deprecation window.
  */
-import { isValidePriceConfig } from './cpmBucketManager';
+import { isValidPriceConfig } from './cpmBucketManager';
 const utils = require('./utils');
 
 const DEFAULT_DEBUG = false;
@@ -134,7 +134,7 @@ export function newConfig() {
         utils.logWarn('Prebid Warning: setPriceGranularity was called with invalid setting, using `medium` as default.');
       }
     } else if (typeof val === 'object') {
-      if (!isValidePriceConfig(val)) {
+      if (!isValidPriceConfig(val)) {
         utils.logError('Invalid custom price value passed to `setPriceGranularity()`');
         return false;
       }
@@ -144,16 +144,16 @@ export function newConfig() {
 
   /*
    * Returns configuration object if called without parameters,
-   * or single configuration property if given a string matching a configuartion
-   * property name.
+   * or single configuration property if given a string matching a configuration
+   * property name.  Allows deep access e.g. getConfig('currency.adServerCurrency')
    *
    * If called with callback parameter, or a string and a callback parameter,
    * subscribes to configuration updates. See `subscribe` function for usage.
    */
   function getConfig(...args) {
     if (args.length <= 1 && typeof args[0] !== 'function') {
       const option = args[0];
-      return option ? config[option] : config;
+      return option ? utils.deepAccess(config, option) : config;
     }
 
     return subscribe(...args);

src/cpmBucketManager.js

@@ -57,26 +57,25 @@ const _autoPriceConfig = {
   }]
 };
 
-function getPriceBucketString(cpm, customConfig) {
-  let cpmFloat = 0;
-  cpmFloat = parseFloat(cpm);
+function getPriceBucketString(cpm, customConfig, granularityMultiplier = 1) {
+  let cpmFloat = parseFloat(cpm);
   if (isNaN(cpmFloat)) {
     cpmFloat = '';
   }
 
   return {
-    low: (cpmFloat === '') ? '' : getCpmStringValue(cpm, _lgPriceConfig),
-    med: (cpmFloat === '') ? '' : getCpmStringValue(cpm, _mgPriceConfig),
-    high: (cpmFloat === '') ? '' : getCpmStringValue(cpm, _hgPriceConfig),
-    auto: (cpmFloat === '') ? '' : getCpmStringValue(cpm, _autoPriceConfig),
-    dense: (cpmFloat === '') ? '' : getCpmStringValue(cpm, _densePriceConfig),
-    custom: (cpmFloat === '') ? '' : getCpmStringValue(cpm, customConfig)
+    low: (cpmFloat === '') ? '' : getCpmStringValue(cpm, _lgPriceConfig, granularityMultiplier),
+    med: (cpmFloat === '') ? '' : getCpmStringValue(cpm, _mgPriceConfig, granularityMultiplier),
+    high: (cpmFloat === '') ? '' : getCpmStringValue(cpm, _hgPriceConfig, granularityMultiplier),
+    auto: (cpmFloat === '') ? '' : getCpmStringValue(cpm, _autoPriceConfig, granularityMultiplier),
+    dense: (cpmFloat === '') ? '' : getCpmStringValue(cpm, _densePriceConfig, granularityMultiplier),
+    custom: (cpmFloat === '') ? '' : getCpmStringValue(cpm, customConfig, granularityMultiplier)
   };
 }
 
-function getCpmStringValue(cpm, config) {
+function getCpmStringValue(cpm, config, granularityMultiplier) {
   let cpmStr = '';
-  if (!isValidePriceConfig(config)) {
+  if (!isValidPriceConfig(config)) {
     return cpmStr;
   }
   const cap = config.buckets.reduce((prev, curr) => {
@@ -88,20 +87,20 @@ function getCpmStringValue(cpm, config) {
     'max': 0,
   });
   let bucket = config.buckets.find(bucket => {
-    if (cpm > cap.max) {
+    if (cpm > cap.max * granularityMultiplier) {
       const precision = bucket.precision || _defaultPrecision;
-      cpmStr = bucket.max.toFixed(precision);
-    } else if (cpm <= bucket.max && cpm >= bucket.min) {
+      cpmStr = (bucket.max * granularityMultiplier).toFixed(precision);
+    } else if (cpm <= bucket.max * granularityMultiplier && cpm >= bucket.min * granularityMultiplier) {
       return bucket;
     }
   });
   if (bucket) {
-    cpmStr = getCpmTarget(cpm, bucket.increment, bucket.precision);
+    cpmStr = getCpmTarget(cpm, bucket.increment, bucket.precision, granularityMultiplier);
   }
   return cpmStr;
 }
 
-function isValidePriceConfig(config) {
+function isValidPriceConfig(config) {
   if (utils.isEmpty(config) || !config.buckets || !Array.isArray(config.buckets)) {
     return false;
   }
@@ -114,12 +113,12 @@ function isValidePriceConfig(config) {
   return isValid;
 }
 
-function getCpmTarget(cpm, increment, precision) {
+function getCpmTarget(cpm, increment, precision, granularityMultiplier) {
   if (!precision) {
     precision = _defaultPrecision;
   }
-  let bucketSize = 1 / increment;
+  let bucketSize = 1 / increment * granularityMultiplier;
   return (Math.floor(cpm * bucketSize) / bucketSize).toFixed(precision);
 }
 
-export { getPriceBucketString, isValidePriceConfig };
+export { getPriceBucketString, isValidPriceConfig };