Skip to content

Commit 0507f6d

Browse files
jaanauatijaanauati
authored
improve readme, link to new site (jaanauati#126)
1 parent 417d14d commit 0507f6d

File tree

1 file changed

+33
-137
lines changed

1 file changed

+33
-137
lines changed

‎Readme.md

Lines changed: 33 additions & 137 deletions
Original file line numberDiff line numberDiff line change
@@ -6,157 +6,53 @@
66
A React implementation of the google [DFP](https://developers.google.com/doubleclick-gpt/reference "GPT Reference") api. This package is inspired in the awesome library [jquery.dfp](https://github.com/coop182/jquery.dfp.js), and aims to provide its same ease of usage but, of course, taking into consideration the react concepts & lifecycle features.
77

88

9-
## Install:
9+
## Installation:
10+
11+
To install just run the following command (no other dependencies are required):
1012
```bash
11-
npm install --save-dev react-dfp
13+
npm install --save react-dfp
1214
```
15+
You can find more deatails in the [React-dfp site](http://react-dfp.tk/).
1316

14-
## Usage
1517

16-
1) Create the adslots:
17-
```javascript
18-
import { DFPSlotsProvider, AdSlot } from 'react-dfp';
18+
## Getting started
1919

20-
<DFPSlotsProvider dfpNetworkId={'9999'} adUnit={"foo/bar/baz"} ... >
21-
...
22-
<AdSlot sizes={[ [900, 90], [728, 90]]} />
23-
...
24-
/* you can override the props */
25-
<AdSlot adUnit={"home/mobile"} sizes={[ [300, 250], [300, 600]]} />
26-
...
27-
</DFPSlotsProvider>
28-
```
29-
2) (*Optional*) Render or refresh the ads:
30-
```javascript
31-
import { DFPManager } from 'react-dfp';
32-
...
33-
/* If you are using <DFPSlotsProvider> the following call won't be required,
34-
* unless you have set the property autoLoad={false}.
35-
*/
36-
DFPManager.load();
37-
...
38-
DFPManager.refresh();
39-
```
20+
React-dfp has been designed in a very React-ish way, its main goal is to be able to serve DFP ads in your React application just using React components, that means that you wont have to programatically perform any initialiation call when your page loads.
4021

41-
## Examples:
22+
Here a quick example, notice that ads will render in your page as soon as your component is mounted, through its components (DFPSlotsProvider and AdSlot), react-dfp is making a full abstraction of the google dfp/gpt api.
4223

43-
1) Basic:
4424
```javascript
45-
import React from 'react';
46-
import ReactDom from 'react-dom';
47-
import { DFPSlotsProvider, AdSlot } from 'react-dfp';
48-
49-
ReactDom.render(
50-
<DFPSlotsProvider dfpNetworkId='9999' targetingArguments={ {'customKw': 'test'} }
51-
sizeMapping={ [ {viewport: [1024, 768], sizes:[[728, 90], [300, 250]]},
52-
{viewport: [900, 768], sizes:[[300, 250]] }] }>
53-
<div className="desktop-ads">
54-
<AdSlot sizes={[[728,90], [300, 250]]} adUnit='homepage/1' />
55-
</div>
56-
<div className="mobile-ads">
57-
<AdSlot sizes={[[320,50], [300, 50]]} adUnit='homepage/mobile' />
58-
</div>
59-
...
60-
</DFPSlotsProvider>,
61-
document.querySelectorAll(".ad-container")[0]);
25+
import React, { Component } from 'react';
26+
import { DFPSlotsProvider, AdSlot } from 'react-dfp';
27+
class Page extends Component {
28+
render() {
29+
...
30+
31+
return (
32+
<DFPSlotsProvider dfpNetworkId={'9999'} adUnit={"foo/bar/baz"} ... >
33+
...
34+
<AdSlot sizes={[ [900, 90], [728, 90]]} />
35+
...
36+
/* you can override the props */
37+
<AdSlot adUnit={"home/mobile"} sizes={[ [300, 250], [300, 600]]} />
38+
...
39+
</DFPSlotsProvider>
40+
);
41+
}
42+
}
6243
```
6344

