pierre@0: --------- pierre@0: Overview: pierre@0: --------- pierre@1: The ad module is a powerful advertising system for Drupal-powered websites. It pierre@0: supports the random display and tracking of graphical (banner), text and raw pierre@1: html ads. Ads can easily be displayed in themes, blocks, or embedded in site pierre@1: content. The module records comprehensive statistics about when and how often pierre@0: ads are viewed and clicked, including a plug-in module for generating graphical pierre@1: time-based reports. Ads can be assigned to multiple owners, each of which can pierre@0: be assigned their own set of permissions. Installation is simple by design. An pierre@1: API is provided allowing the development of additional functionality and pierre@0: integration with other Drupal modules. pierre@0: pierre@0: Features: pierre@0: * auto-generated ad blocks supporting a configurable number of ads pierre@0: * automatically or manually embed ads into site content pierre@1: * collection of comprehensive statistics allowing time-based reporting and pierre@0: analysis pierre@0: * tracking of when and where ads are clicked, by which user and which IP pierre@0: * advertisements can have multiple owners pierre@0: * granular per-advertisement/per-owner permissions system pierre@0: * activation/expiration scheduling based on time, clicks or impressions pierre@0: * an ad_image plug-in for image (aka banner) ads pierre@0: * an ad_text plug-in for simple text ads pierre@0: * an ad_html plug-in for raw html ads pierre@1: * an externally maintained ad_geoip plug-in provides support for pierre@0: geotargeting ads pierre@0: * an ad_report plug-in for basic graphical reports pierre@0: * an ad_notify plug-in for scheduling automatic email notifications pierre@0: * an ad_remote plug-in for hosting ads on remote (non-Drupal) websites pierre@0: * an administrative statistics overview page pierre@0: * support for any number of configurable ad groups, utilizing Drupal's pierre@0: taxonomy (category) subsystem pierre@0: * display ads based on node ids (nids) or taxonomy terms (categories) pierre@0: * file-based caching for improved performance pierre@0: * memcache-based caching for improved performance pierre@0: * support for external caching methods pierre@0: * MySQL and PostgreSQL support pierre@0: pierre@0: pierre@0: ------ pierre@0: Usage: pierre@0: ------ pierre@0: Installation and requirements information can be found within the INSTALL.txt pierre@0: file included with this module. pierre@0: pierre@0: pierre@0: ------------- pierre@0: Creating ads: pierre@0: ------------- pierre@0: Once the ad module is properly installed an enabled, you can create pierre@0: advertisements by visiting 'create content' on your website and choosing pierre@0: 'advertisement' as the content type. If you have enabled multiple ad type pierre@0: modules, you can select one of them from the resulting menu, such as 'image piotre@7: advertisement' or 'text advertisement'. pierre@0: pierre@0: Text ads: pierre@0: --------- pierre@0: Text ads are very simple, requiring that you fill out only three fields of pierre@0: information. First, you need to specify the Destination URL where you want pierre@0: people to be redirected when they click on your text ad. Second, you enter pierre@0: the a header for your ad. The header will be linked to the Destination URL. pierre@0: Finally, you need to specify the body of your ad. pierre@0: pierre@0: Image ads: pierre@0: ---------- pierre@0: Image ads or only slightly more complicated than text ads. They depend on pierre@0: the drupal core Upload module for managing the actual images. As with text pierre@0: ads, you first need to specify the Destination URL where you want people to pierre@0: be redirected when they click on your image ad. Second, you can optoinally pierre@0: enter some Mouseover text. If you enter text in the mouseover field this pierre@0: text will be displayed when people hover their mouse pointer over the pierre@0: advertisement. Finally, you need to scroll down to the File attachements pierre@0: section of the page and click the Browser button to select your image, then sly@8: click Attach to upload the image. If you upload multiple images, the first sly@8: image with "List" checked will be displayed. If no images have "List" checked sly@8: then no images will be displayed. pierre@0: pierre@0: HTML ads: pierre@0: --------- pierre@0: HTML ads allow you to easily define your own custom ad type by simply pasting pierre@0: in a block of HTML code. At this time, however, the ad module is unable to pierre@0: track when html ads are clicked. pierre@0: pierre@0: Ad groups: pierre@0: ---------- pierre@0: Ads can be organized into groups. For example, you may have a group called pierre@1: "Text Ads" and another group called "Image Ads." You could then assign your pierre@1: text ads to the "Text Ads" group, and your image ads to your "Image Ads" pierre@1: groups. (This is not required, it is perfectly valid to include both image pierre@1: ads and text ads in the same group.) When displaying ads, you typically tell pierre@1: the ad module to display ads from a certain group and then the ad module pierre@0: randomly selects an active ad from the specified group. Each ad can be a pierre@0: member of any number of groups. pierre@0: pierre@0: Ad status: pierre@0: ---------- pierre@0: There are several states that an ad can exist in. An ad in the Pending state pierre@0: is one that has recently been uploaded and is waiting to be approved by a pierre@0: privileged user. An ad in the Approved state is one that has been approved pierre@0: by a privileged user but is not actively being displayed, the ad could be pierre@1: waiting on an autoactivation event. An ad in the Active state is being pierre@1: actively displayed. An ad in the Offline state is approved but is currently pierre@1: not being displayed. An ad in the Unpublished state means that the ad node pierre@1: was unpublished so the ad is not any longer being displayed. An ad in the pierre@1: Expired state is no longer being displayed. An ad in the Denied state means pierre@0: it was not approved by the site administrator. pierre@0: pierre@0: Scheduling: pierre@0: ----------- pierre@0: If you put an ad into the Approved state and then enter a date and time in the pierre@0: Automatically Activate Ad field, the ad will be automatically activated pierre@0: on the date and time specified. This feature requires that cron be functional pierre@0: on your website. If you enter a date and time in the Automatically Expire Ad pierre@0: field, the ad will be automatically expired on the date and time specified. pierre@0: Again, this feature requires that cron be functional on your website. pierre@0: pierre@0: If you enter a number into the Maximum Impressions field, the ad will be pierre@0: automatically expired once it has been displayed this number of times. pierre@0: pierre@0: If you enter a number into the Maximum Clicks field, the ad will be pierre@0: automatically expired once it has been clicked this number of times. pierre@0: pierre@0: --------------- pierre@0: Displaying ads: pierre@0: --------------- pierre@0: There are many ways to display ads with the ad module. The simplest way pierre@0: is to enable one of the automatically generated ad blocks. It is also possible pierre@0: to use the ad_embed module to automatically embed ads within your site content. pierre@1: And you can even display ads from within the PHP of your theme or another pierre@0: module. pierre@0: pierre@0: ---------- pierre@0: Ad blocks: pierre@0: ---------- pierre@0: The ad module automatically generates on ad block for every ad group that you pierre@1: create. For example, if you visit "Administer >> Site building >> Blocks" pierre@1: you will find a block named "ad group: default". If you enable this block, pierre@0: it will display a random ad from all active ads in the default group. pierre@0: pierre@0: You can optionally configure the block to display more than one ad at a time pierre@0: by clicking the 'configure' link on the block administration page. pierre@0: pierre@0: ------------- pierre@0: Embedded ads: pierre@0: ------------- pierre@0: If you enabled the ad_embed module, it is possible to embed ads into your pierre@0: site content. To configure the ad_embed module go to "Administer >> Content pierre@1: Management >> Ads >> Settings >> Embedded ads". pierre@0: pierre@1: If you wish to manually embed ads in your content, check the box next to pierre@1: "Replace ad bracket tags" or "Replace ad comment tags". This will cause the pierre@1: ad_embed module to replace embedded [[add]] or tags respectively. pierre@0: Instructions on how to specify specific ad groups or even specific ads and pierre@1: how many ads to display at a time can be found by visiting "Administer >> pierre@0: Help >> Embed". pierre@0: pierre@0: If you wish to automatically embed ads in your content, configure this on a pierre@0: per-content-type basis in the lower configuration section. pierre@0: embeded ads". pierre@0: pierre@0: ------------------------ pierre@0: Displaying ads from PHP: pierre@0: ------------------------ pierre@0: To display an ad from within PHP code, make a call to the ad() function. pierre@0: You can optionally specify an ad group, the number of ads to display, and pierre@0: several other options. For example, to display one random ad from all ads pierre@1: that have not been assigned to any group you don't have to pass in any pierre@0: parameters: pierre@0: pierre@0: pierre@0: To display two ads from all ads that have not been assigned to any group pierre@0: you would execute the following code: pierre@0: pierre@0: pierre@0: (The first parameter specifies the ad group to display ads from. By pierre@0: specifying 0, we are telling the ad module to display ads that are not pierre@0: assigned to any group. The second parameter specifies the number of ads pierre@0: to display at one time.) pierre@0: pierre@1: To randomly display an ad from a specific group of nids, for example with pierre@0: the node ID 69 or 76, you would pass in the following parameters: pierre@0: '69,76')); ?> pierre@0: pierre@0: (When specifying specific nids, any specified ad group is ignored, so we pierre@0: leave the first parameter as NULL. The second parameter causes only one pierre@0: ad to be displayed at a time. And the third parameter is an array that pierre@0: tells the ad module to randomly display either ad 69 or ad 76.) pierre@0: pierre@0: To display and ad randomly selected from multiple groups you can simply pierre@0: specify multiple groups separated by commas. For example, to display 3 pierre@0: ads from groups 24, 56 and 98 you would pass in the following parameters: pierre@0: pierre@0: pierre@0: You can also specify how to display a given ad. Current display methods are sly@3: 'javascript', 'jquery', 'iframe', and 'raw'. When using the 'javascript', sly@3: 'jquery', and 'iframe' methods, ads will randomly change even when the Drupal sly@3: pagecache is enabled. When using the 'raw' method, ads will only change when sly@3: the Drupal pagecache is flushed. sly@3: pierre@0: To force one ad with a tid of 76 to display using JavaScript you would pass pierre@0: in the following parameters: pierre@0: 'javascript')); pierre@0: pierre@0: To force two ads with a tid of 101 or 102 to display using the Raw method pierre@0: you would pass in the following parameters: pierre@0: 'raw')); pierre@0: pierre@0: ------------ pierre@0: Theming ads: pierre@0: ------------ pierre@0: All ads are wrapped in the following tags: pierre@0: pierre@0: pierre@0: All ads are in the same "advertisement" class. Each ad group gets a unique pierre@0: id. This makes it possible to create generic advertisement formatting as pierre@0: well as specific advertisement formatting. pierre@0: pierre@0: CSS Example 1: pierre@0: -------------- pierre@0: This sample code can be added to your theme's custom style.css. It adds pierre@0: padding to advertisements, wrapping them in a dashed border and giving pierre@0: them a background color. It also adds the text "Advertisement:" above pierre@0: the ad: pierre@0: pierre@0: .advertisement { pierre@0: padding: 5px; pierre@0: border: dashed; pierre@0: background-color: #ffd; pierre@0: } pierre@0: pierre@0: .advertisement:before { pierre@0: content: "Advertisement:"; pierre@0: } pierre@1: pierre@0: CSS Example 2: pierre@0: -------------- pierre@0: Here is more sample code that could be added to your theme's custom pierre@1: style.css. It will cause multiple image ads to be displayed horizontally pierre@0: one beside the other (space permitting), rather than vertically one pierre@0: below the other. The ads are aligned to the left side of the screen, pierre@0: if you'd prefer them to be aligned to the right side of the screen change pierre@0: the word "left" to "right" in the snippet: pierre@0: pierre@0: .image-advertisement { pierre@0: float: left; pierre@0: padding: 3px; pierre@0: } pierre@0: pierre@0: pierre@0: ------------------- pierre@0: Ad module settings: pierre@0: ------------------- pierre@0: The ad module and related modules provide a number of configuration options. pierre@0: pierre@0: ---------------- pierre@0: Global settings: pierre@0: ---------------- pierre@0: The ad module allows you to specify some global settings at "Administer >> pierre@0: Content management >> Ads >> Settings >> Global settings". pierre@0: pierre@0: Even if you do not plan to make any changes, you should visit this page at pierre@0: least one time as the ad module will perform a series of sanity tests when pierre@0: you visit this page, alerting you to any installation problems. pierre@0: piotre@7: This page is divided into sections. The "Status" section validates that the piotre@7: module can find the necessary scripts for serving advertisements. If piotre@7: everything is properly installed, it will show you the automatically detected piotre@7: paths to serve.ph and adserve.inc. If you instead see errors in this section, piotre@7: review the directions in INSTALL.txt to get the ad module properly installed. pierre@0: piotre@7: In the "General" section you can configure what happens when an advertisement piotre@7: is clicked by setting the 'Click-through target'. You can also enable the piotre@7: 'nofollow' option to add 'rel="nofollow"' to all links generated by the ad piotre@7: module. The 'Display type' allows you to alter how advertisements are piotre@7: displayed, using JavaScript, jQuery, IFrames, or simply embedding raw HTML piotre@7: into your page. Regardless of the 'Display type' the ad module will piotre@7: accurately track how many times each advertisement is displayed and clicked. piotre@7: Finally, the 'Validate URLs' option tells the module whether or not it piotre@7: should use Drupal's built in URL validation logic to ensure that the piotre@7: Destination URL for new advertisements is a valid URL. pierre@0: piotre@7: In the "Search" section there are two options which are enabled by default. piotre@7: The first causes advertisements to be removed from local searches when using piotre@7: Drupal's built in search module. The second causes advertisements to be piotre@7: removed from remote search engines by adding the "noindex" meta tag to all piotre@7: pages where node ads are displayed. If you publish advertisement nodes to piotre@7: the front page mixed in with other content types, you should probably piotre@7: disable the "Remove ads from remote search engines" option as otherwise piotre@7: you may find that your entire website is removed from all search engines. piotre@7: (Note that displaying ads on the front page is not the same as displaying piotre@7: an ad node on the front page. The 'noindex' tag is not added when ads are piotre@7: displayed via blocks, direct calls to ad(), using views, or when embedded piotre@7: with the ad_embed module.) pierre@0: piotre@7: The "IFrame" section allows you to configure the size of IFrames and other piotre@7: related settings. pierre@0: piotre@7: The "Cache" section provides access to the configuration options for any piotre@7: enabled ad caching modules. By default the ad module comes with the piotre@7: file cache which allows advertisements to be quickly and efficiently displayed piotre@7: from a cache file without bootstrapping Drupal. If your website utilizes piotre@7: multiple web servers, you should instead download the ad_memcache module piotre@7: which allows you to serve advertisements from a shared memcache instance. pierre@0: pierre@0: --------- pierre@0: Text ads: pierre@0: --------- pierre@0: The ad_text module allows you to specify some minimum and maximum lengths for pierre@0: text ads at "Administer >> Content management >> Ads >> Settings >> Text ads". pierre@0: pierre@0: ---------- pierre@0: Image ads: pierre@0: ---------- pierre@1: The ad_image module allows you to specify some image constraints on a pierre@1: per-group basis at "Administer >> Content management >> Ads >> Settings >> pierre@0: Image ads". pierre@0: pierre@0: ------------- pierre@0: Embedded ads: pierre@0: ------------- pierre@1: Manually and automatically embedded ads can be configured at "Administer >> pierre@0: Content management >> Ads >> Settings >> Embedded ads". pierre@0: pierre@0: pierre@0: ----------- pierre@0: Statistics: pierre@0: ----------- pierre@0: The ad module tracks how often each ad is viewed and clicked. The statistics pierre@0: are tracked to an hourly granularity. pierre@0: pierre@0: When an advertisement is first enabled, the statistics for 'This hour', 'Today', pierre@1: 'Last seven days', 'This month', 'This year' and 'All time' will all be the pierre@0: same. When available, statistics will also include 'Last hour', 'Yesterday', pierre@0: 'Last month', and 'Last year'. sly@3: sly@3: When displaying advertisements using the JavaScript, jQuery, and IFrame methods sly@3: impressions are tracked each time the script is loaded. When displaying sly@3: advertisements using the Raw method, impressions are tracked through the use sly@3: of a hidden 1x1 pixel image that is displayed along with each advertisement. sly@3: sly@3: The click_filter module can be enabled to filter out the following invalid sly@3: clicks: sly@3: * Duplicate clicks from the same IP address sly@3: * Clicks from the owner of the advertisement sly@3: * Clicks from any user with 'filter clicks' permissions. sly@3: * Clicks from any users in which the word "bot" is contained in their sly@3: HTTP_USER_AGENT sly@3: sly@3: This means that when the click_filter module is enabled, all clicks by UID 1 sly@3: will be filtered because Drupal will automatically assign all permissions to sly@3: this user, including the 'filter clicks' permisison. The click_filter module sly@3: currently has no configuration options beyond the 'filter clicks' permission.