diff --git a/modules/timeoutRtdProvider.js b/modules/timeoutRtdProvider.js new file mode 100644 index 00000000000..020a7d6f7f0 --- /dev/null +++ b/modules/timeoutRtdProvider.js @@ -0,0 +1,173 @@ + +import { submodule } from '../src/hook.js'; +import * as ajax from '../src/ajax.js'; +import * as utils from '../src/utils.js'; +import { getGlobal } from '../src/prebidGlobal.js'; + +const SUBMODULE_NAME = 'timeout'; + +// this allows the stubbing of functions during testing +export const timeoutRtdFunctions = { + getDeviceType, + getConnectionSpeed, + checkVideo, + calculateTimeoutModifier, + handleTimeoutIncrement +}; + +function getDeviceType() { + const userAgent = window.navigator.userAgent.toLowerCase(); + if ((/ipad|android 3.0|xoom|sch-i800|playbook|tablet|kindle/i.test(userAgent))) { + return 5; // tablet + } + if ((/iphone|ipod|android|blackberry|opera|mini|windows\sce|palm|smartphone|iemobile/i.test(userAgent))) { + return 4; // mobile + } + return 2; // personal computer +} + +function checkVideo(adUnits) { + return adUnits.some((adUnit) => { + return adUnit.mediaTypes && adUnit.mediaTypes.video; + }); +} + +function getConnectionSpeed() { + const connection = window.navigator.connection || window.navigator.mozConnection || window.navigator.webkitConnection || {} + const connectionType = connection.type || connection.effectiveType; + + switch (connectionType) { + case 'slow-2g': + case '2g': + return 'slow'; + + case '3g': + return 'medium'; + + case 'bluetooth': + case 'cellular': + case 'ethernet': + case 'wifi': + case 'wimax': + case '4g': + return 'fast'; + } + + return 'unknown'; +} +/** + * Calculate the time to be added to the timeout + * @param {Array} adUnits + * @param {Object} rules + * @return {int} + */ +function calculateTimeoutModifier(adUnits, rules) { + utils.logInfo('Timeout rules', rules); + let timeoutModifier = 0; + let toAdd = 0; + + if (rules.includesVideo) { + const hasVideo = timeoutRtdFunctions.checkVideo(adUnits); + toAdd = rules.includesVideo[hasVideo] || 0; + utils.logInfo(`Adding ${toAdd} to timeout for includesVideo ${hasVideo}`) + timeoutModifier += toAdd; + } + + if (rules.numAdUnits) { + const numAdUnits = adUnits.length; + if (rules.numAdUnits[numAdUnits]) { + timeoutModifier += rules.numAdUnits[numAdUnits]; + } else { + for (const [rangeStr, timeoutVal] of Object.entries(rules.numAdUnits)) { + const [lowerBound, upperBound] = rangeStr.split('-'); + if (parseInt(lowerBound) <= numAdUnits && numAdUnits <= parseInt(upperBound)) { + utils.logInfo(`Adding ${timeoutVal} to timeout for numAdUnits ${numAdUnits}`) + timeoutModifier += timeoutVal; + break; + } + } + } + } + + if (rules.deviceType) { + const deviceType = timeoutRtdFunctions.getDeviceType(); + toAdd = rules.deviceType[deviceType] || 0; + utils.logInfo(`Adding ${toAdd} to timeout for deviceType ${deviceType}`) + timeoutModifier += toAdd; + } + + if (rules.connectionSpeed) { + const connectionSpeed = timeoutRtdFunctions.getConnectionSpeed(); + toAdd = rules.connectionSpeed[connectionSpeed] || 0; + utils.logInfo(`Adding ${toAdd} to timeout for connectionSpeed ${connectionSpeed}`) + timeoutModifier += toAdd; + } + + utils.logInfo('timeout Modifier calculated', timeoutModifier); + return timeoutModifier; +} + +/** + * + * @param {Object} reqBidsConfigObj + * @param {function} callback + * @param {Object} config + * @param {Object} userConsent + */ +function getBidRequestData(reqBidsConfigObj, callback, config, userConsent) { + utils.logInfo('Timeout rtd config', config); + const timeoutUrl = utils.deepAccess(config, 'params.endpoint.url'); + if (timeoutUrl) { + utils.logInfo('Timeout url', timeoutUrl); + ajax.ajaxBuilder()(timeoutUrl, { + success: function(response) { + try { + const rules = JSON.parse(response); + timeoutRtdFunctions.handleTimeoutIncrement(reqBidsConfigObj, rules); + } catch (e) { + utils.logError('Error parsing json response from timeout provider.') + } + callback(); + }, + error: function(errorStatus) { + utils.logError('Timeout request error!', errorStatus); + callback(); + } + }); + } else if (utils.deepAccess(config, 'params.rules')) { + timeoutRtdFunctions.handleTimeoutIncrement(reqBidsConfigObj, utils.deepAccess(config, 'params.rules')); + callback(); + } else { + utils.logInfo('No timeout endpoint or timeout rules found. Exiting timeout rtd module'); + callback(); + } +} + +/** + * Gets the timeout modifier, adds it to the bidder timeout, and sets it to reqBidsConfigObj + * @param {Object} reqBidsConfigObj + * @param {Object} rules + */ +function handleTimeoutIncrement(reqBidsConfigObj, rules) { + const adUnits = reqBidsConfigObj.adUnits || getGlobal().adUnits; + const timeoutModifier = timeoutRtdFunctions.calculateTimeoutModifier(adUnits, rules); + const bidderTimeout = getGlobal().getConfig('bidderTimeout'); + reqBidsConfigObj.timeout = bidderTimeout + timeoutModifier; +} + +/** @type {RtdSubmodule} */ +export const timeoutSubmodule = { + /** + * used to link submodule with realTimeData + * @type {string} + */ + name: SUBMODULE_NAME, + init: () => true, + getBidRequestData, +}; + +function registerSubModule() { + submodule('realTimeData', timeoutSubmodule); +} + +registerSubModule(); diff --git a/modules/timeoutRtdProvider.md b/modules/timeoutRtdProvider.md new file mode 100644 index 00000000000..49d1e1fc70a --- /dev/null +++ b/modules/timeoutRtdProvider.md @@ -0,0 +1,151 @@ + --- + layout: page_v2 + title: Timeout Rtd Module + description: Module for managing timeouts in real time + page_type: module + module_type: rtd + module_code : example + enable_download : true + sidebarType : 1 + --- + +## Overview +The timeout RTD module enables publishers to set rules that determine the timeout based on +certain features. It supports rule sets dynamically retrieved from a timeout provider as well as rules +set directly via configuration. +Build the timeout RTD module into the Prebid.js package with: +``` +gulp build --modules=timeoutRtdProvider,rtdModule... +``` + +## Configuration +The module is configured in the realTimeData.dataProviders object. The module will override +`bidderTimeout` in the pbjs config. + +### Timeout Data Provider interface +The timeout RTD module provides an interface of dynamically fetching timeout rules from +a data provider just before the auction begins. The endpoint url is set in the config just as in +the example below, and the timeout data will be used when making bid requests. + +``` +pbjs.setConfig({ + ... + "realTimeData": { + "dataProviders": [{ + "name": 'timeout', + "params": { + "endpoint": { + "url": "http://{cdn-link}.json" + } + } + } + ]}, + + // This value below will be modified by the timeout RTD module if it successfully + // fetches the timeout data. + "bidderTimeout": 1500, + ... +}); +``` + +Sample Endpoint Response: +``` +{ + "rules": { + "includesVideo": { + "true": 200, + "false": 50 + }, + "numAdUnits" : { + "1-5": 100, + "6-10": 200, + "11-15": 300 + }, + "deviceType": { + "2": 50, + "4": 100, + "5": 200 + }, + "connectionSpeed": { + "slow": 200, + "medium": 100, + "fast": 50, + "unknown": 10 + }, +} +``` + +### Rule Handling: +The rules retrieved from the endpoint will be used to add time to the `bidderTimeout` based on certain features such as +the user's deviceType, connection speed, etc. These rules can also be configured statically on page via a `rules` object. +Note that the timeout Module will ignore the static rules if an endpoint url is provided. The timeout rules follow the +format: +``` +{ + '': { + '': + } +} +``` +See bottom of page for examples. + +Currently supported features: + +|Name |Description | Keys | Example +| :------------ | :------------ | :------------ |:------------ | +| includesVideo | Adds time to the timeout based on whether there is a video ad unit in the auction or not | 'true'/'false'| { "true": 200, "false": 50 } | +| numAdUnits | Adds time based on the number of ad units. Ranges in the format `'lowerbound-upperbound` are accepted. This range is inclusive | numbers or number ranges | {"1": 50, "2-5": 100, "6-10": 200} | +| deviceType | Adds time based on device type| 2, 4, or 5| {"2": 50, "4": 100} | +| connectionSpeed | Adds time based on connection speed. `connectionSpeed` defaults to 'unknown' if connection speed cannot be determined | slow, medium, fast, or unknown | { "slow": 200} | + +If there are multiple rules set, all of them would be used and any that apply will be added to the base timeout. For example, if the rules object contains: +``` +{ + "includesVideo": { + "true": 200, + "false": 50 + }, + "numAdUnits" : { + "1-3": 100, + "4-5": 200 + } +} +``` +and there are 3 ad units in the auction, all of which are banner, then the timeout to be added will be 150 milliseconds (50 for `includesVideo[false]` + 100 for `numAdUnits['1-3']`). + +Full example: +``` +pbjs.setConfig({ + ... + "realTimeData": { + "dataProviders": [{ + "name": 'timeout', + "params": { + "rules": { + "includesVideo": { + "true": 200, + "false": 50 + }, + "numAdUnits" : { + "1-5": 100, + "6-10": 200, + "11-15": 300 + }, + "deviceType": { + "2": 50, + "4": 100, + "5": 200 + }, + "connectionSpeed": { + "slow": 200, + "medium": 100, + "fast": 50, + "unknown": 10 + }, + } + } + ]} + ... + // The timeout RTD module will add time to `bidderTimeout` based on the rules set above. + "bidderTimeout": 1500, +``` diff --git a/test/spec/modules/timeoutRtdProvider_spec.js b/test/spec/modules/timeoutRtdProvider_spec.js new file mode 100644 index 00000000000..88415a99b5e --- /dev/null +++ b/test/spec/modules/timeoutRtdProvider_spec.js @@ -0,0 +1,339 @@ + +import { timeoutRtdFunctions, timeoutSubmodule } from '../../../modules/timeoutRtdProvider' +import { expect } from 'chai'; +import * as ajax from 'src/ajax.js'; +import * as prebidGlobal from 'src/prebidGlobal.js'; + +const DEFAULT_USER_AGENT = window.navigator.userAgent; +const DEFAULT_CONNECTION = window.navigator.connection; + +const PC_USER_AGENT = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.135 Safari/537.36 Edge/12.246'; +const MOBILE_USER_AGENT = 'Mozilla/5.0 (iPhone; CPU iPhone OS 10_3_1 like Mac OS X) AppleWebKit/603.1.30 (KHTML, like Gecko) Version/10.0 Mobile/14E304 Safari/602.1'; +const TABLET_USER_AGENT = 'Mozilla/5.0 (iPad; CPU OS 12_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148'; + +function resetUserAgent() { + window.navigator.__defineGetter__('userAgent', () => DEFAULT_USER_AGENT); +}; + +function setUserAgent(userAgent) { + window.navigator.__defineGetter__('userAgent', () => userAgent); +} + +function resetConnection() { + window.navigator.__defineGetter__('connection', () => DEFAULT_CONNECTION); +} +function setConnectionType(connectionType) { + window.navigator.__defineGetter__('connection', () => { return {'type': connectionType} }); +} + +describe('getDeviceType', () => { + afterEach(() => { + resetUserAgent(); + }); + + [ + // deviceType, userAgent, deviceTypeNum + ['pc', PC_USER_AGENT, 2], + ['mobile', MOBILE_USER_AGENT, 4], + ['tablet', TABLET_USER_AGENT, 5], + ].forEach(function(args) { + const [deviceType, userAgent, deviceTypeNum] = args; + it(`should be able to recognize ${deviceType} devices`, () => { + setUserAgent(userAgent); + const res = timeoutRtdFunctions.getDeviceType(); + expect(res).to.equal(deviceTypeNum) + }) + }) +}); + +describe('getConnectionSpeed', () => { + afterEach(() => { + resetConnection(); + }); + [ + // connectionType, connectionSpeed + ['slow-2g', 'slow'], + ['2g', 'slow'], + ['3g', 'medium'], + ['bluetooth', 'fast'], + ['cellular', 'fast'], + ['ethernet', 'fast'], + ['wifi', 'fast'], + ['wimax', 'fast'], + ['4g', 'fast'], + ['not known', 'unknown'], + [undefined, 'unknown'], + ].forEach(function(args) { + const [connectionType, connectionSpeed] = args; + it(`should be able to categorize connection speed when the connection type is ${connectionType}`, () => { + setConnectionType(connectionType); + const res = timeoutRtdFunctions.getConnectionSpeed(); + expect(res).to.equal(connectionSpeed) + }) + }) +}); + +describe('Timeout modifier calculations', () => { + let sandbox; + beforeEach(() => { + sandbox = sinon.sandbox.create(); + }); + + afterEach(() => { + sandbox.restore(); + }); + + it('should be able to detect video ad units', () => { + let adUnits = [] + let res = timeoutRtdFunctions.checkVideo(adUnits); + expect(res).to.be.false; + + adUnits = [{ + mediaTypes: { + video: [] + } + }]; + res = timeoutRtdFunctions.checkVideo(adUnits); + expect(res).to.be.true; + + adUnits = [{ + mediaTypes: { + banner: [] + } + }]; + res = timeoutRtdFunctions.checkVideo(adUnits); + expect(res).to.be.false; + }); + + it('should calculate the timeout modifier for video', () => { + sandbox.stub(timeoutRtdFunctions, 'checkVideo').returns(true); + const rules = { + includesVideo: { + 'true': 200, + 'false': 50 + } + } + const res = timeoutRtdFunctions.calculateTimeoutModifier([], rules); + expect(res).to.equal(200) + }); + + it('should calculate the timeout modifier for connectionSpeed', () => { + sandbox.stub(timeoutRtdFunctions, 'getConnectionSpeed').returns('slow'); + const rules = { + connectionSpeed: { + 'slow': 200, + 'medium': 100, + 'fast': 50 + } + } + const res = timeoutRtdFunctions.calculateTimeoutModifier([], rules); + expect(res).to.equal(200); + }); + + it('should calculate the timeout modifier for deviceType', () => { + sandbox.stub(timeoutRtdFunctions, 'getDeviceType').returns(4); + const rules = { + deviceType: { + '2': 50, + '4': 100, + '5': 200 + }, + } + const res = timeoutRtdFunctions.calculateTimeoutModifier([], rules); + expect(res).to.equal(100) + }); + + it('should calculate the timeout modifier for ranged numAdunits', () => { + const rules = { + numAdUnits: { + '1-5': 100, + '6-10': 200, + '11-15': 300, + } + } + const adUnits = [1, 2, 3, 4, 5, 6]; + const res = timeoutRtdFunctions.calculateTimeoutModifier(adUnits, rules); + expect(res).to.equal(200) + }); + + it('should calculate the timeout modifier for exact numAdunits', () => { + const rules = { + numAdUnits: { + '1': 100, + '2': 200, + '3': 300, + '4-5': 400, + } + } + const adUnits = [1, 2]; + const res = timeoutRtdFunctions.calculateTimeoutModifier(adUnits, rules); + expect(res).to.equal(200); + }); + + it('should add up all the modifiers when all the rules are present', () => { + sandbox.stub(timeoutRtdFunctions, 'getConnectionSpeed').returns('slow'); + sandbox.stub(timeoutRtdFunctions, 'getDeviceType').returns(4); + const rules = { + connectionSpeed: { + 'slow': 200, + 'medium': 100, + 'fast': 50 + }, + deviceType: { + '2': 50, + '4': 100, + '5': 200 + }, + includesVideo: { + 'true': 200, + 'false': 50 + }, + numAdUnits: { + '1': 100, + '2': 200, + '3': 300, + '4-5': 400, + } + } + const res = timeoutRtdFunctions.calculateTimeoutModifier([{ + mediaTypes: { + video: [] + } + }], rules); + expect(res).to.equal(600); + }); +}); + +describe('Timeout RTD submodule', () => { + let sandbox; + beforeEach(() => { + sandbox = sinon.sandbox.create(); + }); + + afterEach(() => { + sandbox.restore(); + }); + + it('should init successfully', () => { + expect(timeoutSubmodule.init()).to.equal(true); + }); + + it('should make a request to the endpoint url if it is provided, and handle the response', () => { + const response = '{"deviceType":{ "2": 50, "4": 100, "5": 200 }}' + const ajaxStub = sandbox.stub().callsFake(function (url, callbackObj) { + callbackObj.success(response); + }); + sandbox.stub(ajax, 'ajaxBuilder').callsFake(function () { return ajaxStub }); + + const reqBidsConfigObj = {} + const expectedLink = 'https://somelink.json' + const config = { + 'name': 'timeout', + 'params': { + 'endpoint': { + url: expectedLink + } + } + } + const handleTimeoutIncrementStub = sandbox.stub(timeoutRtdFunctions, 'handleTimeoutIncrement'); + timeoutSubmodule.getBidRequestData(reqBidsConfigObj, function() {}, config) + + expect(ajaxStub.calledWith(expectedLink)).to.be.true; + expect(handleTimeoutIncrementStub.calledWith(reqBidsConfigObj, JSON.parse(response))).to.be.true; + }); + + it('should make a request to the endpoint url and ignore the rules object if the endpoint is provided', () => { + const ajaxStub = sandbox.stub().callsFake((url, callbackObj) => {}); + sandbox.stub(ajax, 'ajaxBuilder').callsFake(() => ajaxStub); + const expectedLink = 'https://somelink.json' + const config = { + 'name': 'timeout', + 'params': { + 'endpoint': { + url: expectedLink + }, + 'rules': { + 'includesVideo': { + 'true': 200, + }, + } + } + } + timeoutSubmodule.getBidRequestData({}, function() {}, config); + expect(ajaxStub.calledWith(expectedLink)).to.be.true; + }); + + it('should use the rules object if there is no endpoint url', () => { + const config = { + 'name': 'timeout', + 'params': { + 'rules': { + 'includesVideo': { + 'true': 200, + }, + } + } + } + const handleTimeoutIncrementStub = sandbox.stub(timeoutRtdFunctions, 'handleTimeoutIncrement'); + const reqBidsConfigObj = {}; + timeoutSubmodule.getBidRequestData(reqBidsConfigObj, function() {}, config); + expect(handleTimeoutIncrementStub.calledWith(reqBidsConfigObj, config.params.rules)).to.be.true; + }); + + it('should exit quietly if no relevant timeout config is found', () => { + const callback = sandbox.stub() + const ajaxStub = sandbox.stub().callsFake((url, callbackObj) => {}); + sandbox.stub(ajax, 'ajaxBuilder').callsFake(function() { return ajaxStub }); + const handleTimeoutIncrementStub = sandbox.stub(timeoutRtdFunctions, 'handleTimeoutIncrement'); + + timeoutSubmodule.getBidRequestData({}, callback, {}); + + expect(handleTimeoutIncrementStub.called).to.be.false; + expect(callback.called).to.be.true; + expect(ajaxStub.called).to.be.false; + }); + + it('should be able to increment the timeout with the calculated timeout modifier', () => { + const baseTimeout = 100; + const getConfigStub = sandbox.stub().returns(baseTimeout); + sandbox.stub(prebidGlobal, 'getGlobal').callsFake(() => { + return { + getConfig: getConfigStub + } + }); + + const reqBidsConfigObj = {adUnits: [1, 2, 3]} + const addedTimeout = 400; + const rules = { + numAdUnits: { + '3-5': addedTimeout, + } + } + + timeoutRtdFunctions.handleTimeoutIncrement(reqBidsConfigObj, rules) + expect(reqBidsConfigObj.timeout).to.be.equal(baseTimeout + addedTimeout); + }); + + it('should be able to increment the timeout with the calculated timeout modifier when there are multiple matching rules', () => { + const baseTimeout = 100; + const getConfigStub = sandbox.stub().returns(baseTimeout); + sandbox.stub(prebidGlobal, 'getGlobal').callsFake(() => { + return { + getConfig: getConfigStub + } + }); + + const reqBidsConfigObj = {adUnits: [1, 2, 3]} + const addedTimeout = 400; + const rules = { + numAdUnits: { + '3-5': addedTimeout / 2, + }, + includesVideo: { + 'false': addedTimeout / 2, + } + } + timeoutRtdFunctions.handleTimeoutIncrement(reqBidsConfigObj, rules) + expect(reqBidsConfigObj.timeout).to.be.equal(baseTimeout + addedTimeout); + }); +});