64-
2) (manually) Add and refresh ads.
65-
```javascript
66-
import React from 'react';
67-
import ReactDom from 'react-dom';
45+
## Examples
46+
See the [React-dfp site](http://react-dfp.tk/) for more examples (basic example, how to have refreshable ads, etc).
6847

69-
import {AdSlot, DFPManager} from 'react-dfp';
48+
## Documentation
7049

71-
function loadSecondaryAd() {
72-
ReactDom.render(<AdSlot sizes={[[300, 250]]}
73-
dfpNetworkId='9999'
74-
adUnit='homepage/2'
75-
/>,
76-
document.querySelectorAll(".ad-container-2")[0]);
77-
}
50+
You can find the React-dfp documentation [on the website](http://react-dfp.tk/). The site divided in many sections that describe each one the Components, properties and also the DFPManager api (in case you need to use this one manually).
7851

79-
ReactDom.render( <AdSlot sizes={[[728,90], [300, 250]]}
80-
dfpNetworkId='9999'
81-
adUnit='homepage/1'
82-
targetingArguments={ {'customKw': 'test'} }
83-
sizeMapping={ [ {viewport: [1024, 768], sizes:[[728, 90], [300, 250]]},
84-
{viewport: [900, 768], sizes:[[300, 250]] }] }
85-
onSlotRender={loadSecondaryAd}
86-
/* never refresh this adSlot */
87-
shouldRefresh={ ()=> false }
88-
/>,
89-
document.querySelectorAll(".ad-container")[0]);
90-
DFPManager.setTargetingArguments({'key': 'oh'});
91-
92-
// refresh ads every 15 seconds
93-
window.setInterval(function refreshAds() { DFPManager.refresh(); }, 15000);
94-
95-
DFPManager.load();
96-
```
52+
The website is also full of live/working examples.
53+
54+
If you are also interested on it, you can find the source code of the website here: https://github.com/jaanauati/react-dfp-website.
9755

