Merge pull request #14 from freestarcapital/version-2.0.0

Version 2.0.0

.gitignore

@@ -23,6 +23,7 @@
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+*.tgz
 
 # editor directories and files
 .idea

README-BYPASS.md

@@ -0,0 +1,122 @@
+# Bypassing Freestar Placements
+
+The Freestar Vue Component allows for the ability to bypass relying on Freestar placements.
+
+Note: Using this option will not allow Freestar to monetize the adUnit with header bidding demand nor allow Freestar to
+manage the ad unit.
+
+### Example
+
+```vue
+<template>
+ <div>
+ <freestar-ad-slot
+ :ad-refresh="adRefreshCount"
+ :placement-name="adUnit.placementName"
+ :targeting="adUnit.targeting"
+ :channel="channel"
+ :class-list="classList"
+ :slot-size="slotSize"
+ :size-mapping="sizeMapping"
+ :ad-unit-path="adUnitPath"
+ @new-ad-slots="onNewAdSlotsHook"
+ @delete-ad-slots="onDeleteAdSlotsHook"
+ @ad-refresh="onAdRefreshHook"
+ />
+ <button @click="onAdRefresh">
+ Trigger Refresh
+ </button>
+ </div>
+</template>
+
+<script>
+export default {
+ name: 'Demo',
+ data() {
+ return {
+ adUnit: {
+ placementName: 'div-gpt-ad-leaderboard-multi',
+ slotId: 'div-gpt-ad-leaderboard-multi',
+ targeting: { key1: 'value1', key2: 'value2' },
+ },
+ channel: 'custom_channel',
+ classList: ['m-30', 'p-15', 'b-thin-red'],
+ adRefreshCount: 0,
+ slotSize: [[300,250], [728,90]],
+ sizeMapping: [
+ {viewport: [0,0], slot: [300,250]},
+ {viewport: [768, 0], slot: [728,90]}
+ ],
+ adUnitPath: '/45796/my_adunit_name',
+ };
+ },
+ mounted() {
+ this.$nextTick(() => {
+ this.createAdRefreshExample();
+ });
+ },
+ methods: {
+ onNewAdSlotsHook(placementName) {
+ console.log('freestar.newAdSlots() was called', { placementName });
+ },
+ onDeleteAdSlotsHook(placementName) {
+ console.log('freestar.deleteAdSlots() was called', { placementName });
+ },
+ onAdRefreshHook(placementName) {
+ console.log('adRefresh was called', { placementName });
+ },
+ // example of manually refreshing an ad
+ onAdRefresh() {
+ this.adRefreshCount += 1;
+ },
+ createAdRefreshExample() {
+ // example of automatically refreshing an ad every 5 seconds a total of 5 times
+ const interval = setInterval(() => {
+ const maxRefreshes = 5;
+ this.adRefreshCount += 1;
+ if (this.adRefreshCount === maxRefreshes) {
+ clearInterval(interval);
+ }
+ }, 5000);
+ },
+ },
+};
+
+</script>
+
+<style>
+ .m-30 {
+ margin: 30px;
+ }
+
+ .p-15 {
+ padding: 15px;
+ }
+
+ .b-thin-red {
+ border: 1px solid red;
+ }
+</style>
+```
+
+### Additional Props
+**adUnitPath**
+An *optional* string with the full GAM ad unit path. This should be used only if you are intending to bypass Freestar placements intentionally.
+
+**slotSize**
+An *optional* string or array as defined by [GPT Documentation](https://developers.google.com/publisher-tag/reference#googletag.GeneralSize). Should only be used in conjuction with `adUnitPath`
+
+**sizeMapping**
+An *optional* array of object which contains an array of viewport size and slot size. To be used in conjunction with `adUnitPath`. This needs to be set if the ad needs to serve different ad size per different view port sizes (responsive ad).
+Setting the `slot` to any dimension that's not configured in DFP results in rendering an empty ad.
+The ad slot size which is provided for the viewport size of [0, 0] will be used as default ad size if none of viewport size matches.
+
+https://support.google.com/dfp_premium/answer/3423562?hl=en
+
+ e.g.
+  
+ sizeMapping={[
+  {viewport: [0, 0], slot: [320, 50]},
+  {viewport: [768, 0], slot: [728, 90]}
+ ]}
+  

README-KVPCONFIGMAPPING.md

@@ -0,0 +1,18 @@
+# Key Value Config Mapping
+
+You can optionally specify a configuration file to map placements based key value pairs. Do not use this without the support of your Freestar Team 
+
+### Usage
+in your Vue app entry point (main.js)
+
+```js
+import FreestarAdSlot from '@freestar/pubfig-adslot-vue-component';
+
+const KEY_VALUE_CONFIG_MAPPING_URL = 'https://api.jsonbin.io/b/6000f76fe31fbc3bdef3d725/1';
+
+Vue.use(FreestarAdSlot, { publisher: 'publisherString', keyValueConfigMappingURL: KEY_VALUE_CONFIG_MAPPING_URL });
+```
+
+### Additional Options
+**keyValueConfigMappingURL**
+An *optional* string with the full url to the Key Value Config Mapping file. Consult with your Freestar Account Manager for more information on how to have this file setup

README.md

@@ -1,78 +1,91 @@
 # Freestar Pubfig Ad Slot Vue Component
 
+## NOTE: As of v2.0, the plugin must be installed using Vue.use()
+
 ### Install
 
 ```sh
 npm install --save @freestar/pubfig-adslot-vue-component
 ```
 
+In your Vue app entry point add the following:
+```js
+import FreestarAdSlot from '@freestar/pubfig-adslot-vue-component';
+
+Vue.use(FreestarAdSlot, { publisher: 'publisherString' });
+```
+
+**Options**
+- **publisher** A *required* string of the publisher, which will be provided by Freestar.
+
 ### Usage
 
 ```html
 <template>
  <div>
- <FreestarAdSlot
- ref='freestarAdSlotRef'
- :adRefresh=adRefreshCount
- :adUnit=adUnit
- :channel=channel
- :classList=classList
- v-on:new-ad-slots='onNewAdSlotsHook'
- v-on:delete-ad-slots='onDeleteAdSlotsHook'
- v-on:ad-refresh='onAdRefreshHook'
+ <freestar-ad-slot
+ :ad-refresh="adRefreshCount"
+ :placement-name="adUnit.placementName"
+ :targeting="adUnit.targeting"
+ :channel="channel"
+ :class-list="classList"
+ @new-ad-slots="onNewAdSlotsHook"
+ @delete-ad-slots="onDeleteAdSlotsHook"
+ @ad-refresh="onAdRefreshHook"
  />
- <button v-on:click='onAdRefresh'>Trigger Refresh</button>
+ <button @click="onAdRefresh">
+ Trigger Refresh
+ </button>
  </div>
 </template>
 
 <script>
-import FreestarAdSlot from '@freestar/pubfig-adslot-vue-component'
-
-export default {
- name: 'Demo',
- data: function () {
- return {
- adUnit: {
- placementName: 'div-gpt-ad-leaderboard-multi',
- slotId: 'div-gpt-ad-leaderboard-multi',
- targeting: ['value1', 'value2']
- },
- channel: 'custom_channel',
- classList: ['m-30', 'p-15', 'b-thin-red'],
- adRefreshCount: 0
- }
- },
- components: {
- FreestarAdSlot
- },
- methods: {
- onNewAdSlotsHook: function (placementName) {
- console.log('freestar.newAdSlots() was called', {placementName})
+ export default {
+ name: 'Demo',
+ data() {
+ return {
+ adUnit: {
+ placementName: 'div-gpt-ad-leaderboard-multi',
+ slotId: 'div-gpt-ad-leaderboard-multi',
+ targeting: { key1: 'value1', key2: 'value2' },
+ },
+ channel: 'custom_channel',
+ classList: ['m-30', 'p-15', 'b-thin-red'],
+ adRefreshCount: 0,
+ };
  },
- onDeleteAdSlotsHook: function (placementName) {
- console.log('freestar.deleteAdSlots() was called', {placementName})
+ mounted() {
+ this.$nextTick(() => {
+ this.createAdRefreshExample();
+ });
  },
- onAdRefreshHook: function (placementName) {
- console.log('adRefresh was called', {placementName})
+ methods: {
+ onNewAdSlotsHook(placementName) {
+ console.log('freestar.newAdSlots() was called', { placementName });
+ },
+ onDeleteAdSlotsHook(placementName) {
+ console.log('freestar.deleteAdSlots() was called', { placementName });
+ },
+ onAdRefreshHook(placementName) {
+ console.log('adRefresh was called', { placementName });
+ },
+ // example of manually refreshing an ad
+ onAdRefresh() {
+ this.adRefreshCount += 1;
+ },
+ createAdRefreshExample() {
+ // example of automatically refreshing an ad every 5 seconds a total of 5 times
+ const interval = setInterval(() => {
+ const maxRefreshes = 5;
+ this.adRefreshCount += 1;
+ if (this.adRefreshCount === maxRefreshes) {
+ clearInterval(interval);
+ }
+ }, 5000);
+ },
  },
- // example of manually refreshing an ad
- onAdRefresh: function () {
- this.adRefreshCount++
- }
- },
- mounted: function () {
- this.$nextTick(() => {
- // example of automatically refreshing an ad every 5 seconds a total of 5 times
- const interval = setInterval(() => {
- const maxRefreshes = 5
- this.adRefreshCount++
- if (this.adRefreshCount === maxRefreshes) {
- clearInterval(interval)
- }
- }, 5000)
- })
- }
-}
+ };
+
 </script>
 
 <style>
@@ -88,12 +101,16 @@ export default {
  border: 1px solid red;
  }
 </style>
+
 ```
 
 ### Props
 
-**adUnit**
-A *required* object with *required* `placementName` & `slotId` and *optional* `targeting` properties.
+**placementName**
+A *required* string of the ad unit placement, which will be provided by Freestar.
+
+**targeting**
+An *optional* object of key/value pairs for targeting.
 
 **channel**
 An *optional* string of a custom channel to use.
@@ -104,20 +121,37 @@ An *optional* array of strings representing any additional classes that should b
 **adRefresh**
 An *optional* number bound to the ad refresh. You can increment this value to trigger a refresh of the ad slot.
 
+### Events
+
+**new-ad-slots**
+returns the `placementName` when the component **mounts** and an ad is requested.
+
+**delete-ad-slots**
+returns 
+
+**ad-refresh**
+returns the `placementName` when the component refreshes an ad.
+
 ### API Methods
 
-**FreestarAdSlot.setPageTargeting**
-Proxy for the GPT setTargeting call to set page level targeting. (use a ref, e.g. this.$refs.freestarAdSlotRef.setPageTargeting(key, value)) See [GPT documentation](https://developers.google.com/doubleclick-gpt/reference#googletag.PubAdsService_setTargeting) for more details
+**this.$freestar.setPageTargeting(key, value)**
+Proxy for the GPT setTargeting call to set page level targeting. See [GPT documentation](https://developers.google.com/doubleclick-gpt/reference#googletag.PubAdsService_setTargeting) for more details
+
+**this.$freestar.clearPageTargeting(key)**
+Proxy for the GPT clearTargeting call to clear page level targeting. See [GPT documentation](https://developers.google.com/doubleclick-gpt/reference#googletag.PubAdsService_clearTargeting) for more details
+
+**this.$freestar.trackPageView()**
+Proxy for the freestar.trackPageview() method.
+
+Freestar collects data values such as url location which is then used in various tables. In order to properly track data sites that are using Single Page Applications (SPAs), or sites with slideshows/carousels that change urls/url parameters these new actions must be taken by the publisher to assure accuracy of the collected data. When the location and/or url is updated the lifecycle of the DOM and/or Window does not reload the pubfig.js script. In order to address this the publisher must invoke the freestar.trackPageview() method. This will ensure that the new url is stored and used throughout the data collection for that page or view.
 
-**FreestarAdSlot.clearPageTargeting**
-Proxy for the GRP clearTargeting call to clear page level targeting. (use a ref, e.g. this.$refs.freestarAdSlotRef.clearPageTargeting()) See [GPT documentation](https://developers.google.com/doubleclick-gpt/reference#googletag.PubAdsService_clearTargeting) for more details
 ### Glossary
 
 **placementName**
 A value acquired from Google Ad Manager (previously known as DFP/Adx), which will be provided by Freestar.
 
-**slotId**
-A value used for the DOM `<div>` id for the ad unit to render within.
-
 **targeting**
 A set of targeting values for the ad unit placement.
+
+### Bypassing Freestar Ad Placements
+If you would like to bypass Freestar Ad placements and render GAM ad units yourself directly please follow the instructions [here](README-BYPASS.md)