Yieldmo Synthetic Inventory Module: initial commit

modules/yieldmoSyntheticInventoryModule.js

@@ -0,0 +1,42 @@
+import { config } from '../src/config.js';
+
+export const MODULE_NAME = 'Yieldmo Synthetic Inventory Module';
+
+export function init(config) {
+  validateConfig(config);
+
+  window.top.googletag = window.top.googletag || {cmd: []};
+
+  const googletag = window.top.googletag;
+  const containerName = 'ym_sim_container_' + config.placementId;
+
+  googletag.cmd.push(() => {
+    if (window.top.document.body) {
+      googletagCmd(config, containerName, googletag);
+    } else {
+      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.top.document.createElement('div');
+  gamContainer.id = containerName;
+  window.top.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));

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({
+        ym_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
+<div id="ym_%%PATTERN:ym_sim_p_id%%" class="ym"></div><script type="text/javascript">(function(e,t){if(t._ym===void 0){t._ym="";var m=e.createElement("script");m.type="text/javascript",m.async=!0,m.src="//static.yieldmo.com/ym."+Math.round(5*Math.random()/3)+".js",(e.getElementsByTagName("head")[0]||e.getElementsByTagName("body")[0]).appendChild(m)}else t._ym instanceof String||void 0===t._ym.chkPls||t._ym.chkPls()})(document,window);</script>
+```

test/spec/modules/yieldmoSyntheticInventoryModule_spec.js

@@ -0,0 +1,37 @@
+import { expect } from 'chai';
+import {
+  init,
+  MODULE_NAME,
+  validateConfig
+} from 'modules/yieldmoSyntheticInventoryModule';
+
+const mockedYmConfig = {
+  placementId: '123456',
+  adUnitPath: '/6355419/ad_unit_name_used_in_gam'
+};
+
+describe('Yieldmo Synthetic Inventory Module', function() {
+  let config = Object.assign({}, mockedYmConfig);
+
+  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`)
+  });
+});