98-
## Options
99-
100-
### DFPSlotsProvider
101-
102-
| Property | Type | Example | Description |
103-
| ------------------ | ------------- | ----------- | ------- |
104-
| autoLoad | boolean (default true) | ``` { false } ``` | Tell to the provider if it should load the ads when the slots are mounted. |
105-
| dfpNetworkId | string | ``` "1122" ``` | DFP Account id. |
106-
| personalizedAds | boolean (default true) | ```<DFPSlotsProvider personalizedAds={false}> ... </DFPSlotsProvider>``` | Configure whether your page should receive personalized ads or not (see https://support.google.com/admanager/answer/7678538?hl=en). |
107-
| singleRequest | boolean (default true) | ```<DFPSlotsProvider singleRequest={false}> ... </DFPSlotsProvider>``` | Enables or disables the gpt's singleRequest feature. |
108-
| adUnit | string | ``` "homepage" ``` | The adunit you want to target the boxes (children / contained boxes). |
109-
| sizeMapping | array of objects. | ```{ [ {viewport: [1024, 768], sizes:[[728, 90], [300, 250]]}, {viewport: [900, 768], sizes:[[300, 250]] }] } ``` | Set the size mappings to be applied to the nested ad slots. |
110-
| adSenseAttributes | object | ``` { "site_url": "my.site.com", ... } ``` | Object with adSense attributes that will be applied globaly (see: https://developers.google.com/doubleclick-gpt/adsense_attributes). |
111-
| targetingArguments | object | ``` { "keywords": "family", "content": "test" } ``` | Object with attributes you want to set to all the ad slots (custom targeting variables) |
112-
| collapseEmptyDivs | boolean | ```{ false }``` | Enables collapsing of slot divs when there is no ad content to display. |
113-
114-
### AdSlot
115-
116-
| Property | Type | Example | Description |
117-
| ------------------ | ------------- | ----------- | ------- |
118-
| dfpNetworkId | string (required) | ``` "1122" ``` | DFP Account id. |
119-
| adUnit | string (required) | ``` "homepage" ``` | The adunit you want to target to this box. |
120-
| sizes | array (required) | ```[ [300, 250], [300, 600], 'fluid' ] ``` | list of sizes that this box support. Sizes can be specified by either and array like [width, height] or with strings ("dfp named sizes") like 'fluid'. You can configure 1 or more sizes.|
121-
| sizeMapping | array of objects. | ```{ [ {viewport: [1024, 768], sizes:[[728, 90], [300, 250]]}, {viewport: [900, 768], sizes:[[300, 250]] }] }``` | Set the size mappings to be applied to the adSlot. |
122-
| adSenseAttributes | object | ``` { "site_url": "my.site.com", ... } ``` | Object with adSense attributes to apply to the current ad slot (see: https://developers.google.com/doubleclick-gpt/adsense_attributes). |
123-
| targetingArguments | object (optional) | ``` { "keywords": "family", "content": "test" } ``` | Object with attributes you want to add to this box (you can use for custom targeting) |
124-
| onSlotRender | fcn. (optional) | ```function(eventData) { console.log(eventData.size); } ``` | This callback is executed after the adSlot is rendered. The first argument passes the gpt event data (googletag.events.SlotRenderEndedEvent). |
125-
| onSlotIsViewable | fcn. (optional) | ```function(eventData) { console.log(eventData.size); } ``` | This callback is executed after the impresion becomes viewable. The first argument passes the gpt event data (googletag.events.ImpressionViewableEvent). |
126-
| shouldRefresh | fcn. (optional) (should return a boolean)| ``` function() { /* never refresh this ad */ return false; } ``` | Return a boolean that tells the dfp manager whether the ad slot can be refreshed or not. |
127-
| slotId | string. (optional) | ``` "homepage-leadboard" ``` | Controls the id of the dom element in which the dom is displayed. If this field is not provided a random name is created. |
128-
129-
### DFPManager
130-
131-
#### Public methods
132-
| Property | Type | Example | Description |
133-
| ------------------ | ------------- | ----------- | ------- |
134-
| load | ```fcn(...slotId) ```| ```DFPManager.load(); ``` | Fetches the gpt api (by calling init()) and renders the ad slots in the page. You can pass any arbitrary number of slot ids; in this case only the specified ads are initialized. When no argument are passed, all the slots are initialized. |
135-
| refresh | ``` fcn(...slotId) ``` | ```DFPManager.refresh('slot-1', 'slot-2'); ``` | Refreshes the ad slots available in the page. Pass any arbitrary number of slot ids to only refresh those specific slots. If no parameters are passed all the slots are refreshed (with exception of those that prevent it via `shouldRefresh` prop,) This method will call load() if it wasn't already called. Use the method ```<AdSlot shouldRefresh={function(){}} ...>``` to get control over the slots to be refreshed.|
136-
| configureSingleRequest | ```fcn(boolean)``` | ```DFPManager.configureSingleRequest( false )``` | Controls the strategy to use for the network requests. This method accepts a boolean that tells wether to enable or disable the singleRequest mode. |
137-
| configurePersonalizedAds | ```fcn(boolean)``` | ```DFPManager.configurePersonalizedAds( false )``` | Configure the strategy to serve ads. true: serve personalized ads, false: configure dfp to not serve personalized ads (see https://support.google.com/admanager/answer/7678538?hl=en). |
138-
| singleRequestEnabled | ```fcn() => bool``` | ``` DFPManager.singleRequestEnabled(); ``` | Returns true when the singleRequest mode is enabled, false otherwise. |
139-
| setAdSenseAttributes | ``` fcn(object)``` | ``` DFPManager.setAdSenseAttributes({ "page_url": "www.site.com", "adsense_link_color": "#000000"}); ``` | Use this method to set AdSense attributes. |
140-
| setAdSenseAttribute | ``` fcn(key, value)``` | ``` DFPManager.setAdSenseAttributes("page_url", "www.site.com"); ``` | Use this method to set AdSense attributes. |
141-
| getAdSenseAttributes | ```fcn() => object``` | ``` DFPManager.getAdSenseAttributes(); ``` | This method returns an object with the global adSense attributes. |
142-
| getAdSenseAttribute | ```fcn(key) => value``` | ``` DFPManager.getAdSenseAttribute("page_url"); ``` | Returns the value of a custom adSense attribute. |
143-
| setTargetingArguments | ``` fcn(object)``` | ``` DFPManager.setTargetingArguments({ "keywords": "family", "content": "test" }); ``` | Use this function to pass custom targetting variables. |
144-
| getGoogletag | ```fcn() => Promise ```| ``` DFPManager.getGoogletag().then( googletag => { console.log(googletag); }); ``` | Returns a promise that resolves when the object googletag object is ready for usage (if required this fcn makes the network call to fetch the scripts). |
145-
| setCollapseEmptyDivs | ```fcn(boolean)``` | ```DFPManager.setCollapseEmptyDivs( true )``` | Enables collapsing of slot divs when there is no ad content to display. The method accepts one parameter that expects the following values: false: collapse after ads are fetched; true: collapse divs before ads are fetched; null/undefined: do not collapse divs. |
146-
147-
#### For Internal Usage Only
148-
| Property | Type | Example | Description |
149-
| ------------------ | ------------- | ----------- | ------- |
150-
| init | ```fcn() => Promise ```| ```DFPManager.init(); ```| Initializes the dfp manager (fetches the gpt scripts from network). Returns a promise that resolves when the gpt api is ready for usage. |
151-
| unregisterSlot | ```fcn(slotId)``` | ```DFPManager.unregisterSlot('hp-001')``` | Unregisters the given slot. This method also calls DFPManager.destroyGPTSlots(...). |
152-
| attachSlotRenderEnded | ``` fcn( fcn({slotId, event}) ) ``` | ``` DFPManager.attachSlotRenderEnded((id, event) => {console.log(event.size); }) ``` | Attaches a callback that will be called when an ad slot is rendered (or refreshed). slotId is the id of slot. event is the gpt event data. |
153-
| detachSlotRenderEnded | ``` fcn(callback) ``` | ``` DFPManager.detachSlotRenderEnded(myCallback) ``` | Detaches the callback. |
154-
| getRegisteredSlots | ``` fcn() => {} ``` | ``` Object.keys(DFPManager.getRegisteredSlots()) ``` | Returns an object whose attributes are the registered slots. Example: ``` { slotId: { data }, .... }```|
155-
| getRefreshableSlots | ``` fcn() => { slotId:{ slot }, ... } ``` | ``` console.log(DFPManager.getRegisteredSlots().length); ``` | Returns an object whose properties are slots that can be refreshed (see property ```shouldRefresh``` ). |
156-
| getTargetingArguments | ``` fcn() => {} ``` | ``` Object.keys(DFPManager.getTargetingArguments()) ``` | Returns an object that contains the targeting arguments (configured through ```DFPManager.setTargetingArguments()```) |
157-
| getSlotTargetingArguments | ``` fcn(slotId) => {} ``` | ``` console.log(DFPManager.getSlotTargetingArguments('slot-five')['the-key']); ``` | Returns an object that contains the custom targeting arguments that were set for the given slot (slotId). |
158-
| getSlotAdSenseAttributes | ``` fcn(slotId) => {} ``` | ``` console.log(DFPManager.getSlotAdSenseAttributes('slot-five')['the-key']); ``` | Returns an object that contains all the adSense attributes were previously set to the given slot (slotId). |
159-
| destroyGPTSlots| ```fcn(...slotId) => Promise``` | ```DFPManager.destroyGPTSlots('hp-001', 'hp-002')``` | Identifies the gpt adSlots linked to the provided ids and subsequently calls googletag.destroysSlots(...). Returns a promise that resolves when the slots are destroyed.|
16056

16157
## Wanna help?
16258
I certainly know that testcases need to be improved, but, as long as your syntax is clean, submit testscases and, of course, all the interfaces are kept working, all kind of contribution is welcome.

0 commit comments

Comments
 (0)