Ad Management

Ralkage

Ad Management

A comprehensive ad management system for Flarum forums. Supports image banners, HTML/JS ads, and Google AdSense with zones, analytics, an approval workflow, and a user self-service portal.

Features

Ad Zones — Named positions (header, below_header, between_posts, sidebar, above_footer, footer, custom) with optional dimension constraints
Ad Types — Image banners, raw HTML/JS, and Google AdSense units
Rotation — One random ad per zone per page load (randomized each visit)
Analytics — Per-ad impression and click tracking with daily breakdowns and CTR
Approval Workflow — User-submitted ads queue for admin review before going live; optional approval for image changes
Email Notifications — Expiration reminders and performance reports via cron, with customizable templates
Admin Notifications — Instant email alert when a user submits an ad for review
Rate Limiting — Anti-fraud protection on click and impression tracking endpoints
Group Visibility — Show ads only to specific member groups; hide ads for premium groups
Post Shortcodes — Embed any zone inline in discussion posts: {myadvertisements[zone_name]}
Image Processing — Automatic resizing to zone dimensions; optional compression via PHP GD or reSmush.it API
GDPR Compliance — Purge old click records with the built-in console command

Screenshots:

Requirements

Flarum ^1.8
PHP ^8.0 with GD extension (for image resizing/compression)
PHP curl extension (optional, for reSmush.it API compression)

Installation

composer require ralkage/flarum-ext-ad-management

Then enable it in your Flarum admin panel under Extensions.

Quick Start

Go to Admin → Ad Management → Zones and create a zone (or use a built-in default zone).
Go to Advertisements and create your first ad.

Set up the cron job for email notifications:

   0 8 * * * php /var/www/flarum ad-management:send-notifications >> /dev/null 2>&1

(Optional) Grant the Submit Advertisements permission to allow forum members to submit ads for review.

Console Commands

Command	Description
`php flarum ad-management:send-notifications`	Send expiration reminders and performance reports
`php flarum ad-management:purge-clicks [days]`	Delete click records older than N days (default: 90) for GDPR compliance

Documentation

See ADMIN_GUIDE.md for full configuration and usage documentation.

License

MIT

Capybara

Ralkage is releasing extensions at lightning speed 🏎

Heavenly

Ralkage

I have a few suggestions/issues regarding the user interface:

Dark Mode Incompatibility:
The advertisement container (specifically the background and the "SPONSORED" label area) does not seem to sync with the FoF Night Mode extension. When the site is in Dark Mode, the ad area remains white or uses light-themed styling, which creates a harsh contrast and doesn't blend well with the dark theme. It would be great if the ad container's background and text colors could automatically adapt to Flarum's dark mode variables.

Option to Toggle/Remove "SPONSORED" Label:
Currently, there is no option in the admin settings to hide or customize the "SPONSORED" text. For a cleaner look, could you please add a setting to toggle this label on or off? Or perhaps provide a field to change the text to something else?

Responsive Layout:
The ad zone seems to be restricted by fixed width/height containers, making it difficult for ads to appear "full width" on mobile devices. An option for a truly responsive container would be highly appreciated.

Thank you for your hard work on this extension, Love it!

luceos

Ralkage out of curiosity, are these vibe coded?

Ralkage

luceos 50/50. I still review, refactor, and test everything that I can test before releasing.

It was a bit rough at first since Claude didn’t fully understand how to build a Flarum extension, but after a few prompts I got it on track.

Oh and the Flarum CLI was clutch for the 2.x conversion. It had a few hiccups, but it handled most of the heavy lifting 💪

Ralkage

1.1.0

What's New

Dark Mode Support

Ad zone backgrounds, borders, and the "Sponsored" label now use Flarum CSS custom properties (var(--control-bg), var(--body-bg), var(--muted-color)), adapting automatically to FoF Night Mode and any other theme.

Responsive Ads

Image ad banners are now full-width on mobile viewports, removing the fixed-width clipping on small screens.

Ad-Free Permission

Replaced the "Hide Ads for Groups" text field (which required knowing internal group IDs) with a proper Flarum permission: Ad-Free (hide all ads). Grant it to any group (e.g. Premium subscribers) via Admin → Permissions. Works correctly for admin accounts too.

Upgrade Notes

The Hide Ads for Groups setting has been removed. Re-configure ad suppression via the new permission in the Permissions panel.

Thanks @Heavenly for the feedback!! 😁 (2.x version coming out soon)

andrewjs18

hi @Ralkage - thanks for this!

I haven't had a chance to test this yet...I really need to set up a 2.X demo flarum install...

what happens when you put more than 1 ad/banner in the same section? can you stack multiple ads in the same section? since flarum is an SPA, how will the ads 'rotate'?

