diff --git a/modules/yieldmoSyntheticInventoryModule.js b/modules/yieldmoSyntheticInventoryModule.js new file mode 100644 index 00000000000..bca778a7b43 --- /dev/null +++ b/modules/yieldmoSyntheticInventoryModule.js @@ -0,0 +1,46 @@ +import { config } from '../src/config.js'; +import { isGptPubadsDefined } from '../src/utils.js'; + +export const MODULE_NAME = 'Yieldmo Synthetic Inventory Module'; + +export function init(config) { + validateConfig(config); + + if (!isGptPubadsDefined()) { + window.googletag = window.googletag || {}; + window.googletag.cmd = window.googletag.cmd || []; + } + + const googletag = window.googletag; + const containerName = 'ym_sim_container_' + config.placementId; + + googletag.cmd.push(() => { + if (window.document.body) { + googletagCmd(config, containerName, googletag); + } else { + window.document.addEventListener('DOMContentLoaded', () => googletagCmd(config, containerName, googletag)); + } + }); +} + +export function validateConfig(config) { + if (!('placementId' in config)) { + throw new Error(`${MODULE_NAME}: placementId required`); + } + if (!('adUnitPath' in config)) { + throw new Error(`${MODULE_NAME}: adUnitPath required`); + } +} + +function googletagCmd(config, containerName, googletag) { + const gamContainer = window.document.createElement('div'); + gamContainer.id = containerName; + window.document.body.appendChild(gamContainer); + googletag.defineSlot(config.adUnitPath, [1, 1], containerName) + .addService(googletag.pubads()) + .setTargeting('ym_sim_p_id', config.placementId); + googletag.enableServices(); + googletag.display(containerName); +} + +config.getConfig('yieldmo_synthetic_inventory', config => init(config.yieldmo_synthetic_inventory)); diff --git a/modules/yieldmoSyntheticInventoryModule.md b/modules/yieldmoSyntheticInventoryModule.md new file mode 100644 index 00000000000..dd6f0acf884 --- /dev/null +++ b/modules/yieldmoSyntheticInventoryModule.md @@ -0,0 +1,68 @@ +# Yieldmo Synthetic Inventory Module + +## Overview + +This module enables publishers to set up Yieldmo Synthetic Outstream ads on their pages. + +If publishers will enable this module and provide placementId and Google Ad Manager ad unit path, this module will create a placement on the page and inject Yieldmo SDK into this placement. Publisher will then need to get a placement id from their Yieldmo account manager (accounts email) and setup corresponding ad units on the GAM ad server. + +## Integration + +Build the Yieldmo Synthetic Inventory Module into the Prebid.js package with: + +``` +gulp build --modules=yieldmoSyntheticInventoryModule,... +``` + +## Module Configuration + +```js +pbjs.que.push(function() { + pbjs.setConfig({ + yieldmo_synthetic_inventory: { + placementId: '1234567890', + adUnitPath: '/1234567/ad_unit_name_used_in_gam' + } + }); +}); +``` + +### Configuration Parameters + +|Name |Scope |Description | Example| Type +| :------------ | :------------ | :------------ | :------------ | :------------ | +|placementId | required | Yieldmo placement ID | '1234567890' | string +|adUnitPath | required | Google Ad Manager ad unit path | '/6355419/ad_unit_name_used_in_gam' | string + +### How to get ad unit path + +Ad unit path follows the format /network-code/[parent-ad-unit-code/.../]ad-unit-code, where: + +- network-code is a unique identifier for the Ad Manager network the ad unit belongs to +- parent-ad-unit-code are the codes of all parent ad units (only applies to non-top level ad units) +- ad-unit-code is the code for the ad unit to be displayed + +Note that all ad unit codes included in the ad unit path must adhere to the [formatting rules](https://support.google.com/admanager/answer/1628457#ad-unit-codes) specified by Ad Manager. + +Another and probably the easiest way to get an ad unit path is to get it from the google ad manager ad unit document header generated tag: + +```js +googletag.defineSlot('/1234567/ad_unit_name_used_in_gam', [1, 1], 'ad-container-id').addService(googletag.pubads()); +``` + +### How to get Yieldmo placement id + +Please reach out to your Yieldmo account's person or email to support@yieldmo.com + +### Google Ad Manager setup + +Yieldmo Synthetic Inventory Module is designed to be used along with Google Ad Manager. GAM should be set as usual, but there are a few requirements: + +- Ad unit size should be 1x1 +- Creative should NOT be served into a SafeFrame and also should have 1x1 size +- Synthetic Inventory Universal Tag should be used as 3rd party creative code +### Synthetic Inventory Universal Tag + +```js +
+``` \ No newline at end of file diff --git a/test/spec/modules/yieldmoSyntheticInventoryModule_spec.js b/test/spec/modules/yieldmoSyntheticInventoryModule_spec.js new file mode 100644 index 00000000000..55b4e7255f7 --- /dev/null +++ b/test/spec/modules/yieldmoSyntheticInventoryModule_spec.js @@ -0,0 +1,89 @@ +import { expect } from 'chai'; +import { + init, + MODULE_NAME, + validateConfig +} from 'modules/yieldmoSyntheticInventoryModule'; + +const mockedYmConfig = { + placementId: '123456', + adUnitPath: '/6355419/ad_unit_name_used_in_gam' +}; + +const setGoogletag = () => { + window.googletag = { + cmd: [], + defineSlot: sinon.stub(), + addService: sinon.stub(), + pubads: sinon.stub(), + setTargeting: sinon.stub(), + enableServices: sinon.stub(), + display: sinon.stub(), + }; + window.googletag.defineSlot.returns(window.googletag); + window.googletag.addService.returns(window.googletag); + window.googletag.pubads.returns({getSlots: sinon.stub()}); + return window.googletag; +} + +describe('Yieldmo Synthetic Inventory Module', function() { + let config = Object.assign({}, mockedYmConfig); + let googletagBkp; + + beforeEach(function () { + googletagBkp = window.googletag; + delete window.googletag; + }); + + afterEach(function () { + window.googletag = googletagBkp; + }); + + it('should be enabled with valid required params', function() { + expect(function () { + init(mockedYmConfig); + }).not.to.throw() + }); + + it('should throw an error if placementId is missed', function() { + const {placementId, ...config} = mockedYmConfig; + + expect(function () { + validateConfig(config); + }).throw(`${MODULE_NAME}: placementId required`) + }); + + it('should throw an error if adUnitPath is missed', function() { + const {adUnitPath, ...config} = mockedYmConfig; + + expect(function () { + validateConfig(config); + }).throw(`${MODULE_NAME}: adUnitPath required`) + }); + + it('should add correct googletag.cmd', function() { + const containerName = 'ym_sim_container_' + mockedYmConfig.placementId; + const gtag = setGoogletag(); + + init(mockedYmConfig); + + expect(gtag.cmd.length).to.equal(1); + + gtag.cmd[0](); + + expect(gtag.addService.getCall(0)).to.not.be.null; + expect(gtag.setTargeting.getCall(0)).to.not.be.null; + expect(gtag.setTargeting.getCall(0).args[0]).to.exist.and.to.equal('ym_sim_p_id'); + expect(gtag.setTargeting.getCall(0).args[1]).to.exist.and.to.equal(mockedYmConfig.placementId); + expect(gtag.defineSlot.getCall(0)).to.not.be.null; + expect(gtag.enableServices.getCall(0)).to.not.be.null; + expect(gtag.display.getCall(0)).to.not.be.null; + expect(gtag.display.getCall(0).args[0]).to.exist.and.to.equal(containerName); + expect(gtag.pubads.getCall(0)).to.not.be.null; + + const gamContainerEl = window.document.getElementById(containerName); + expect(gamContainerEl).to.not.be.null; + + gamContainerEl.parentNode.removeChild(gamContainerEl); + }); +});