Extension:ShoutWiki Ads

MediaWiki extensions manual

ShoutWiki Ads Release status: stable
Implementation	User interface
Description	Displays Google AdSense ads on skins
Author(s)	Jack Phoenix
Latest version	0.4.8
MediaWiki	1.43.0+
License	Public domain
Download	Download extension Git [?]: Download Git master browse repository (Phabricator · GitHub) commit history repository contributors (GitHub) code review
Example	ShoutWiki
Parameters $wgAdConfig
Hooks used AuroraLeftSidebar BeforePageDisplay DuskAfterToolbox GamesSideBox HomeAfterEverything MetrolookAfterToolbox MetrolookRightPanel MirageGetRightRailModules MonacoFooter MonacoSetupSkinUserCss MonacoSidebar NimbusLeftSide QuartzSidebarWidgetAdvertiser QuartzSidebarWidgets RefreshedFooter RefreshedInSidebar SiteNoticeAfter SkinAfterBottomScripts SkinAfterContent SkinAfterPortlet TruglassInContent
Public wikis using	942 (Ranked 280th)
Translate the ShoutWiki Ads extension if it is available at translatewiki.net
Issues	Open tasks · Report a bug

ShoutWiki Ads extension displays Google AdSense ads on skins without requiring a wiki system administrator to manually modify any skin files, thus making upgrades smoother. It supports a wide array of skins, see below for a full list.

The extension will not display ads

• when ads are disabled ($wgAdConfig['enabled'] = false;)
• on the login page (Special:UserLogin)
• on namespaces where ads are not enabled
• for users in the staff user group
• if the wiki is in a language that is not supported by Google AdSense

Additionally, the ad HTML is always given the noprint class to hide the ads in printable view. Note that sadly, as of MediaWiki 1.39, support for this CSS class is a skin-specific feature and some skins do not unfortunately implement it properly; most do, though.

Despite the name, this extension isn't very ShoutWiki-specific and can be used on any MediaWiki installation (running a sufficiently up-to-date version of MediaWiki).

History

The reason why this extension was written was that in the past, each skin (at ShoutWiki) that should have ads needed to implement its own ad loader, which was not very easy to maintain, as it meant lots and lots of code duplication. To solve the problem, we stashed all the ad-related code into one class, and we'd just hook on the different hooks in different skins to display the ads.

All the functions in the ShoutWikiAds class are public and static, so it's very easy to use the class.

Installation

• Download and move the extracted ShoutWikiAds folder to your extensions/ directory.
  Developers and code contributors should install the extension from Git instead, using:cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/ShoutWikiAds
• Add the following code at the bottom of your LocalSettings.php file:

  wfLoadExtension( 'ShoutWikiAds' );
  

• Configure the $wgAdConfig variable
•  Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Parameters

The extension has only one configuration variable, $wgAdConfig. It should look something like this:

$wgAdConfig = [
	// Is ad serving enabled?
	'enabled' => true,

	// AdSense publisher ID *without* the "pub-" prefix
	'adsense-client' => '',

	// Namespaces for which ad serving is enabled
	'namespaces' => [
		NS_MAIN,
		NS_TALK
	],

	// Set to 'responsive' for responsive ads
	'mode' => 'static',

	// Set to true when developing to have the extension serve
	// out static images (from Google's servers) instead of
	// real ad units
	'debug' => false,

	// Ad slots for certain skins' certain types of ads
	// Note: 
	'monaco-leaderboard-ad-slot' => '',
	'monaco-small-square-ad-slot' => '',
	'monaco-button-ad-slot' => '',
	'monobook-skyscraper-ad-slot' => '',
	'truglass-leaderboard-ad-slot' => '',
	'vector-button-ad-slot' => '',
	'vector-skyscraper-ad-slot' => '',

	### PER-SKIN AD CONFIGURATION ###
	'aurora' => [ // ShoutWiki exclusive skin
		'leaderboard' => true,
		'leaderboard-bottom' => true,
		'skyscraper' => true
	],
	'cologneblue' => [
		'banner' => true,
		'toolbox' => true
	],
	// Note: Both Dusk and DuskToDawn have so narrow content areas that
	// they just don't have the necessary space for a 'leaderboard' ad,
	// so instead they use a 'banner' ad.
	'dusk' => [
		'banner' => true,
		'toolbox' => true
	],
	'dusktodawn' => [
		'banner' => true,
	],
	'metrolook' => [
		'toolbox' => true,

		// Note: the wide skyscraper ad is only shown when screen width is
		// at least 1300px!
		'wide-skyscraper' => true
	],
	'mirage' => [
		'leaderboard' => true,
		'square' => true
	],
	'modern' => [
		'leaderboard' => true,
		'toolbox' => true
	],
	'monaco' => [ // ShoutWiki exclusive skin
		// Note: for Monaco, the leaderboard ad is in the page *footer*!
		'leaderboard' => true,
		'sidebar' => true
	],
	'monobook' => [
		'leaderboard' => true,
		'sidebar' => true,
		'skyscraper' => true
	],
	'nimbus' => [
		'leaderboard' => true,
		'sidebar' => true
	],
	'refreshed' => [
		'leaderboard' => true,
		'leaderboard-footer' => true,
		'sidebar' => true
	],
	'truglass' => [
		'leaderboard' => true
	],
	'vector' => [
		'leaderboard' => true,
		'skyscraper' => true,
		'toolbox' => true
	]
];

If the enabled key is set to false, the extension will do nothing.

The adsense-client key should be set to your AdSense provider number (just the number, not the "pub-" part!).

Supported skins

• Aurora (ShoutWiki)
• Cologne Blue
• Dusk
• DuskToDawn
• Metrolook
• Mirage
• Modern
• Monaco (ShoutWiki)
• MonoBook
• Nimbus
• Quartz (ShoutWiki)
• Refreshed
• Truglass
• Vector (original version only, Vector 2022/New Vector is untested)

Note on leaderboard ads

Save for a handful of explicitly blacklisted skins (Dusk and DuskToDawn, which have a very narrow content area; Monaco and Truglass, which do support the leaderboard ad but the implementation is non-standard), almost all skins support the leaderboard ad type even if they aren't explicitly listed above as supported. This is because for most skins, the leaderboard ad is implemented via a SiteNoticeAfter hook handler, and this hook should run in pretty much all skins.

To test it out, set $wgAdConfig['<your-skin-name>']['leaderboard'] = true; in LocalSettings.php. For example, for the DeskMessMirrored skin:

$wgAdConfig['deskmessmirrored']['leaderboard'] = true;

This would then enable the leaderboard ad slot in the DeskMessMirrored skin, which you can then verify by simply loading a page with the aforementioned skin.

Customizing ad colors

When in the non-responsive mode (i.e. $wgAdConfig['mode'] is set to 'static'), certain MediaWiki: namespace messages can be used to customize the colors of displayed ads. The naming of these interface messages follows the convention shoutwiki-<skin name>-<ad slot name>-ad-color-<color variable name>. For example, MediaWiki:Shoutwiki-metrolook-wide-skyscraper-ad-color-bg could be used to customize the ad background color for wide skyscraper ads in the Metrolook skin (this corresponds to the AdSense JS variable google_color_bg.

For each ad slot, the following JS variables can be customized via the aforementioned messages:

• border color (google_color_border JS variable)
• background color (google_color_bg JS variable)
• link color (google_color_link JS variable) (TODO: how does this differ from google_color_url below? I have no idea...)
• text color (google_color_text JS variable)
• URL color (google_color_url JS variable) (TODO: how does this differ from google_color_link above? I have no idea...)