|
pierre@0
|
1 ---------
|
|
pierre@0
|
2 Overview:
|
|
pierre@0
|
3 ---------
|
|
pierre@1
|
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@1
|
6 html ads. Ads can easily be displayed in themes, blocks, or embedded in site
|
|
pierre@1
|
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@1
|
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@1
|
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@1
|
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@1
|
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
|
|
piotre@7
|
55 advertisement' 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
|
|
sly@8
|
75 click Attach to upload the image. If you upload multiple images, the first
|
|
sly@8
|
76 image with "List" checked will be displayed. If no images have "List" checked
|
|
sly@8
|
77 then no images will be displayed.
|
|
pierre@0
|
78
|
|
pierre@0
|
79 HTML ads:
|
|
pierre@0
|
80 ---------
|
|
pierre@0
|
81 HTML ads allow you to easily define your own custom ad type by simply pasting
|
|
pierre@0
|
82 in a block of HTML code. At this time, however, the ad module is unable to
|
|
pierre@0
|
83 track when html ads are clicked.
|
|
pierre@0
|
84
|
|
pierre@0
|
85 Ad groups:
|
|
pierre@0
|
86 ----------
|
|
pierre@0
|
87 Ads can be organized into groups. For example, you may have a group called
|
|
pierre@1
|
88 "Text Ads" and another group called "Image Ads." You could then assign your
|
|
pierre@1
|
89 text ads to the "Text Ads" group, and your image ads to your "Image Ads"
|
|
pierre@1
|
90 groups. (This is not required, it is perfectly valid to include both image
|
|
pierre@1
|
91 ads and text ads in the same group.) When displaying ads, you typically tell
|
|
pierre@1
|
92 the ad module to display ads from a certain group and then the ad module
|
|
pierre@0
|
93 randomly selects an active ad from the specified group. Each ad can be a
|
|
pierre@0
|
94 member of any number of groups.
|
|
pierre@0
|
95
|
|
pierre@0
|
96 Ad status:
|
|
pierre@0
|
97 ----------
|
|
pierre@0
|
98 There are several states that an ad can exist in. An ad in the Pending state
|
|
pierre@0
|
99 is one that has recently been uploaded and is waiting to be approved by a
|
|
pierre@0
|
100 privileged user. An ad in the Approved state is one that has been approved
|
|
pierre@0
|
101 by a privileged user but is not actively being displayed, the ad could be
|
|
pierre@1
|
102 waiting on an autoactivation event. An ad in the Active state is being
|
|
pierre@1
|
103 actively displayed. An ad in the Offline state is approved but is currently
|
|
pierre@1
|
104 not being displayed. An ad in the Unpublished state means that the ad node
|
|
pierre@1
|
105 was unpublished so the ad is not any longer being displayed. An ad in the
|
|
pierre@1
|
106 Expired state is no longer being displayed. An ad in the Denied state means
|
|
pierre@0
|
107 it was not approved by the site administrator.
|
|
pierre@0
|
108
|
|
pierre@0
|
109 Scheduling:
|
|
pierre@0
|
110 -----------
|
|
pierre@0
|
111 If you put an ad into the Approved state and then enter a date and time in the
|
|
pierre@0
|
112 Automatically Activate Ad field, the ad will be automatically activated
|
|
pierre@0
|
113 on the date and time specified. This feature requires that cron be functional
|
|
pierre@0
|
114 on your website. If you enter a date and time in the Automatically Expire Ad
|
|
pierre@0
|
115 field, the ad will be automatically expired on the date and time specified.
|
|
pierre@0
|
116 Again, this feature requires that cron be functional on your website.
|
|
pierre@0
|
117
|
|
pierre@0
|
118 If you enter a number into the Maximum Impressions field, the ad will be
|
|
pierre@0
|
119 automatically expired once it has been displayed this number of times.
|
|
pierre@0
|
120
|
|
pierre@0
|
121 If you enter a number into the Maximum Clicks field, the ad will be
|
|
pierre@0
|
122 automatically expired once it has been clicked this number of times.
|
|
pierre@0
|
123
|
|
pierre@0
|
124 ---------------
|
|
pierre@0
|
125 Displaying ads:
|
|
pierre@0
|
126 ---------------
|
|
pierre@0
|
127 There are many ways to display ads with the ad module. The simplest way
|
|
pierre@0
|
128 is to enable one of the automatically generated ad blocks. It is also possible
|
|
pierre@0
|
129 to use the ad_embed module to automatically embed ads within your site content.
|
|
pierre@1
|
130 And you can even display ads from within the PHP of your theme or another
|
|
pierre@0
|
131 module.
|
|
pierre@0
|
132
|
|
pierre@0
|
133 ----------
|
|
pierre@0
|
134 Ad blocks:
|
|
pierre@0
|
135 ----------
|
|
pierre@0
|
136 The ad module automatically generates on ad block for every ad group that you
|
|
pierre@1
|
137 create. For example, if you visit "Administer >> Site building >> Blocks"
|
|
pierre@1
|
138 you will find a block named "ad group: default". If you enable this block,
|
|
pierre@0
|
139 it will display a random ad from all active ads in the default group.
|
|
pierre@0
|
140
|
|
pierre@0
|
141 You can optionally configure the block to display more than one ad at a time
|
|
pierre@0
|
142 by clicking the 'configure' link on the block administration page.
|
|
pierre@0
|
143
|
|
pierre@0
|
144 -------------
|
|
pierre@0
|
145 Embedded ads:
|
|
pierre@0
|
146 -------------
|
|
pierre@0
|
147 If you enabled the ad_embed module, it is possible to embed ads into your
|
|
pierre@0
|
148 site content. To configure the ad_embed module go to "Administer >> Content
|
|
pierre@1
|
149 Management >> Ads >> Settings >> Embedded ads".
|
|
pierre@0
|
150
|
|
pierre@1
|
151 If you wish to manually embed ads in your content, check the box next to
|
|
pierre@1
|
152 "Replace ad bracket tags" or "Replace ad comment tags". This will cause the
|
|
pierre@1
|
153 ad_embed module to replace embedded [[add]] or <!--ad--> tags respectively.
|
|
pierre@0
|
154 Instructions on how to specify specific ad groups or even specific ads and
|
|
pierre@1
|
155 how many ads to display at a time can be found by visiting "Administer >>
|
|
pierre@0
|
156 Help >> Embed".
|
|
pierre@0
|
157
|
|
pierre@0
|
158 If you wish to automatically embed ads in your content, configure this on a
|
|
pierre@0
|
159 per-content-type basis in the lower configuration section.
|
|
pierre@0
|
160 embeded ads".
|
|
pierre@0
|
161
|
|
pierre@0
|
162 ------------------------
|
|
pierre@0
|
163 Displaying ads from PHP:
|
|
pierre@0
|
164 ------------------------
|
|
pierre@0
|
165 To display an ad from within PHP code, make a call to the ad() function.
|
|
pierre@0
|
166 You can optionally specify an ad group, the number of ads to display, and
|
|
pierre@0
|
167 several other options. For example, to display one random ad from all ads
|
|
pierre@1
|
168 that have not been assigned to any group you don't have to pass in any
|
|
pierre@0
|
169 parameters:
|
|
pierre@0
|
170 <?php print ad(); ?>
|
|
pierre@0
|
171
|
|
pierre@0
|
172 To display two ads from all ads that have not been assigned to any group
|
|
pierre@0
|
173 you would execute the following code:
|
|
pierre@0
|
174 <?php print ad(0, 2); ?>
|
|
pierre@0
|
175
|
|
pierre@0
|
176 (The first parameter specifies the ad group to display ads from. By
|
|
pierre@0
|
177 specifying 0, we are telling the ad module to display ads that are not
|
|
pierre@0
|
178 assigned to any group. The second parameter specifies the number of ads
|
|
pierre@0
|
179 to display at one time.)
|
|
pierre@0
|
180
|
|
pierre@1
|
181 To randomly display an ad from a specific group of nids, for example with
|
|
pierre@0
|
182 the node ID 69 or 76, you would pass in the following parameters:
|
|
pierre@0
|
183 <?php print ad(NULL, 1, array('nids' => '69,76')); ?>
|
|
pierre@0
|
184
|
|
pierre@0
|
185 (When specifying specific nids, any specified ad group is ignored, so we
|
|
pierre@0
|
186 leave the first parameter as NULL. The second parameter causes only one
|
|
pierre@0
|
187 ad to be displayed at a time. And the third parameter is an array that
|
|
pierre@0
|
188 tells the ad module to randomly display either ad 69 or ad 76.)
|
|
pierre@0
|
189
|
|
pierre@0
|
190 To display and ad randomly selected from multiple groups you can simply
|
|
pierre@0
|
191 specify multiple groups separated by commas. For example, to display 3
|
|
pierre@0
|
192 ads from groups 24, 56 and 98 you would pass in the following parameters:
|
|
pierre@0
|
193 <?php print ad('24,56,98', 2); ?>
|
|
pierre@0
|
194
|
|
pierre@0
|
195 You can also specify how to display a given ad. Current display methods are
|
|
sly@3
|
196 'javascript', 'jquery', 'iframe', and 'raw'. When using the 'javascript',
|
|
sly@3
|
197 'jquery', and 'iframe' methods, ads will randomly change even when the Drupal
|
|
sly@3
|
198 pagecache is enabled. When using the 'raw' method, ads will only change when
|
|
sly@3
|
199 the Drupal pagecache is flushed.
|
|
sly@3
|
200
|
|
pierre@0
|
201 To force one ad with a tid of 76 to display using JavaScript you would pass
|
|
pierre@0
|
202 in the following parameters:
|
|
pierre@0
|
203 <?php print ad(76, 1, array('method' => 'javascript'));
|
|
pierre@0
|
204
|
|
pierre@0
|
205 To force two ads with a tid of 101 or 102 to display using the Raw method
|
|
pierre@0
|
206 you would pass in the following parameters:
|
|
pierre@0
|
207 <?php print ad('101,102', 76, array('method' => 'raw'));
|
|
pierre@0
|
208
|
|
pierre@0
|
209 ------------
|
|
pierre@0
|
210 Theming ads:
|
|
pierre@0
|
211 ------------
|
|
pierre@0
|
212 All ads are wrapped in the following tags:
|
|
pierre@0
|
213 <div class="advertisement" id="group-#"></div>
|
|
pierre@0
|
214
|
|
pierre@0
|
215 All ads are in the same "advertisement" class. Each ad group gets a unique
|
|
pierre@0
|
216 id. This makes it possible to create generic advertisement formatting as
|
|
pierre@0
|
217 well as specific advertisement formatting.
|
|
pierre@0
|
218
|
|
pierre@0
|
219 CSS Example 1:
|
|
pierre@0
|
220 --------------
|
|
pierre@0
|
221 This sample code can be added to your theme's custom style.css. It adds
|
|
pierre@0
|
222 padding to advertisements, wrapping them in a dashed border and giving
|
|
pierre@0
|
223 them a background color. It also adds the text "Advertisement:" above
|
|
pierre@0
|
224 the ad:
|
|
pierre@0
|
225
|
|
pierre@0
|
226 .advertisement {
|
|
pierre@0
|
227 padding: 5px;
|
|
pierre@0
|
228 border: dashed;
|
|
pierre@0
|
229 background-color: #ffd;
|
|
pierre@0
|
230 }
|
|
pierre@0
|
231
|
|
pierre@0
|
232 .advertisement:before {
|
|
pierre@0
|
233 content: "Advertisement:";
|
|
pierre@0
|
234 }
|
|
pierre@1
|
235
|
|
pierre@0
|
236 CSS Example 2:
|
|
pierre@0
|
237 --------------
|
|
pierre@0
|
238 Here is more sample code that could be added to your theme's custom
|
|
pierre@1
|
239 style.css. It will cause multiple image ads to be displayed horizontally
|
|
pierre@0
|
240 one beside the other (space permitting), rather than vertically one
|
|
pierre@0
|
241 below the other. The ads are aligned to the left side of the screen,
|
|
pierre@0
|
242 if you'd prefer them to be aligned to the right side of the screen change
|
|
pierre@0
|
243 the word "left" to "right" in the snippet:
|
|
pierre@0
|
244
|
|
pierre@0
|
245 .image-advertisement {
|
|
pierre@0
|
246 float: left;
|
|
pierre@0
|
247 padding: 3px;
|
|
pierre@0
|
248 }
|
|
pierre@0
|
249
|
|
pierre@0
|
250
|
|
pierre@0
|
251 -------------------
|
|
pierre@0
|
252 Ad module settings:
|
|
pierre@0
|
253 -------------------
|
|
pierre@0
|
254 The ad module and related modules provide a number of configuration options.
|
|
pierre@0
|
255
|
|
pierre@0
|
256 ----------------
|
|
pierre@0
|
257 Global settings:
|
|
pierre@0
|
258 ----------------
|
|
pierre@0
|
259 The ad module allows you to specify some global settings at "Administer >>
|
|
pierre@0
|
260 Content management >> Ads >> Settings >> Global settings".
|
|
pierre@0
|
261
|
|
pierre@0
|
262 Even if you do not plan to make any changes, you should visit this page at
|
|
pierre@0
|
263 least one time as the ad module will perform a series of sanity tests when
|
|
pierre@0
|
264 you visit this page, alerting you to any installation problems.
|
|
pierre@0
|
265
|
|
piotre@7
|
266 This page is divided into sections. The "Status" section validates that the
|
|
piotre@7
|
267 module can find the necessary scripts for serving advertisements. If
|
|
piotre@7
|
268 everything is properly installed, it will show you the automatically detected
|
|
piotre@7
|
269 paths to serve.ph and adserve.inc. If you instead see errors in this section,
|
|
piotre@7
|
270 review the directions in INSTALL.txt to get the ad module properly installed.
|
|
pierre@0
|
271
|
|
piotre@7
|
272 In the "General" section you can configure what happens when an advertisement
|
|
piotre@7
|
273 is clicked by setting the 'Click-through target'. You can also enable the
|
|
piotre@7
|
274 'nofollow' option to add 'rel="nofollow"' to all links generated by the ad
|
|
piotre@7
|
275 module. The 'Display type' allows you to alter how advertisements are
|
|
piotre@7
|
276 displayed, using JavaScript, jQuery, IFrames, or simply embedding raw HTML
|
|
piotre@7
|
277 into your page. Regardless of the 'Display type' the ad module will
|
|
piotre@7
|
278 accurately track how many times each advertisement is displayed and clicked.
|
|
piotre@7
|
279 Finally, the 'Validate URLs' option tells the module whether or not it
|
|
piotre@7
|
280 should use Drupal's built in URL validation logic to ensure that the
|
|
piotre@7
|
281 Destination URL for new advertisements is a valid URL.
|
|
pierre@0
|
282
|
|
piotre@7
|
283 In the "Search" section there are two options which are enabled by default.
|
|
piotre@7
|
284 The first causes advertisements to be removed from local searches when using
|
|
piotre@7
|
285 Drupal's built in search module. The second causes advertisements to be
|
|
piotre@7
|
286 removed from remote search engines by adding the "noindex" meta tag to all
|
|
piotre@7
|
287 pages where node ads are displayed. If you publish advertisement nodes to
|
|
piotre@7
|
288 the front page mixed in with other content types, you should probably
|
|
piotre@7
|
289 disable the "Remove ads from remote search engines" option as otherwise
|
|
piotre@7
|
290 you may find that your entire website is removed from all search engines.
|
|
piotre@7
|
291 (Note that displaying ads on the front page is not the same as displaying
|
|
piotre@7
|
292 an ad node on the front page. The 'noindex' tag is not added when ads are
|
|
piotre@7
|
293 displayed via blocks, direct calls to ad(), using views, or when embedded
|
|
piotre@7
|
294 with the ad_embed module.)
|
|
pierre@0
|
295
|
|
piotre@7
|
296 The "IFrame" section allows you to configure the size of IFrames and other
|
|
piotre@7
|
297 related settings.
|
|
pierre@0
|
298
|
|
piotre@7
|
299 The "Cache" section provides access to the configuration options for any
|
|
piotre@7
|
300 enabled ad caching modules. By default the ad module comes with the
|
|
piotre@7
|
301 file cache which allows advertisements to be quickly and efficiently displayed
|
|
piotre@7
|
302 from a cache file without bootstrapping Drupal. If your website utilizes
|
|
piotre@7
|
303 multiple web servers, you should instead download the ad_memcache module
|
|
piotre@7
|
304 which allows you to serve advertisements from a shared memcache instance.
|
|
pierre@0
|
305
|
|
pierre@0
|
306 ---------
|
|
pierre@0
|
307 Text ads:
|
|
pierre@0
|
308 ---------
|
|
pierre@0
|
309 The ad_text module allows you to specify some minimum and maximum lengths for
|
|
pierre@0
|
310 text ads at "Administer >> Content management >> Ads >> Settings >> Text ads".
|
|
pierre@0
|
311
|
|
pierre@0
|
312 ----------
|
|
pierre@0
|
313 Image ads:
|
|
pierre@0
|
314 ----------
|
|
pierre@1
|
315 The ad_image module allows you to specify some image constraints on a
|
|
pierre@1
|
316 per-group basis at "Administer >> Content management >> Ads >> Settings >>
|
|
pierre@0
|
317 Image ads".
|
|
pierre@0
|
318
|
|
pierre@0
|
319 -------------
|
|
pierre@0
|
320 Embedded ads:
|
|
pierre@0
|
321 -------------
|
|
pierre@1
|
322 Manually and automatically embedded ads can be configured at "Administer >>
|
|
pierre@0
|
323 Content management >> Ads >> Settings >> Embedded ads".
|
|
pierre@0
|
324
|
|
pierre@0
|
325
|
|
pierre@0
|
326 -----------
|
|
pierre@0
|
327 Statistics:
|
|
pierre@0
|
328 -----------
|
|
pierre@0
|
329 The ad module tracks how often each ad is viewed and clicked. The statistics
|
|
pierre@0
|
330 are tracked to an hourly granularity.
|
|
pierre@0
|
331
|
|
pierre@0
|
332 When an advertisement is first enabled, the statistics for 'This hour', 'Today',
|
|
pierre@1
|
333 'Last seven days', 'This month', 'This year' and 'All time' will all be the
|
|
pierre@0
|
334 same. When available, statistics will also include 'Last hour', 'Yesterday',
|
|
pierre@0
|
335 'Last month', and 'Last year'.
|
|
sly@3
|
336
|
|
sly@3
|
337 When displaying advertisements using the JavaScript, jQuery, and IFrame methods
|
|
sly@3
|
338 impressions are tracked each time the script is loaded. When displaying
|
|
sly@3
|
339 advertisements using the Raw method, impressions are tracked through the use
|
|
sly@3
|
340 of a hidden 1x1 pixel image that is displayed along with each advertisement.
|
|
sly@3
|
341
|
|
sly@3
|
342 The click_filter module can be enabled to filter out the following invalid
|
|
sly@3
|
343 clicks:
|
|
sly@3
|
344 * Duplicate clicks from the same IP address
|
|
sly@3
|
345 * Clicks from the owner of the advertisement
|
|
sly@3
|
346 * Clicks from any user with 'filter clicks' permissions.
|
|
sly@3
|
347 * Clicks from any users in which the word "bot" is contained in their
|
|
sly@3
|
348 HTTP_USER_AGENT
|
|
sly@3
|
349
|
|
sly@3
|
350 This means that when the click_filter module is enabled, all clicks by UID 1
|
|
sly@3
|
351 will be filtered because Drupal will automatically assign all permissions to
|
|
sly@3
|
352 this user, including the 'filter clicks' permisison. The click_filter module
|
|
sly@3
|
353 currently has no configuration options beyond the 'filter clicks' permission.
|
