diff --git a/src/__tests__/index.spec.js b/src/__tests__/index.spec.js index de195a2a..5e4d4325 100644 --- a/src/__tests__/index.spec.js +++ b/src/__tests__/index.spec.js @@ -2,8 +2,10 @@ import { run, runWaterfall, requestAd, - requestNextAd + requestNextAd, + vastSelectors } from '../index'; +import * as selectors from '../vastSelectors'; test('must publish `requestAd`', () => { expect(requestAd).toBeInstanceOf(Function); @@ -21,3 +23,7 @@ test('must publish `runWaterfall`', () => { expect(runWaterfall).toBeInstanceOf(Function); }); +test('must publish `vastSelectors`', () => { + expect(vastSelectors).toEqual(selectors); +}); + diff --git a/src/index.js b/src/index.js index 1102338f..2742bee8 100644 --- a/src/index.js +++ b/src/index.js @@ -1,7 +1,6 @@ /** * @module @mailonline/video-ad-sdk * @description Video ad SDK to load and play HTML5 video ads. - * */ import run from './runner/run'; @@ -9,11 +8,13 @@ import runWaterfall from './runner/runWaterfall'; import requestAd from './vastRequest/requestAd'; import requestNextAd from './vastRequest/requestNextAd'; import getDetails from './vastChain/getDetails'; +import * as vastSelectors from './vastSelectors'; export { getDetails, run, runWaterfall, requestAd, - requestNextAd + requestNextAd, + vastSelectors }; diff --git a/src/runner/runWaterfall.js b/src/runner/runWaterfall.js index 9e04554f..c6339fc7 100644 --- a/src/runner/runWaterfall.js +++ b/src/runner/runWaterfall.js @@ -152,8 +152,8 @@ const waterfall = async (fetchVastChain, placeholder, options, isCanceled) => { * Defaults to `true`. * @param {Object} [options.hooks] - Optional map with hooks to configure the behaviour of the ad. * @param {Function} [options.hooks.createSkipControl] - If provided it will be called to generate the skip control. Must return a clickable [HTMLElement](https://developer.mozilla.org/es/docs/Web/API/HTMLElement) that is detached from the DOM. - * @param {Function} [options.hooks.validateVastResponse] - If provided it will be called for each valid vast response. Must throw if there is a problem with the vast response. If the Error instance has an `code` number then it will be tracked using the error macros in the Vast response. It will also call {@link runWaterfall~onError} with the thrown error. - * @param {Function} [options.hooks.transformVastResponse] - If provided it will be called before building the adUnit allowing the modification of the vastResponse if needed. + * @param {Function} [options.hooks.validateVastResponse] - If provided it will be called passing the current {@link VastChain} for each valid vast response. Must throw if there is a problem with the vast response. If the Error instance has an `code` number then it will be tracked using the error macros in the Vast response. It will also call {@link runWaterfall~onError} with the thrown error. + * @param {Function} [options.hooks.transformVastResponse] - If provided it will be called with the current {@link VastChain} before building the adUnit allowing the modification of the vastResponse if needed. * @returns {Function} - Cancel function. If called it will cancel the ad run. {@link runWaterfall~onRunFinish} will still be called; */ const runWaterfall = (adTag, placeholder, options) => { diff --git a/src/types.js b/src/types.js index 33ea4a37..4721150a 100644 --- a/src/types.js +++ b/src/types.js @@ -128,6 +128,18 @@ * @property {string} [universalAdId] - A string identifying the unique creative identifier. */ +/** + * VAST InteractiveFile representation + * For more info please take a look at the [VAST specification]{@link https://iabtechlab.com/standards/vast/} + * + * @global + * @typedef InteractiveFile + * @type Object + * @property {string} [apiFramework] - will most likely be `VPAID` + * @property {string} [src] - The source file url. + * @property {string} [type] - MIME type for the file container like `application/javascript`. + */ + /** * VastTrackingEvent. * For more info please take a look at the [VAST specification]{@link https://iabtechlab.com/standards/vast/} diff --git a/src/vastSelectors/getIcons.js b/src/vastSelectors/getIcons.js index 2d44b439..a4da0ffe 100644 --- a/src/vastSelectors/getIcons.js +++ b/src/vastSelectors/getIcons.js @@ -94,15 +94,6 @@ const getIconClicks = (iconElement) => { }; }; -/** - * Gets the Vast Icon definitions from the Vast Ad - * - * @function - * @param {ParsedAd} ad - VAST ad object. - * @returns {?Array.} - Array of VAST icon definitions - * @static - * @ignore - */ const getIcons = (ad) => { const linearCreativeElement = ad && getLinearCreative(ad); const linearElement = linearCreativeElement && get(linearCreativeElement, 'linear'); diff --git a/src/vastSelectors/getLinearTrackingEvents.js b/src/vastSelectors/getLinearTrackingEvents.js index 8dfa37f7..172c1c72 100644 --- a/src/vastSelectors/getLinearTrackingEvents.js +++ b/src/vastSelectors/getLinearTrackingEvents.js @@ -7,16 +7,6 @@ import { import parseOffset from './helpers/parseOffset'; import getLinearCreative from './helpers/getLinearCreative'; -/** - * Gets the Linear tracking events from the Vast Ad - * - * @function - * @param {ParsedAd} ad - VAST ad object. - * @param {string} [eventName] - If provided it will filter-out the array events against it. - * @returns {?Array.} - Array of Tracking event definitions - * @static - * @ignore - */ const getLinearTrackingEvents = (ad, eventName) => { const creativeElement = ad && getLinearCreative(ad); diff --git a/src/vastSelectors/getNonLinearTrackingEvents.js b/src/vastSelectors/getNonLinearTrackingEvents.js index d732cbe2..90978454 100644 --- a/src/vastSelectors/getNonLinearTrackingEvents.js +++ b/src/vastSelectors/getNonLinearTrackingEvents.js @@ -6,16 +6,6 @@ import { } from '../xml'; import getLinearCreative from './helpers/getLinearCreative'; -/** - * Gets the Non Linear tracking events from the Vast Ad - * - * @function - * @param {ParsedAd} ad - VAST ad object. - * @param {string} [eventName] - If provided it will filter-out the array events against it. - * @returns {?Array.} - Array of Tracking event definitions - * @static - * @ignore - */ const getNonLinearTrackingEvents = (ad, eventName) => { const creativeElement = ad && getLinearCreative(ad); diff --git a/src/vastSelectors/index.js b/src/vastSelectors/index.js index 28f62637..ebfc2a8e 100644 --- a/src/vastSelectors/index.js +++ b/src/vastSelectors/index.js @@ -1,3 +1,8 @@ +/** + * @memberof module:@mailonline/video-ad-sdk + * @description Published as part of {@link module:@mailonline/video-ad-sdk} + * @module vastSelectors + */ import { get, getAll, @@ -42,7 +47,6 @@ const compareBySequence = (itemA, itemB) => { * @param {ParsedVast} parsedVAST - Parsed VAST xml. * @returns {?Array} - Array of ads or empty array. * @static - * @ignore */ export const getAds = (parsedVAST) => { const vastElement = parsedVAST && get(parsedVAST, 'VAST'); @@ -62,7 +66,6 @@ export const getAds = (parsedVAST) => { * @param {ParsedVast} parsedVAST - Parsed VAST xml. * @returns {?VAST-macro} - Vast Error URI or `null` otherwise. * @static - * @ignore */ export const getVastErrorURI = (parsedVAST) => { const vastElement = parsedVAST && get(parsedVAST, 'VAST'); @@ -85,7 +88,6 @@ export const getVastErrorURI = (parsedVAST) => { * @param {ParsedAd} ad - Parsed ad definition object. * @returns {?number} - The pod ad sequence number or `null`. * @static - * @ignore */ export const getPodAdSequence = (ad) => { const sequence = parseInt(getAttribute(ad, 'sequence'), 10); @@ -104,7 +106,6 @@ export const getPodAdSequence = (ad) => { * @param {ParsedAd} ad - Parsed ad definition object. * @returns {?boolean} - Returns true if there the ad is a pod ad and false otherwise. * @static - * @ignore */ export const isPodAd = (ad) => Boolean(getPodAdSequence(ad)); @@ -115,7 +116,6 @@ export const isPodAd = (ad) => Boolean(getPodAdSequence(ad)); * @param {ParsedVAST} parsedVAST - Parsed VAST xml. * @returns {?boolean} - Returns true if there is an ad pod in the array and false otherwise. * @static - * @ignore */ export const hasAdPod = (parsedVAST) => { const ads = getAds(parsedVAST); @@ -126,11 +126,11 @@ export const hasAdPod = (parsedVAST) => { /** * Returns true if the passed VastChain has an ad pod or false otherwise. * + * @function * @param {Array} VastChain - Array of VAST responses. See `load` or `requestAd` for more info. * * @returns {boolean} - True if the VastChain contains an ad pod and false otherwise. * @static - * @ignore */ export const isAdPod = (VastChain = []) => VastChain.map(({parsedXML}) => parsedXML).some(hasAdPod); @@ -141,7 +141,6 @@ export const isAdPod = (VastChain = []) => VastChain.map(({parsedXML}) => parsed * @param {ParsedVAST} parsedVAST - Parsed VAST xml. * @returns {?ParsedAd} - First ad of the VAST xml or `null`. * @static - * @ignore */ export const getFirstAd = (parsedVAST) => { const ads = getAds(parsedVAST); @@ -165,7 +164,6 @@ export const getFirstAd = (parsedVAST) => { * @param {ParsedAd} ad - VAST ad object. * @returns {boolean} - `true` if the ad contains a wrapper and `false` otherwise. * @static - * @ignore */ export const isWrapper = (ad = {}) => Boolean(get(ad || {}, 'Wrapper')); @@ -176,7 +174,6 @@ export const isWrapper = (ad = {}) => Boolean(get(ad || {}, 'Wrapper')); * @param {ParsedAd} ad - VAST ad object. * @returns {boolean} - Returns `true` if the ad contains an Inline or `false` otherwise. * @static - * @ignore */ export const isInline = (ad) => Boolean(get(ad || {}, 'Inline')); @@ -187,7 +184,6 @@ export const isInline = (ad) => Boolean(get(ad || {}, 'Inline')); * @param {ParsedAd} ad - VAST ad object. * @returns {?string} - Returns the VASTAdTagURI from the wrapper ad or `null` otherwise. * @static - * @ignore */ export const getVASTAdTagURI = (ad) => { const wrapperElement = get(ad, 'Wrapper'); @@ -207,7 +203,6 @@ export const getVASTAdTagURI = (ad) => { * @param {Object} ad - VAST ad object. * @returns {WrapperOptions} - Returns the options from the wrapper ad. * @static - * @ignore */ export const getWrapperOptions = (ad) => { const { @@ -240,7 +235,6 @@ export const getWrapperOptions = (ad) => { * @param {ParsedAd} ad - VAST ad object. * @returns {?string} - Vast ad Error URI or `null` otherwise. * @static - * @ignore */ export const getAdErrorURI = (ad) => { const adTypeElement = ad && getFirstChild(ad); @@ -263,7 +257,6 @@ export const getAdErrorURI = (ad) => { * @param {ParsedAd} ad - VAST ad object. * @returns {?string} - Vast ad Impression URI or `null` otherwise. * @static - * @ignore */ export const getImpressionUri = (ad) => { const adTypeElement = ad && getFirstChild(ad); @@ -280,13 +273,12 @@ export const getImpressionUri = (ad) => { }; /** - * Gets the ads MediaFiles. + * Gets the ad's MediaFiles. * * @function * @param {ParsedAd} ad - VAST ad object. * @returns {?Array.} - array of media files or null * @static - * @ignore */ export const getMediaFiles = (ad) => { const creativeElement = ad && getLinearCreative(ad); @@ -339,6 +331,14 @@ export const getMediaFiles = (ad) => { return null; }; +/** + * Gets the ad's InteractiveFiles. That were added with the `InteractiveCreativeFile` tag. + * + * @function + * @param {ParsedAd} ad - VAST ad object. + * @returns {?Array.} - array of media files or null + * @static + */ export const getInteractiveCreativeFiles = (ad) => { const creativeElement = ad && getLinearCreative(ad); @@ -367,6 +367,14 @@ export const getInteractiveCreativeFiles = (ad) => { return null; }; +/** + * Gets all the ad's InteractiveFiles. + * + * @function + * @param {ParsedAd} ad - VAST ad object. + * @returns {?Array.} - array of media files or null + * @static + */ export const getInteractiveFiles = (ad) => { let interactiveFiles = getInteractiveCreativeFiles(ad); @@ -412,7 +420,6 @@ const getVideoClicksElement = (ad) => { * @param {ParsedAd} ad - VAST ad object. * @returns {?VAST-macro} - clickthrough macro * @static - * @ignore */ export const getClickThrough = (ad) => { const videoClicksElement = getVideoClicksElement(ad); @@ -432,7 +439,6 @@ export const getClickThrough = (ad) => { * @param {ParsedAd} ad - VAST ad object. * @returns {?Array.} - click tracking macro * @static - * @ignore */ export const getClickTracking = (ad) => { const videoClicksElement = getVideoClicksElement(ad); @@ -452,7 +458,6 @@ export const getClickTracking = (ad) => { * @param {ParsedAd} ad - VAST ad object. * @returns {?Array.} - click tracking macro * @static - * @ignore */ export const getCustomClick = (ad) => { const videoClicksElement = getVideoClicksElement(ad); @@ -472,7 +477,6 @@ export const getCustomClick = (ad) => { * @param {Object} ad - VAST ad object. * @returns {?ParsedOffset} - the time offset in milliseconds or a string with the percentage or null * @static - * @ignore */ export const getSkipOffset = (ad) => { const creativeElement = ad && getLinearCreative(ad); @@ -509,7 +513,15 @@ const getXmlEncodedValue = (xml) => { return Boolean(result) && result[1] === 'true'; }; -const getCreativeData = (xml) => { +/** + * Gets the creative data. + * + * @function + * @param {string} xml - VAST XML text. + * @returns {Object} - with `AdParameters` as they come in the XML and a flag `xmlEncoded` to indicate if the ad parameters are xml encoded. + * @static + */ +export const getCreativeData = (xml) => { const linearContent = getLinearContent(xml); const AdParameters = linearContent && getAdParametersContent(linearContent); const xmlEncoded = linearContent && getXmlEncodedValue(linearContent); @@ -521,8 +533,36 @@ const getCreativeData = (xml) => { }; export { - getCreativeData, + + /** + * Gets the Vast Icon definitions from the Vast Ad. + * + * @function + * @param {ParsedAd} ad - VAST ad object. + * @returns {?Array.} - Array of VAST icon definitions + * @static + */ getIcons, + + /** + * Gets the Linear tracking events from the Vast Ad + * + * @function + * @param {ParsedAd} ad - VAST ad object. + * @param {string} [eventName] - If provided it will filter-out the array events against it. + * @returns {?Array.} - Array of Tracking event definitions + * @static + */ getLinearTrackingEvents, + + /** + * Gets the Non Linear tracking events from the Vast Ad + * + * @function + * @param {ParsedAd} ad - VAST ad object. + * @param {string} [eventName] - If provided it will filter-out the array events against it. + * @returns {?Array.} - Array of Tracking event definitions + * @static + */ getNonLinearTrackingEvents };