MediaWiki extensions manual

CentralNotice Release status: stable
Implementation	Special page,API
Description	Adds a central sitenotice
Author(s)	Andrew Russell Green,Matthew Walker,Adam Roses WightFormerly:Brooke Vibber,Tomasz Finc,Trevor Parscal,Ryan Kaldari
Latest version	2.6.1 (continuous updates)
Compatibility policy	Snapshots releases along with MediaWiki. Master is not backward compatible.
Database changes	Yes
Tables	cn_notices cn_assignments cn_templates cn_notice_languages cn_notice_projects cn_notice_countries cn_notice_regions cn_template_mixins cn_notice_mixins cn_notice_mixin_params cn_known_devices cn_template_devices cn_known_mobile_carriers cn_notice_mobile_carriers cn_notice_log cn_template_log
License	GNU General Public License 2.0 or later
Download	Download extension Git[?]: Browse repository (GitHub) Gerrit code review Git commit log Download source tarball
Example	Special:CentralNotice on Meta (read-only)
Parameters $wgNoticeBannerMaxAge $wgNoticeBannerReducedMaxAge $wgNoticeHideUrls $wgCentralNoticeCategoriesUsingLegacy $wgNoticeUseLanguageConversion $wgNoticeCookieDurations $wgCentralNoticeBannerMixins $wgCentralMobileSelectedBannerDispatcher $wgNoticeInfrastructure $wgCentralBannerRecorder $wgNoticeBucketExpiry $wgNoticeCookieDomain $wgNoticeTranslateDeployStates $wgCentralNoticeAdminGroup $wgCentralNoticeCampaignTypes $wgCentralNoticeImpressionEventSampleRate $wgCentralNoticeESITestString $wgCentralNoticeFallbackHideCookieDuration $wgCentralSelectedBannerDispatcher $wgCentralHost $wgNoticeProject $wgNoticeTabifyPages $wgCentralNoticeGeoIPBackgroundLookupModule $wgCentralNoticeApiUrl $wgNoticeProjects $wgCentralNoticeMessageProtectRight $wgCentralNoticeMaxCampaignFallback $wgCentralNoticeContentSecurityPolicy $wgCentralNoticeHideBannersP3P $wgCentralNoticeSampleRate $wgCentralNoticeCampaignMixins $wgCentralNoticePerCampaignBucketExtension $wgNoticeNumberOfControllerBuckets $wgNoticeNumberOfBuckets $wgNoticeUseTranslateExtension $wgCentralNoticeLoader
Hooks used CanonicalNamespaces ChangeTagsListActive GetPreferences ListDefinedTags LoadExtensionSchemaUpdates PreferencesGetIcon ResourceLoaderRegisterModules SkinTemplateNavigation::Universal UserMergeAccountFields
Hooks provided CentralNoticeCampaignChange
Translate the CentralNotice extension if it is available at translatewiki.net
Issues	Open tasks ·Report a bug

TheCentralNotice extension delivers announcements (usually in the form of banners) to Wikimedia wikis.It is used heavily by theFundraising team to solicit donations, and for announcements of interest to Wikimedia communities and users.CentralNotice can target announcements by country, language, project, device and logged-in status.

This page has information for CentralNotice developers andwiki administrators who want to install CentralNotice on their own sites.To learn how to create and configure CentralNotice campaigns, please seeHelp:CentralNotice onMeta-Wiki.For information about the CentralNotice setup on the Wikimedia Foundation's cluster, seeCentralNotice onWikitech.

CentralNotice allows central distribution of announcements to many wikis (calledsubscribing wikis) from a central wiki (theinfrastructure wiki).If you only need to post messages to a single wiki, consider usingSitenotice instead.

1. Download the latest snapshot and extract it to your extensions directory.
2. Add toLocalSettings.php the following:

   wfLoadExtension('CentralNotice');

3. By default, GeoIP lookup is disabled. If theGeo cookie is pre-populated, however, its value will be used. For local development, you can enable a client-side implementation that useshttps://freegeoip.net as follows. For more information, see#GeoIP lookup.

$wgCentralNoticeGeoIPBackgroundLookupModule='ext.centralNotice.freegeoipLookup';

1. From the command line, go to the wiki root and runphp maintenance/run.php update
2. EditLocalSettings.php and set ...
   1. $wgNoticeInfrastructure to true
   2. $wgNoticeProjects to be an array of projects that will subscribe to the central wiki. For examplearray( 'wikipedia', 'wiktionary' )
