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