{"_id":"@aller/ads","_rev":"37-6347184ccd309d07eda71b695c2016b7","name":"@aller/ads","dist-tags":{"latest":"0.0.2"},"versions":{"0.0.2":{"name":"@aller/ads","version":"0.0.2","license":"MIT","_id":"@aller/ads@0.0.2","maintainers":[{"name":"n00t","email":"jardar@protonmail.com"},{"name":"zackkorman","email":"zack.korman@medialaben.no"},{"name":"alexbazan","email":"alexander-bazan@outlook.com"},{"name":"ueland","email":"tor.henning@gmail.com"},{"name":"misund","email":"just.misund@sol.no"},{"name":"risto1913","email":"risto@kvarme.net"},{"name":"jimoe","email":"jon3828@gmail.com"},{"name":"vnorvik","email":"vnorvik@gmail.com"},{"name":"ryaaoka","email":"natalia.bezvoziuk@medialaben.no"},{"name":"morganbro","email":"morgan.bro@dagbladet.no"},{"name":"hameltomor","email":"hameltomor@gmail.com"},{"name":"kasperrt","email":"kasper@kasperrt.no"},{"name":"erlend_seppo","email":"erlend.seppola@gmail.com"},{"name":"benbenbenjamin","email":"benjamin.oliver@medialaben.no"},{"name":"andrew.ovcharenko","email":"andrew.ovcharenko@medialaben.no"},{"name":"dimasty","email":"dlazarchuk@gmail.com"},{"name":"sushasgit","email":"gryshchukoleksandra@gmail.com"},{"name":"kevinmidboe","email":"Kevin.Midboe@gmail.com"}],"dist":{"shasum":"b3dd2ab7d8a54717fcae7899dbeab981a3fb7f31","tarball":"https://registry.npmjs.org/@aller/ads/-/ads-0.0.2.tgz","fileCount":20,"integrity":"sha512-BsMSB8mc+KaNgCzBuFM5mYN4w65df3fDnTS/p69BaA8BgRWLtqTv+X5V4WBtBnNXeV44s/WUNUKz+nTpRZKHgQ==","signatures":[{"sig":"MEYCIQCToedH0bwsjars8xONYrz0n5CHo0rLd5nrkDIpv97FYgIhAOHPbw/CzTlayAxQYGUSeGR1Ju9vAjB0vOQ9F5V7hlFy","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":53020,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v4.10.10\r\nComment: https://openpgpjs.org\r\n\r\nwsFzBAEBCAAGBQJiK04oACEJED1NWxICdlZqFiEECWMYAoorWMhJKdjhPU1b\r\nEgJ2VmqopA//fB1TYlXka4hUOQWZRXuZvY5BDJwTsQdWq2kKKH0pAnG0o2Em\r\nYI1JLzebwW08owiao6R7jpnkMjE6k+0REPMkByg/oJm0FOEu9hs47Zx+Hctz\r\nQucEzbhQJgnmkgERLe8jmXOWhaNbl70SIezP+L7GP8x6bBlxs6Y6h38VqKT2\r\nTMciCzk7jsGnZLGCuDhFiMaOnv6vCE6bjqoRw+uTzXEw+ulbDVi6hZ5ibavB\r\nGWiKQcsFcFRMVomgabiHEPzJ4KBRZ6qQnxOhHDXz/5dyM5RJMXk4YY0wPFrq\r\n049lP0wjQc6xmmgsf2BUgVSKfNHOLS93JNEJDfyOUpkBZ8AlWjchtThzNTG0\r\n43gsblYdTLiPT6dcITzbsgvuCF14LXHxwSQDYBE+qgM/Fz5QLxt2yIUHCnmW\r\nFfbxr2nqk1yUWpoOBvoQPahQZNL/pTuAfWVyMhMjH/266IMkEUtCpkVq0BDH\r\n0XojTK1+wNwRLsbFn2o2riV2GqKQ2Ams76HcrRc307qKtIuZ+n61b0D1++62\r\n/QHdxlx+2i5OpkJgOpdsHbzU/kIsXrugBviOFuxFboUajv7lSqRkx1dfk/+v\r\n92+lCwC76dI4mHYEyXYriZiLF3JtYYHU7jd5O57PdbXWQvONPGOyAaUaLru1\r\nwqZmNkYu5op5LEZMAPirRUQkytCtkZKb/OM=\r\n=ivE0\r\n-----END PGP SIGNATURE-----\r\n"},"scripts":{"dev":"","test":"","build":""},"_npmUser":{"name":"n00t","email":"jardar@protonmail.com"},"_npmVersion":"6.14.15","description":"Library for doing ads with React","directories":{},"_nodeVersion":"14.17.6","dependencies":{"react":"17.0.2","react-dom":"17.0.2","@babel/preset-env":"7.14.5"},"_hasShrinkwrap":false,"devDependencies":{"@types/doubleclick-gpt":"2019111201.0.0"},"_npmOperationalInternal":{"tmp":"tmp/ads_0.0.2_1647005224028_0.5776325948918282","host":"s3://npm-registry-packages"}}},"time":{"created":"2022-03-11T13:27:03.983Z","modified":"2026-05-18T14:43:32.360Z","0.0.2":"2022-03-11T13:27:04.195Z"},"license":"MIT","description":"Library for doing ads with React","maintainers":[{"email":"jon3828@gmail.com","name":"jimoe"},{"email":"marius.ibsen@gmail.com","name":"lobunto"},{"email":"goodleby@gmail.com","name":"goodleby"},{"email":"konrad.jorgensen@gmail.com","name":"konrad-j"},{"email":"jesus.castanocandela@gmail.com","name":"roninjc"},{"email":"tore.meek@aller.com","name":"toremeek"},{"email":"vnorvik@gmail.com","name":"vnorvik"},{"email":"robin.wasjo@aller.com","name":"robinwa"},{"email":"pal.edman@outlook.com","name":"paed01"},{"email":"kuhanloh@gmail.com","name":"kuhanloh"}],"readme":"# @aller/ads\nThis is a library to help with displaying ads for React based apps (and others). It's a fork-ish of https://github.com/dbmedialab/wolverine-frontend/packages/ads\n\n\n## Displaying an Advertisement\nYou can display an advertisement by calling the `registerAd` method, this can be called as many times and wherever you'd like as required.\n\n```javascript\nads.registerAd({\n  id: 'ad-topbanner1',\n  slotName: 'dagbladet.no/forsiden',\n  dimensions: [[300, 250], [300, 600]],\n})\n```\n\nAlong with the `registerAd` call you also need a div on the page with the same id.\n\n```html\n<div id=\"ad-topbanner1\"></div>\n```\n\nIf you are using an external service to manage initial ad load (like Didomi), set `window.blockArcAdsLoad = true` on page load to block ArcAds from refreshing ads. Set `window.blockArcAdsLoad = false` when you want ArcAds to control refreshing ads again.\n\nThe following table shows all of the possible parameters the `registerAd` method accepts.\n\n| Parameter | Description | Type | Requirement |\n| ------------- | ------------- | ------------- | ------------- |\n| `id`  | The `id` parameter corresponds to a div id on the page that the advertisement should render into. | `String` | `Required` | \n| `slotName`  | The `slotName` parameter is equal to the slot name configured within DFP, for example `sitename/dagbladet.no/forside`. The publisher ID gets attached to the slot name within the ArcAds logic. | `String` | `Required` |\n| `dimensions`  | The `dimensions` parameter should be an array with array of arrays containing the advertisement sizes the slot can load. If left empty the advertisement will be considered as an out of page unit. | `Array` | `Optional` |\n| `targeting`  | The `targeting` paramter accepts an object containing key/value pairs which should attached to the advertisement request. | `Object` | `Optional` |\n| `sizemap`  | The `sizemap` paramter accepts an object containing information about the advertisements size mapping, for more information refer to the [Size Mapping portion of the readme](https://github.com/dbmedialab/wolverine-frontend/packages/ads#size-mapping). | `Object` | `Optional` |\n| `bidding`  | The `bidding` paramter accepts an object containing information about the advertisements header bidding vendors, for more information refer to the [Header Bidding portion of the readme](https://github.com/dbmedialab/wolverine-frontend/packages/ads#header-bidding). | `Object` | `Optional` | \n| `prerender`  | The `prerender` parameter accepts an a function that should fire before the advertisement loads, for more information refer to the [Prerender Hook portion of the readme](https://github.com/dbmedialab/wolverine-frontend/packages/ads/tree/master#prerender-hook). | `Function` | `Optional` | \n\n### Out of Page Ads\nIf an advertisement has an empty or missing `dimensions` parameter it will be considered as a [DFP Out of Page creative](https://support.google.com/dfp_premium/answer/6088046?hl=en) and rendered as such.\n\n### Callback\nWhenever an advertisement loads you can access data about the advertisement such as its size and id by passing in an optional callback to the initialization of ArcAds. This ties a handler to the `slotRenderEnded` event that DFP emits and is called everytime an advertisement is about to render, allowing you to make any page layout modifications to accomodate a specific advertisement.\n\n```javascript\nconst ads = new GPTAds({\n  dfp: {\n    id: '8578'\n  }\n}, (event) => {\n  console.log('Advertisement has loaded...', event)\n})\n```\n\n#### Refreshing an Advertisement\nIf you require the ability to refresh a specific advertisement you can do so via the googletag library, providing it the slot object from GPT. You can get access to the slot object in the callback of ArcAds via `event.slot`.\n\n```javascript\nconst ads = new GPTAds({\n  dfp: {\n    id: '123'\n  }\n}, (event) => {\n  window.adSlot = event.slot\n})\n\n// Refresh a single ad slot\nwindow.googletag.pubads().refresh([window.adSlot])\n\n// Refresh all ad slots on the page\nwindow.googletag.pubads().refresh()\n```\n\n### Targeting\nAdvertisement targeting parameters can be passed to the registration call via the `targeting` object.\n\n```javascript\narcAds.registerAd({\n  id: 'ad-topbanner1',\n  slotName: 'dagbladet.no/forside',\n  dimensions: [[300, 250], [300, 600]],\n  targeting: {\n    section: 'weather'\n  }\n})\n```\n\n## Size Mapping\nYou can configure DFP size mapped ads with the same registration call by adding a `sizemap` object. To utilize size mapping the `dimensions` key should be updated to include an array representing a nested array of arrays containing the applicable sizes for a specific breakpoint.\n\n```javascript\n[ [[970, 250], [970, 90], [728, 90]],\n  [[728, 90]],\n  [[320, 100], [320, 50]] ]\n```\n\nFollowed by an array of equal lengths of breakpoints which will sit within `sizemap.breakpoints`.\n\n```javascript\n[ [1280, 0], [800, 0], [0, 0] ]\n```\n\nWhen put together this will mean that at a window width of 1280 wide, the service can load a `970x250`, `970x90` or a `728x90` advertisement. At 800 wide, it can load a `728x90`, and anything below 800 it will load a `320x90` or a `320x50`.\n\nIf the advertisement should refresh dynamically when the user resizes the screen after the initial load you can toggle `refresh` to `true`. otherwise it should be `false`.\n\n```javascript\nads.registerAd({\n  id: 'ad-topbanner1',\n  slotName: 'dagbladet.no/forside',\n  dimensions: [ [[970, 250], [970, 90], [728, 90]], [[728, 90]], [[320, 100], [320, 50]] ],\n  targeting: {\n    section: 'weather'\n  },\n  sizemap: {\n    breakpoints: [ [1280, 0], [800, 0], [0, 0] ],\n    refresh: true\n  }\n})\n```\n\n## Prerender Hook\nWe provide a way for you to get information about an advertisement before it loads, which is useful for attaching targeting data from third party vendors.\n\nYou can setup a function within the `registerAd` call by adding a `prerender` paramter, the value of which being the function you'd like to fire before the advertisement loads. This function will also fire before the advertisement refreshes if you're using sizemapping.\n\n```javascript\narcAds.registerAd({\n  id: 'ad-topbanner1',\n  slotName: 'dagbladet.no/forside',\n  dimensions: [[300, 250], [300, 600]],\n  prerender: window.adFunction\n})\n```\n\nYour `prerender` function must return a promise. Once it's resolved the advertisement will display. If you do not resolve the promise the advertisement will *not* render.\n\n```javascript\nwindow.adFunction = function(ad) {\n  return new Promise(function(resolve, reject) {\n    // The 'ad' arguement will provide information about the unit\n    console.log(ad)\n    // If you do not resolve the promise the advertisement will not display\n    resolve()\n  });\n}\n```\n\nYou can gather information about the advertisement by accessing the `ad` argument/object.\n\n| Key  | Description |\n| ------------- | ------------- |\n| `adUnit`  | An object containing the GPT ad slot. This can be used when calling other GPT methods.  |\n| `adSlot`  | Contains a string with the full slot name of the advertisement.  |\n| `adDimensions`  | Contains an array with the size of the advertisement which is about to load.   |\n| `adId`  | Contains a string with the id of the advertisement.  |\n\n## Header Bidding\nWe support prebid only.\n\n### Prebid.js\n\n```javascript\n<script src=\"path/to/prebid.js\"></script>\n<script src=\"path/to/arcads.js\"></script>\n\n<script type=\"text/javascript\">\n  const ads = new GPTAds({\n    dfp: {\n      id: '123'\n    }, \n    bidding: {\n      prebid: {\n        enabled: true\n      }\n    }\n  })\n</script>\n\n```\nYou can enable Prebid.js on the wrapper by adding a `prebid` object to the wrapper initialization and setting `enabled: true`. You can also optionally pass it a `timeout` value which corresponds in milliseconds how long Prebid.js will wait until it closs out the bidding for the advertisements on the page. By default the timeout will be set to `700`.\n\n```javascript\nconst ads = new GPTAds({\n  dfp: {\n    id: '123'\n  },\n  bidding: {\n    prebid: {\n      enabled: true,\n      timeout: 1000\n    }\n  }\n}\n```\n\nIf you want to use the slotName instead of the ad id when registering ads, pass `useSlotForAdUnit: true`.\n\n```javascript\nconst ads = new GPTAds({\n  dfp: {\n    id: '123'\n  },\n  bidding: {\n    prebid: {\n      enabled: true,\n      timeout: 1000,\n      useSlotForAdUnit: true\n    }\n  }\n}\n```\n\nOn the wrapper you can also configure a size mapping configuration, which will provide information to Prebid.js on which sized advertisements it should fetch bids for on each breakpoint. For more information on what needs to be configured within the `sizeConfig` array click [here](http://prebid.org/dev-docs/examples/size-mapping.html).\n\n```javascript\nconst arcAds = new ArcAds({\n  dfp: {\n    id: '123'\n  },\n  bidding: {\n    prebid: {\n      enabled: true,\n      timeout: 1000,\n      sizeConfig: [\n        {\n          'mediaQuery': '(min-width: 1024px)',\n          'sizesSupported': [\n            [970, 250],\n            [970, 90],\n            [728, 90]\n          ],\n          'labels': ['desktop']\n        }, \n        {\n          'mediaQuery': '(min-width: 480px) and (max-width: 1023px)',\n          'sizesSupported': [\n            [728, 90]\n          ],\n          'labels': ['tablet']\n        }, \n        {\n          'mediaQuery': '(min-width: 0px)',\n          'sizesSupported': [\n            [320, 100],\n            [320, 50]\n          ],\n          'labels': ['phone']\n        }\n      ]\n    }\n  }\n})\n```\n\nOn the advertisement registration you can then provide information about which bidding services that specific advertisement should use. You can find a list of paramters that Prebid.js accepts for each adapter on the [Prebid.js website](http://prebid.org/dev-docs/publisher-api-reference.html). Additionally you can turn on [Prebid.js debugging](http://prebid.org/dev-docs/toubleshooting-tips.html) by adding `?pbjs_debug=true` to the url.\n\n```javascript\narcAds.registerAd({\n  id: 'ad-topbanner1',\n  slotName: 'dagbladet.no/forside',\n  adType: 'cube',\n  display: 'desktop',\n  dimensions: [ [[970, 250], [970, 90], [728, 90]], [[728, 90]], [[320, 100], [320, 50]] ],\n  sizemap: {\n    breakpoints: [ [1280, 0], [800, 0], [0, 0] ],\n    refresh: 'true'\n  },\n  bidding: {\n    prebid: {\n      enabled: true,\n      bids: [{\n        bidder: 'appnexus',\n        labels: ['desktop', 'tablet', 'phone'],\n        params: {\n          placementId: '10433394' \n        }\n      }]\n    }\n  }\n})\n```\n\nIn certain scenarios you may want to define different sizes for Prebid.js than what you use in GPT. The `registerAd` method will by default use your dimensions to set these for you, but you can override this by adding a `mediaTypes` property to your bidding configuration. You can read more about media types on the [Prebid.js website](http://prebid.org/dev-docs/adunit-reference.html#adunitmediatypes).\n```javascript\narcAds.registerAd({\n  id: 'ad-topbanner1',\n  slotName: 'dagbladet.no/forside',\n  dimensions: [ [[970, 250], [970, 90], [728, 90]], [[728, 90]], [[320, 100], [320, 50]] ],\n  sizemap: {\n    breakpoints: [ [1280, 0], [800, 0], [0, 0] ],\n    refresh: 'true'\n  },\n  bidding: {\n    prebid: {\n      enabled: true,\n      mediaTypes: {\n        banner: {\n          sizes: [[980, 300], [970, 250]],\n        },\n      },\n      bids: [{\n        bidder: 'appnexus',\n        labels: ['desktop', 'tablet', 'phone'],\n        params: {\n          placementId: '10433394' \n        }\n      }]\n    }\n  }\n})\n```\n\n### Slot Override\nYou can override the slot name of every advertisement on the page by appending `?adslot=` to the URL. This will override whatever is placed inside of the `slotName` field when invoking the `registerAd` method. For example if you hit the URL `arcpublishing.com/?adslot=homepage/myad`, the full ad slot path will end up being your DFP id followed by the value: `123/homepage/myad`.\n\nYou can also debug slot names and GPT in general by typing `window.googletag.openConsole()` into the browsers developer console.\n\n\n","readmeFilename":"README.md"}