3. By default thesysop group is the only group with the ability to administer CentralNotice. If additional groups are needed, assign them thecentralnotice-admin andeditinterface permissions.

EditLocalSettings.php and set...

1. $wgNoticeInfrastructure tofalse;
2. $wgNoticeProject to be an entry in$wgNoticeProjects;
3. $wgCentralHost to the protocol (potentially neutral) and domain of the central wiki. For example//meta.wikimedia.org;
4. $wgCentralSelectedBannerDispatcher to the URL of Special:BannerLoader on the central wiki, for example://meta.wikimedia.org/w/index.php/Special:BannerLoader;
5. either$wgCentralDBname to the name of the infrastructure wiki's database, or$wgCentralNoticeApiUrl to the API endpoint of the infrastructure wiki; and
6. $wgCentralBannerRecorder to the URL of Special:RecordImpression on the central wiki. For example://meta.wikimedia.org/w/index.php/Special:RecordImpression.

For most development tasks, you can use a single wiki in both infrastructure and subscribing roles.Following are sample lines to include inLocalSettings.php.(See notes in comments.)

wfLoadExtension('CentralNotice');$wgNoticeInfrastructure=true;$wgNoticeProject='centralnoticeproject';# 'centralnoticeproject' can be any string$wgNoticeProjects=[$wgNoticeProject];$wgCentralHost=$wgServer;$wgCentralSelectedBannerDispatcher="$wgServer$wgScriptPath/index.php?title=Special:BannerLoader";$wgCentralDBname=$wgDBname;$wgCentralNoticeGeoIPBackgroundLookupModule='ext.centralNotice.freegeoipLookup';

All code that runs on subscribing wikis should be smoke-tested withMobileFrontend, to ensure they work on the mobile version of the site.

Some CentralNotice features require other MediaWiki extensions, includingEventLogging andTranslate.

The WMFFundraising tech team are the maintainers of CentralNotice.For questions about installation, bug reports, or usage of CentralNotice please send an email to the mailing listwikitech-l@lists.wikimedia.org or join us in theIRC channel#wikimedia-fundraising^connect.

• centralnotice-admin — Permission required to modify campaigns and banners. Relevant only to the infrastructure wikis (see alsobugzilla:26377).
  • editinterface - required to edit banner content.

From a user facing perspective, the high level CentralNotice objects arecampaigns (a.k.a. notices) andbanners (a.k.a. templates).These are affected by the back end concepts ofselectors andallocation.

• Banner — a single block of translatable html/wikitext/css/javascript that will display at the top ofManual:$wgContentNamespaces pages. The user status, device type, UI languageselectors are applied to banners.
  • Banners may be grouped bycategory. All banners in a category share user side cookies, such as the hiding cookie that is set when a user clicks a banner close button.
• Campaign — a collection of banners. The project, country and content language selectors apply at the campaign level. The system allows as many active campaigns at the same time as you want dynamically calculating anallocation for each banner in an active campaign. Campaigns are defined as active if the central wiki time is greater than the campaign start time, less than the campaign end time, and the campaign is marked as enabled.
  • Banners in a campaign are assigned abucket andweight. Buckets are yet another selector, and weight affects the relative allocation of banners inside a campaign.
  • There are fourpriority levels in CentralNotice. Higher priority campaigns will get a greater allocation of page views.
  • Campaigns may belocked which will prevent editing and deletion of the campaign; but not the banners inside a campaign.
• Selector — any property which may be filtered on for the purposes of allocation. This allows, for example, different banners to be shown to logged in versus logged out users in Argentina browsing Wikipedia in English.
  • Aselection vector is the complete set of selectors a user presents to the central wiki when requesting a banner.
• Allocation — The chance a banner will be shown to a user under a given selection vector.

• Design Research Project 2017
• Banner allocation algorithm
• Database schema / table layout

By default, CentralNotice has no client-side GeoIP lookup service configured.This is optimised for the Wikimedia Foundation production configuration where Varnish populates theGeo cookie from the server-side.(Seewikitech:Geolocation.)You can configure CentralNotice to use a custom data source client-side through theCentralNoticeGeoIPBackgroundLookupModule configuration variable.This variable expects the name of a ResourceLoader module that exports a function.The function will be called without parameters and should return a Promise that resolves with an object containing the following properties:

• country: string - Two-letter country code.
• region: string - Implementation specific.
• city: string - City name.
• lat: number.
• lon: number.

Full usage instructions can be found atmeta:Help:CentralNotice.

