|
pierre@0
|
1 ---------
|
|
pierre@0
|
2 Overview:
|
|
pierre@0
|
3 ---------
|
|
pierre@0
|
4 The ad module is a powerful advertising system for Drupal-powered websites. It
|
|
pierre@0
|
5 supports the random display and tracking of graphical (banner), text and raw
|
|
pierre@0
|
6 html ads. Ads can easily be displayed in themes, blocks, or embedded in site
|
|
pierre@0
|
7 content. The module records comprehensive statistics about when and how often
|
|
pierre@0
|
8 ads are viewed and clicked, including a plug-in module for generating graphical
|
|
pierre@0
|
9 time-based reports. Ads can be assigned to multiple owners, each of which can
|
|
pierre@0
|
10 be assigned their own set of permissions. Installation is simple by design. An
|
|
pierre@0
|
11 API is provided allowing the development of additional functionality and
|
|
pierre@0
|
12 integration with other Drupal modules.
|
|
pierre@0
|
13
|
|
pierre@0
|
14 Features:
|
|
pierre@0
|
15 * auto-generated ad blocks supporting a configurable number of ads
|
|
pierre@0
|
16 * automatically or manually embed ads into site content
|
|
pierre@0
|
17 * collection of comprehensive statistics allowing time-based reporting and
|
|
pierre@0
|
18 analysis
|
|
pierre@0
|
19 * tracking of when and where ads are clicked, by which user and which IP
|
|
pierre@0
|
20 * advertisements can have multiple owners
|
|
pierre@0
|
21 * granular per-advertisement/per-owner permissions system
|
|
pierre@0
|
22 * activation/expiration scheduling based on time, clicks or impressions
|
|
pierre@0
|
23 * an ad_image plug-in for image (aka banner) ads
|
|
pierre@0
|
24 * an ad_text plug-in for simple text ads
|
|
pierre@0
|
25 * an ad_html plug-in for raw html ads
|
|
pierre@0
|
26 * an externally maintained ad_geoip plug-in provides support for
|
|
pierre@0
|
27 geotargeting ads
|
|
pierre@0
|
28 * an ad_report plug-in for basic graphical reports
|
|
pierre@0
|
29 * an ad_notify plug-in for scheduling automatic email notifications
|
|
pierre@0
|
30 * an ad_remote plug-in for hosting ads on remote (non-Drupal) websites
|
|
pierre@0
|
31 * an administrative statistics overview page
|
|
pierre@0
|
32 * support for any number of configurable ad groups, utilizing Drupal's
|
|
pierre@0
|
33 taxonomy (category) subsystem
|
|
pierre@0
|
34 * display ads based on node ids (nids) or taxonomy terms (categories)
|
|
pierre@0
|
35 * file-based caching for improved performance
|
|
pierre@0
|
36 * memcache-based caching for improved performance
|
|
pierre@0
|
37 * support for external caching methods
|
|
pierre@0
|
38 * MySQL and PostgreSQL support
|
|
pierre@0
|
39
|
|
pierre@0
|
40
|
|
pierre@0
|
41 ------
|
|
pierre@0
|
42 Usage:
|
|
pierre@0
|
43 ------
|
|
pierre@0
|
44 Installation and requirements information can be found within the INSTALL.txt
|
|
pierre@0
|
45 file included with this module.
|
|
pierre@0
|
46
|
|
pierre@0
|
47
|
|
pierre@0
|
48 -------------
|
|
pierre@0
|
49 Creating ads:
|
|
pierre@0
|
50 -------------
|
|
pierre@0
|
51 Once the ad module is properly installed an enabled, you can create
|
|
pierre@0
|
52 advertisements by visiting 'create content' on your website and choosing
|
|
pierre@0
|
53 'advertisement' as the content type. If you have enabled multiple ad type
|
|
pierre@0
|
54 modules, you can select one of them from the resulting menu, such as 'image
|
|
pierre@0
|
55 advertiesment' or 'text advertisement'.
|
|
pierre@0
|
56
|
|
pierre@0
|
57 Text ads:
|
|
pierre@0
|
58 ---------
|
|
pierre@0
|
59 Text ads are very simple, requiring that you fill out only three fields of
|
|
pierre@0
|
60 information. First, you need to specify the Destination URL where you want
|
|
pierre@0
|
61 people to be redirected when they click on your text ad. Second, you enter
|
|
pierre@0
|
62 the a header for your ad. The header will be linked to the Destination URL.
|
|
pierre@0
|
63 Finally, you need to specify the body of your ad.
|
|
pierre@0
|
64
|
|
pierre@0
|
65 Image ads:
|
|
pierre@0
|
66 ----------
|
|
pierre@0
|
67 Image ads or only slightly more complicated than text ads. They depend on
|
|
pierre@0
|
68 the drupal core Upload module for managing the actual images. As with text
|
|
pierre@0
|
69 ads, you first need to specify the Destination URL where you want people to
|
|
pierre@0
|
70 be redirected when they click on your image ad. Second, you can optoinally
|
|
pierre@0
|
71 enter some Mouseover text. If you enter text in the mouseover field this
|
|
pierre@0
|
72 text will be displayed when people hover their mouse pointer over the
|
|
pierre@0
|
73 advertisement. Finally, you need to scroll down to the File attachements
|
|
pierre@0
|
74 section of the page and click the Browser button to select your image, then
|
|
pierre@0
|
75 click Attach to upload the image.
|
|
pierre@0
|
76
|
|
pierre@0
|
77 HTML ads:
|
|
pierre@0
|
78 ---------
|
|
pierre@0
|
79 HTML ads allow you to easily define your own custom ad type by simply pasting
|
|
pierre@0
|
80 in a block of HTML code. At this time, however, the ad module is unable to
|
|
pierre@0
|
81 track when html ads are clicked.
|
|
pierre@0
|
82
|
|
pierre@0
|
83 Ad groups:
|
|
pierre@0
|
84 ----------
|
|
pierre@0
|
85 Ads can be organized into groups. For example, you may have a group called
|
|
pierre@0
|
86 "Text Ads" and another group called "Image Ads." You could then assign your
|
|
pierre@0
|
87 text ads to the "Text Ads" group, and your image ads to your "Image Ads"
|
|
pierre@0
|
88 groups. (This is not required, it is perfectly valid to include both image
|
|
pierre@0
|
89 ads and text ads in the same group.) When displaying ads, you typically tell
|
|
pierre@0
|
90 the ad module to display ads from a certain group and then the ad module
|
|
pierre@0
|
91 randomly selects an active ad from the specified group. Each ad can be a
|
|
pierre@0
|
92 member of any number of groups.
|
|
pierre@0
|
93
|
|
pierre@0
|
94 Ad status:
|
|
pierre@0
|
95 ----------
|
|
pierre@0
|
96 There are several states that an ad can exist in. An ad in the Pending state
|
|
pierre@0
|
97 is one that has recently been uploaded and is waiting to be approved by a
|
|
pierre@0
|
98 privileged user. An ad in the Approved state is one that has been approved
|
|
pierre@0
|
99 by a privileged user but is not actively being displayed, the ad could be
|
|
pierre@0
|
100 waiting on an autoactivation event. An ad in the Active state is being
|
|
pierre@0
|
101 actively displayed. An ad in the Offline state is approved but is currently
|
|
pierre@0
|
102 not being displayed. An ad in the Unpublished state means that the ad node
|
|
pierre@0
|
103 was unpublished so the ad is not any longer being displayed. An ad in the
|
|
pierre@0
|
104 Expired state is no longer being displayed. An ad in the Denied state means
|
|
pierre@0
|
105 it was not approved by the site administrator.
|
|
pierre@0
|
106
|
|
pierre@0
|
107 Scheduling:
|
|
pierre@0
|
108 -----------
|
|
pierre@0
|
109 If you put an ad into the Approved state and then enter a date and time in the
|
|
pierre@0
|
110 Automatically Activate Ad field, the ad will be automatically activated
|
|
pierre@0
|
111 on the date and time specified. This feature requires that cron be functional
|
|
pierre@0
|
112 on your website. If you enter a date and time in the Automatically Expire Ad
|
|
pierre@0
|
113 field, the ad will be automatically expired on the date and time specified.
|
|
pierre@0
|
114 Again, this feature requires that cron be functional on your website.
|
|
pierre@0
|
115
|
|
pierre@0
|
116 If you enter a number into the Maximum Impressions field, the ad will be
|
|
pierre@0
|
117 automatically expired once it has been displayed this number of times.
|
|
pierre@0
|
118
|
|
pierre@0
|
119 If you enter a number into the Maximum Clicks field, the ad will be
|
|
pierre@0
|
120 automatically expired once it has been clicked this number of times.
|
|
pierre@0
|
121
|
|
pierre@0
|
122
|
|
pierre@0
|
123 ---------------
|
|
pierre@0
|
124 Displaying ads:
|
|
pierre@0
|
125 ---------------
|
|
pierre@0
|
126 There are many ways to display ads with the ad module. The simplest way
|
|
pierre@0
|
127 is to enable one of the automatically generated ad blocks. It is also possible
|
|
pierre@0
|
128 to use the ad_embed module to automatically embed ads within your site content.
|
|
pierre@0
|
129 And you can even display ads from within the PHP of your theme or another
|
|
pierre@0
|
130 module.
|
|
pierre@0
|
131
|
|
pierre@0
|
132 ----------
|
|
pierre@0
|
133 Ad blocks:
|
|
pierre@0
|
134 ----------
|
|
pierre@0
|
135 The ad module automatically generates on ad block for every ad group that you
|
|
pierre@0
|
136 create. For example, if you visit "Administer >> Site building >> Blocks"
|
|
pierre@0
|
137 you will find a block named "ad group: default". If you enable this block,
|
|
pierre@0
|
138 it will display a random ad from all active ads in the default group.
|
|
pierre@0
|
139
|
|
pierre@0
|
140 You can optionally configure the block to display more than one ad at a time
|
|
pierre@0
|
141 by clicking the 'configure' link on the block administration page.
|
|
pierre@0
|
142
|
|
pierre@0
|
143 -------------
|
|
pierre@0
|
144 Embedded ads:
|
|
pierre@0
|
145 -------------
|
|
pierre@0
|
146 If you enabled the ad_embed module, it is possible to embed ads into your
|
|
pierre@0
|
147 site content. To configure the ad_embed module go to "Administer >> Content
|
|
pierre@0
|
148 Management >> Ads >> Settings >> Embedded ads".
|
|
pierre@0
|
149
|
|
pierre@0
|
150 If you wish to manually embed ads in your content, check the box next to
|
|
pierre@0
|
151 "Replace ad bracket tags" or "Replace ad comment tags". This will cause the
|
|
pierre@0
|
152 ad_embed module to replace embedded [[add]] or <!--ad--> tags respectively.
|
|
pierre@0
|
153 Instructions on how to specify specific ad groups or even specific ads and
|
|
pierre@0
|
154 how many ads to display at a time can be found by visiting "Administer >>
|
|
pierre@0
|
155 Help >> Embed".
|
|
pierre@0
|
156
|
|
pierre@0
|
157 If you wish to automatically embed ads in your content, configure this on a
|
|
pierre@0
|
158 per-content-type basis in the lower configuration section.
|
|
pierre@0
|
159 embeded ads".
|
|
pierre@0
|
160
|
|
pierre@0
|
161 ------------------------
|
|
pierre@0
|
162 Displaying ads from PHP:
|
|
pierre@0
|
163 ------------------------
|
|
pierre@0
|
164 To display an ad from within PHP code, make a call to the ad() function.
|
|
pierre@0
|
165 You can optionally specify an ad group, the number of ads to display, and
|
|
pierre@0
|
166 several other options. For example, to display one random ad from all ads
|
|
pierre@0
|
167 that have not been assigned to any group you don't have to pass in any
|
|
pierre@0
|
168 parameters:
|
|
pierre@0
|
169 <?php print ad(); ?>
|
|
pierre@0
|
170
|
|
pierre@0
|
171 To display two ads from all ads that have not been assigned to any group
|
|
pierre@0
|
172 you would execute the following code:
|
|
pierre@0
|
173 <?php print ad(0, 2); ?>
|
|
pierre@0
|
174
|
|
pierre@0
|
175 (The first parameter specifies the ad group to display ads from. By
|
|
pierre@0
|
176 specifying 0, we are telling the ad module to display ads that are not
|
|
pierre@0
|
177 assigned to any group. The second parameter specifies the number of ads
|
|
pierre@0
|
178 to display at one time.)
|
|
pierre@0
|
179
|
|
pierre@0
|
180 To randomly display an ad from a specific group of nids, for example with
|
|
pierre@0
|
181 the node ID 69 or 76, you would pass in the following parameters:
|
|
pierre@0
|
182 <?php print ad(NULL, 1, array('nids' => '69,76')); ?>
|
|
pierre@0
|
183
|
|
pierre@0
|
184 (When specifying specific nids, any specified ad group is ignored, so we
|
|
pierre@0
|
185 leave the first parameter as NULL. The second parameter causes only one
|
|
pierre@0
|
186 ad to be displayed at a time. And the third parameter is an array that
|
|
pierre@0
|
187 tells the ad module to randomly display either ad 69 or ad 76.)
|
|
pierre@0
|
188
|
|
pierre@0
|
189 To display and ad randomly selected from multiple groups you can simply
|
|
pierre@0
|
190 specify multiple groups separated by commas. For example, to display 3
|
|
pierre@0
|
191 ads from groups 24, 56 and 98 you would pass in the following parameters:
|
|
pierre@0
|
192 <?php print ad('24,56,98', 2); ?>
|
|
pierre@0
|
193
|
|
pierre@0
|
194 You can also specify how to display a given ad. Current display methods are
|
|
pierre@0
|
195 'javascript' and 'raw'. When using the 'javascript' method, ads will
|
|
pierre@0
|
196 randomly change even when the Drupal pagecache is enabled. When using the
|
|
pierre@0
|
197 'raw' method, ads will only change when the Drupal pagecache is flushed.
|
|
pierre@0
|
198 To force one ad with a tid of 76 to display using JavaScript you would pass
|
|
pierre@0
|
199 in the following parameters:
|
|
pierre@0
|
200 <?php print ad(76, 1, array('method' => 'javascript'));
|
|
pierre@0
|
201
|
|
pierre@0
|
202 To force two ads with a tid of 101 or 102 to display using the Raw method
|
|
pierre@0
|
203 you would pass in the following parameters:
|
|
pierre@0
|
204 <?php print ad('101,102', 76, array('method' => 'raw'));
|
|
pierre@0
|
205
|
|
pierre@0
|
206 ------------
|
|
pierre@0
|
207 Theming ads:
|
|
pierre@0
|
208 ------------
|
|
pierre@0
|
209 All ads are wrapped in the following tags:
|
|
pierre@0
|
210 <div class="advertisement" id="group-#"></div>
|
|
pierre@0
|
211
|
|
pierre@0
|
212 All ads are in the same "advertisement" class. Each ad group gets a unique
|
|
pierre@0
|
213 id. This makes it possible to create generic advertisement formatting as
|
|
pierre@0
|
214 well as specific advertisement formatting.
|
|
pierre@0
|
215
|
|
pierre@0
|
216 CSS Example 1:
|
|
pierre@0
|
217 --------------
|
|
pierre@0
|
218 This sample code can be added to your theme's custom style.css. It adds
|
|
pierre@0
|
219 padding to advertisements, wrapping them in a dashed border and giving
|
|
pierre@0
|
220 them a background color. It also adds the text "Advertisement:" above
|
|
pierre@0
|
221 the ad:
|
|
pierre@0
|
222
|
|
pierre@0
|
223 .advertisement {
|
|
pierre@0
|
224 padding: 5px;
|
|
pierre@0
|
225 border: dashed;
|
|
pierre@0
|
226 background-color: #ffd;
|
|
pierre@0
|
227 }
|
|
pierre@0
|
228
|
|
pierre@0
|
229 .advertisement:before {
|
|
pierre@0
|
230 content: "Advertisement:";
|
|
pierre@0
|
231 }
|
|
pierre@0
|
232
|
|
pierre@0
|
233 CSS Example 2:
|
|
pierre@0
|
234 --------------
|
|
pierre@0
|
235 Here is more sample code that could be added to your theme's custom
|
|
pierre@0
|
236 style.css. It will cause multiple image ads to be displayed horizontally
|
|
pierre@0
|
237 one beside the other (space permitting), rather than vertically one
|
|
pierre@0
|
238 below the other. The ads are aligned to the left side of the screen,
|
|
pierre@0
|
239 if you'd prefer them to be aligned to the right side of the screen change
|
|
pierre@0
|
240 the word "left" to "right" in the snippet:
|
|
pierre@0
|
241
|
|
pierre@0
|
242 .image-advertisement {
|
|
pierre@0
|
243 float: left;
|
|
pierre@0
|
244 padding: 3px;
|
|
pierre@0
|
245 }
|
|
pierre@0
|
246
|
|
pierre@0
|
247
|
|
pierre@0
|
248 -------------------
|
|
pierre@0
|
249 Ad module settings:
|
|
pierre@0
|
250 -------------------
|
|
pierre@0
|
251 The ad module and related modules provide a number of configuration options.
|
|
pierre@0
|
252
|
|
pierre@0
|
253 ----------------
|
|
pierre@0
|
254 Global settings:
|
|
pierre@0
|
255 ----------------
|
|
pierre@0
|
256 The ad module allows you to specify some global settings at "Administer >>
|
|
pierre@0
|
257 Content management >> Ads >> Settings >> Global settings".
|
|
pierre@0
|
258
|
|
pierre@0
|
259 Even if you do not plan to make any changes, you should visit this page at
|
|
pierre@0
|
260 least one time as the ad module will perform a series of sanity tests when
|
|
pierre@0
|
261 you visit this page, alerting you to any installation problems.
|
|
pierre@0
|
262
|
|
pierre@0
|
263 This page begins by displaying the path to serve.php. If you see an error
|
|
pierre@0
|
264 here, then the ad module is not properly installed. Review the directions
|
|
pierre@0
|
265 in INSTALL.txt to properly install the ad module.
|
|
pierre@0
|
266
|
|
pierre@0
|
267 In the General section you can specify what happens when an advertisement is
|
|
pierre@0
|
268 clicked. For example, you can choose to have the resulting Destination URL
|
|
pierre@0
|
269 opened in the same browser window, or in a new browser window. You can also
|
|
pierre@0
|
270 enable the "nofollow" check box causing ads served by the ad module to
|
|
pierre@0
|
271 include rel="nofollow" in automatically generated links. You can select
|
|
pierre@0
|
272 to display advertisements using JavaScript, jQuery, IFrames, or Raw HTML.
|
|
pierre@0
|
273 Finally, you can disable URL validation, and enable advertisement filtering.
|
|
pierre@0
|
274
|
|
pierre@0
|
275 Checking 'Filter ads' allows you to apply Drupal's standard input filters
|
|
pierre@0
|
276 to your advertisements. If you enable this option, be sure to apply a
|
|
pierre@0
|
277 compatible filter that doesn't strip away the <div> and other tags used by
|
|
pierre@0
|
278 the various advertisement types.
|
|
pierre@0
|
279
|
|
pierre@0
|
280 The next section allows you to configure IFrames, if you are using them to
|
|
pierre@0
|
281 display advertisements.
|
|
pierre@0
|
282
|
|
pierre@0
|
283 For better performance, you can also enable a cache. At this time there is
|
|
pierre@0
|
284 only a file cache available. When the file cache is enabled, ads are quickly
|
|
pierre@0
|
285 displayed from a cache file without bootstrapping Drupal. On very busy
|
|
pierre@0
|
286 websites you may need to increase the number of cache files to prevent
|
|
pierre@0
|
287 cache file contention.
|
|
pierre@0
|
288
|
|
pierre@0
|
289 ---------
|
|
pierre@0
|
290 Text ads:
|
|
pierre@0
|
291 ---------
|
|
pierre@0
|
292 The ad_text module allows you to specify some minimum and maximum lengths for
|
|
pierre@0
|
293 text ads at "Administer >> Content management >> Ads >> Settings >> Text ads".
|
|
pierre@0
|
294
|
|
pierre@0
|
295 ----------
|
|
pierre@0
|
296 Image ads:
|
|
pierre@0
|
297 ----------
|
|
pierre@0
|
298 The ad_image module allows you to specify some image constraints on a
|
|
pierre@0
|
299 per-group basis at "Administer >> Content management >> Ads >> Settings >>
|
|
pierre@0
|
300 Image ads".
|
|
pierre@0
|
301
|
|
pierre@0
|
302 -------------
|
|
pierre@0
|
303 Embedded ads:
|
|
pierre@0
|
304 -------------
|
|
pierre@0
|
305 Manually and automatically embedded ads can be configured at "Administer >>
|
|
pierre@0
|
306 Content management >> Ads >> Settings >> Embedded ads".
|
|
pierre@0
|
307
|
|
pierre@0
|
308
|
|
pierre@0
|
309 -----------
|
|
pierre@0
|
310 Statistics:
|
|
pierre@0
|
311 -----------
|
|
pierre@0
|
312 The ad module tracks how often each ad is viewed and clicked. The statistics
|
|
pierre@0
|
313 are tracked to an hourly granularity.
|
|
pierre@0
|
314
|
|
pierre@0
|
315 When an advertisement is first enabled, the statistics for 'This hour', 'Today',
|
|
pierre@0
|
316 'Last seven days', 'This month', 'This year' and 'All time' will all be the
|
|
pierre@0
|
317 same. When available, statistics will also include 'Last hour', 'Yesterday',
|
|
pierre@0
|
318 'Last month', and 'Last year'.
|