for example, on my current mybb forum, I have about 5-7 header ads in the same location that 'rotate' on each page refresh. here's my site URL for a live example: https://damnfineshave.com

qishou

Ralkage Can you accept adding zh-CN (Simplified Chinese) translation?

Ralkage

andrewjs18 great questions!

Multiple ads in the same zone = fully supported. You can assign as many ads as you want to any zone.

Display mode - as of v1.2.0 (and v2.0.0-beta.8), each zone now has a configurable display mode:

Rotate (default): Shows one random ad at a time. Since Flarum is an SPA, ads re-randomize on every page navigation; so clicking into a discussion, going back to the index, etc. gives a different ad each time, just like your MyBB setup with the 5–7 rotating header banners.

Stack All: Shows every ad in the zone at once, stacked vertically. Useful if you want all sponsors visible simultaneously.
You can configure the mode per-zone from Admin > Ad Management > Ad Zones > Edit.

Let me know if you have any other questions once you get a chance to test it!

qishou sure!

Ralkage

1.2.0

What's New

Ad rotation on SPA navigation: Ads now rotate on every page navigation within Flarum's SPA, not just on hard refresh. If you have multiple ads in a zone, users see a different one each time they navigate.
Display mode per zone (Rotate / Stack All): Each ad zone now has a configurable display mode:
- Rotate (default): Shows one random ad at a time, rotating on each page navigation
- Stack All: Shows every ad in the zone simultaneously

Heavenly

andrewjs18 That's fast👍 You're carrying the whole ecosystem with these updates.

KBExit

I'm having issues with this extension on 2.0. It either says "Oops something went wrong..." or it says I don't have permissions to do anything.
No logs are generated.

Edit: maybe it's a problem with compatibility with Realtime / Horizon for this extension? When this extension is installed, it crashes those 2 services with fatal. On other sites without this extension, the sites work as intended and server logs are clean.

Edit #2: removing the extension from the problem site and rebooting. Seeing if it persists.

Edit #3: problems are all gone with this extension uninstalled.

Flarum Info:

Flarum core: 2.0.0-beta.8
PHP version: CLI: 8.3.30, Web: 8.3.30
PHP memory limit: CLI: 768M, Web: 768M
MySQL version: 8.0.44
Loaded extensions: Core, date, libxml, openssl, pcre, sqlite3, zlib, ctype, curl, dom, fileinfo, filter, hash, iconv, json, mbstring, SPL, session, PDO, pdo_sqlite, standard, posix, random, Reflection, Phar, SimpleXML, tokenizer, xml, xmlreader, xmlwriter, mysqlnd, apache2handler, exif, gd, gmp, intl, pcntl, pdo_mysql, redis, sockets, sodium, zip, Zend OPcache
+--------------------------+-----------------+--------+-------+
| Flarum Extensions        |                 |        |       |
+--------------------------+-----------------+--------+-------+
| ID                       | Version         | Commit | Notes |
+--------------------------+-----------------+--------+-------+
| fof-upload               | 2.0.0-beta.3    |        |       |
| fof-pages                | 2.0.0-beta.2    |        |       |
| fof-linguist             | 2.0.0-beta.1    |        |       |
| fof-horizon              | v2.0.0-beta.8   |        |       |
| fof-drafts               | 2.0.0-beta.6    |        |       |
| flarum-tags              | v2.0.0-beta.8   |        |       |
| flarum-statistics        | v2.0.0-beta.8   |        |       |
| flarum-realtime          | v2.0.0-beta.8.1 |        |       |
| flarum-markdown          | v2.0.0-beta.8   |        |       |
| flarum-lang-english      | v2.0.0-beta.8   |        |       |
| flarum-extension-manager | v2.0.0-beta.8   |        |       |
| flarum-emoji             | v2.0.0-beta.8   |        |       |
| flarum-bbcode            | v2.0.0-beta.8   |        |       |
+--------------------------+-----------------+--------+-------+
Base URL: https://kbexit.vet
Installation path: /var/www/html/public
Queue driver: redis
Session driver: redis (Code override. Configured to file)
Scheduler status: Active
Mail driver: smtp
Debug mode: off

Ralkage

KBExit just pushed a new pre-release for v2.0.0-beta.8, see if the update fixes the issues you mentioned 🙂

Fixes

Fix crash with fof/horizon and flarum/realtime on Flarum 2.0
Fix advertisement list sorting (use Flarum 2.0 SortColumn API)
Fix active ads endpoint for Flarum 2.x (?filter[active]=1)
Fix guest user SQL error in permission check
Fix Mithril fragment key conflict (use contentItems() ItemList API)
Use hasPermission() for ad-free permission to respect admin inheritance