1. LoadSpecial:CentralNoticeBanners
2. Click on the add banner link at the bottom of the page (must be logged in as an admin).
3. Enter in a name and the raw HTML for the given banner.
   1. If this banner is going to be translated then enclose any text to be translated with triple parens - {{{FOO}}}.
4. Submit

(TODO: move and expand this snippet)

• Each banner has its banner definition stored in MediaWiki:Centralnotice-template-<name>
• All of its messages are stored below the banner defined in MediaWiki:Centralnotice-template-<name>-<message>/<language_code>

1. LoadSpecial:CentralNotice
2. Add a campaign with a given start time at the bottom portion of the page, leave a comment, and click submit.
   1. If this campaign is only run on a specific wiki and or language then select it from the pull downs.
3. Click on the new campaign and add the banners you want within this running campaign and their respective weights.
4. If all looks well then set this campaign to enabled and it will show at the corresponding time.

Add any of the following URL parameters to preview a specific banner, defeat "diet" schemes, or debug pseudorandom banner selection.

banner

You can test a banner directly on any wiki by adding?banner=<bannername> to the end of the URL.

randomcampaign

A decimal number between 0 and 1, to be used as the "random" seed for choosing a campaign.

randombanner

A decimal number between 0 and 1, to be used as the "random" seed for choosing a banner among banners available in the chosen campaign.

country

Override the country code, before filtering to geotargeted campaigns. Accepts two-characterISO 3166-1 codes.

uselang

Its usual meaning in MediaWiki, this determines which banners you may be shown. Beware of content language vs. user language.

force

Override any banner hiding code, show the banner.

reset

Zero out any cookies being used to customize banner display (e.g. delivered impression count).

For example,

• [1]
• https://it.wikisource.org/wiki/Speciale:RandomRootpage?randomcampaign=0.142

If there is a problematic banner in the page, you can identify which banner is active by opening your developer console and inspecting the value of:mw.centralNotice.bannerData.bannerName.

Bannersdo not display on pages in theSpecial namespace, as well as edit pages and diff pages.

CentralNotice adds two API modules,centralnoticechoicedata andcentralnoticequerycampaign.(The API modulecentralnoticeallocations was deprecated and removed in MediaWiki 1.25.)

The following documentation is the output ofSpecial:ApiHelp/centralnoticechoicedata, automatically generated by the pre-release version of MediaWiki that is running on this site (MediaWiki.org).

The following documentation is the output ofSpecial:ApiHelp/centralnoticequerycampaign, automatically generated by the pre-release version of MediaWiki that is running on this site (MediaWiki.org).

• Help:CentralNotice andChanges following refactoring (2015-09) on meta
• Extension:CentralNotice/Campaign and banner selection
• Extension:CentralNotice/Impression diet
• Extension:CentralNotice/Special:RecordImpression
• Extension:CentralNotice/Statuses, reasons and status codes
• Extension:CentralNotice/Banner_mixins
• Requests for comment/CentralNotice Caching Overhaul - Frontend Proxy
• Extension:CentralNotice/Notes/Miscelaneous doc bits
• Extension:CentralNotice/Notes/Documentation rewrite
• Extension:CentralNotice/Notes/Campaign-associated_mixins_and_banner_history
• Extension:CentralNotice/Notes/Banner controller refactoring
• Other subpages of this page (warning: many are outdated)

This extension is being used on one or moreWikimedia projects. This probably means that the extension is stable and works well enough to be used by such high-traffic websites. Look for this extension's name in Wikimedia'sCommonSettings.php andInitialiseSettings.php configuration files to see where it's installed. A full list of the extensions installed on a particular wiki can be seen on the wiki'sSpecial:Version page.

This extension is included in the following wiki farms/hosts and/or packages: Miraheze WikiForge This is not an authoritative list.Some wiki farms/hosts and/or packages may contain this extension even if they are not listed here.Always check with your wiki farms/hosts or bundle to confirm.

• Stable extensions
• Special page extensions
• API extensions
• GPL licensed extensions
• Extensions in Wikimedia version control
• CanonicalNamespaces extensions
• ChangeTagsListActive extensions
• GetPreferences extensions
• ListDefinedTags extensions
• LoadExtensionSchemaUpdates extensions
• PreferencesGetIcon extensions
• ResourceLoaderRegisterModules extensions
• SkinTemplateNavigation::Universal extensions
• UserMergeAccountFields extensions
• All extensions
• Extensions used on Wikimedia
• Extensions included in Miraheze
• Extensions included in WikiForge
• Extensions for data exchange with other local wikis
• Extensions supporting fundraising and donations
• Fundraising

• Extensions with release branches compatibility policy