Basic Ads

Basic Ads

This module was developed with the help of Claude AI (from Anthropic).

Provides ad management with placements, scheduling, and display blocks. Includes impression and click tracking with a statistics dashboard, and automatically unpublishes expired ads via cron.

Submit bug reports and feature suggestions, or track changes in the issue queue.

Requirements

This module requires no modules outside of Drupal core.

It depends on the following core modules: Node, Taxonomy, Datetime, Image, Text, Link, Views, and Block.

Installation

Install as you would normally install a contributed Drupal module. For further information, see Installing Drupal Modules.

On installation the module will automatically create:

• A "Basic Ad Placement" taxonomy vocabulary with default terms (Header, Sidebar, Footer, Content Top, Content Bottom)
• A "Basic Ad" content type with image, link, placement, scheduling, and weight fields
• A "Basic Ads" View with a block display for placement-based rendering
• Database tables for impression and click tracking

Configuration

1. Go to Administration > Structure > Taxonomy > Basic Ad Placement to add, edit, or delete placement terms.
2. Go to Administration > Content > Add Content > Basic Ad to create an advertisement. Assign one or more placement terms.
3. Go to Structure > Block Layout and place a "Basic Ad block (by placement)" block in the region of your choice. Select a placement term to filter which ads display, and choose how many ads to show in the "Number of ads to display" field (1–50, default 1). The placed block's admin label is auto-set to Basic Ad: {placement name} so you can tell placements apart at a glance on the Block Layout page.
4. Go to Administration > Configuration > System > Basic Ads Settings to exclude roles from ad tracking.
5. Go to Administration > Reports > Basic Ad Reporting to view ad statistics including impressions, clicks, and CTR.

Weighting and rotation

Each ad has a Weight field (range −50 to +50, default 0). Lower weight means higher priority — standard Drupal weight semantics. Each 10 units of weight roughly halves or doubles an ad's relative odds of being picked when there are more eligible ads than the block's "Number of ads to display" setting. Equal weights give a uniform random selection. The selection is cached for 60 seconds and rotates to a new random subset in the next minute, so different ads surface over time without breaking page caches.

Scheduling

• Leave Start Date empty for immediate display, or set a future date.
• Leave End Date empty for no expiration, or set an end date.
• Expired ads are automatically unpublished by cron.

Tracking and privacy

• Impressions are tracked client-side via JavaScript when ads render in a placement block.
• Clicks are tracked server-side through a redirect endpoint.
• IP addresses are automatically anonymized (IPv4 last octet zeroed, IPv6 truncated to 48 bits).
• Old tracking data (older than 1 year) is automatically purged via cron.
• You can exclude specific roles (e.g. authenticated editors) from impression and click tracking via Configuration > System > Basic Ads Settings.

Troubleshooting

Ads not displaying:

• Check that ads are published.
• Verify the ad placement term matches the block configuration.
• Check start/end dates are correct.
• Ensure the block is placed in a visible region.
• Clear Drupal cache.

Impressions not tracking:

• Check the browser network tab for /ad/view/ requests to verify the tracking library is loading.
• Ensure the ad has a placement (tracking only fires when a placement is present).
• Check that the current user's role is not excluded in Configuration > System > Basic Ads Settings.

Schedule not working:

• Ensure cron is running regularly for expired ad cleanup.
• Check your site's timezone settings.
• Clear cache after changing dates.

Maintainers

• charlie59 - charlie59