Extension:CentralNotice - MediaWiki

Extension:CentralNotice - MediaWiki
Jump to content
From mediawiki.org
Translate this page
Languages:
Bahasa Indonesia
Türkçe
polski
português
čeština
русский
বাংলা
中文
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 Wight
Formerly
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
Virtual domain
virtual-centralnotice
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
Parameters
$wgNoticeUseTranslateExtension
$wgNoticeBannerReducedMaxAge
$wgNoticeNumberOfBuckets
$wgCentralNoticeCategoriesUsingLegacy
$wgNoticeUseLanguageConversion
$wgNoticeCookieDurations
$wgCentralNoticeBannerMixins
$wgCentralNoticeLoader
$wgCentralBannerRecorder
$wgNoticeBucketExpiry
$wgNoticeCookieDomain
$wgNoticeTranslateDeployStates
$wgCentralNoticeAdminGroup
$wgCentralNoticeCampaignTypes
$wgCentralNoticeImpressionEventSampleRate
$wgCentralNoticePerCampaignBucketExtension
$wgNoticeNumberOfControllerBuckets
$wgCentralHost
$wgNoticeProject
$wgNoticeTabifyPages
$wgCentralNoticeGeoIPBackgroundLookupModule
$wgCentralNoticeApiUrl
$wgNoticeProjects
$wgCentralNoticeMessageProtectRight
$wgNoticeInfrastructure
$wgNoticeBannerMaxAge
$wgCentralNoticeHideBannersP3P
$wgCentralNoticeSampleRate
$wgCentralNoticeMaxCampaignFallback
$wgNoticeHideUrls
$wgCentralNoticeContentSecurityPolicy
$wgCentralNoticeFallbackHideCookieDuration
$wgCentralSelectedBannerDispatcher
$wgCentralNoticeCampaignMixins
Hooks used
CanonicalNamespaces
ChangeTagsListActive
GetPreferences
ListDefinedTags
LoadExtensionSchemaUpdates
PreferencesGetIcon
ResourceLoaderRegisterModules
SkinTemplateNavigation::Universal
UserMergeAccountFields
Hooks provided
CentralNoticeCampaignChange
Licence
GNU General Public License 2.0 or later
Download extension
Git
Browse repository
GitHub
Gerrit code review
Git commit log
Download source tarball
Example
Special:CentralNotice on Meta (read-only)
Translate the CentralNotice extension
if it is available at translatewiki.net
Issues
Open tasks
Report a bug
The
CentralNotice
extension delivers announcements (usually in the form of banners) to Wikimedia wikis.
It is used heavily by the
Fundraising
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
and
wiki administrators
who want to install CentralNotice on their own sites.
To learn how to create and configure CentralNotice campaigns, please see
Help:CentralNotice
on
Meta-Wiki
For information about the CentralNotice setup on the Wikimedia Foundation's cluster, see
CentralNotice
on
Wikitech
CentralNotice allows central distribution of announcements to many wikis (called
subscribing
wikis) from a central wiki (the
infrastructure
wiki).
If you only need to post messages to a single wiki
, consider using
Sitenotice
instead.
Installation
CentralNotice is developed, tested, and known to be deployed only on wikis that do not use table prefixing. If your setup uses table prefixing there is no guarantee this extension will work. Please report any bugs to
Phabricator
Install
Extension:EventLogging
first
and move the extracted
CentralNotice
folder to your
extensions/
directory.
Developers and code contributors should install the extension
from Git
instead, using:
cd
extensions/
git
clone
Add the following code at the bottom of your
LocalSettings.php
file:
wfLoadExtension
'CentralNotice'
);
Run the
update script
which will automatically create the necessary database tables that this extension needs.
By default, GeoIP lookup is disabled. If the
Geo
cookie is pre-populated, however, its value will be used. For local development, you can enable a client-side implementation that uses
as follows. For more information, see
#GeoIP lookup
$wgCentralNoticeGeoIPBackgroundLookupModule
'ext.centralNotice.freegeoipLookup'
Done
– Navigate to
Special:Version
on your wiki to verify that the extension is successfully installed.
The infrastructure wiki
The CentralNotice extension enables both the infrastructure and subscribing roles by default, which suffices for most development tasks and involves only a single wiki.
Members of the
sysop
group are granted the right to administer CentralNotice campaigns and banners.
If additional groups are needed, assign them the
centralnotice-admin
and
editinterface
permissions.
Some CentralNotice features optionally integrate with
Translate
. To fully utilize these features, you'll need to install that as well.
Subscribing-only wikis
Edit
LocalSettings.php
and set...
$wgNoticeInfrastructure
to
false
$wgCentralSelectedBannerDispatcher
to the URL of Special:BannerLoader on the central wiki, for example:
either
$wgCentralDBname
to the name of the infrastructure wiki's database, or
$wgCentralNoticeApiUrl
to the API endpoint of the infrastructure wiki; and
$wgCentralBannerRecorder
to the URL of Special:RecordImpression on the central wiki. For example:
All code that runs on subscribing wikis should be smoke-tested with
MobileFrontend
, to ensure they work on the mobile version of the site.
Getting help
The WMF
Fundraising tech
team are the maintainers of CentralNotice.
For questions about installation, bug reports, or usage of CentralNotice please send an email to the mailing list
wikitech-l@lists.wikimedia.org
or join us in the
IRC
channel
#wikimedia-fundraising
connect
Permissions
centralnotice-admin
— Permission required to modify campaigns and banners. Relevant only to the infrastructure wikis (see also
bugzilla:26377
).
editinterface
- required to edit banner content.
Design concepts
From a user facing perspective, the high level CentralNotice objects are
campaigns
(a.k.a. notices) and
banners
(a.k.a. templates).
These are affected by the back end concepts of
selectors
and
allocation
Banner
— a single block of translatable html/wikitext/css/javascript that will display at the top of
Manual:$wgContentNamespaces
pages. The user status, device type, UI language
selectors
are applied to banners.
Banners may be grouped by
category
. 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 an
allocation
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 a
bucket
and
weight
. Buckets are yet another selector, and weight affects the relative allocation of banners inside a campaign.
There are four
priority
levels in CentralNotice. Higher priority campaigns will get a greater allocation of page views.
Campaigns may be
locked
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.
selection 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 documents
Design Research Project 2017
Banner allocation algorithm
Database schema / table layout
GeoIP lookup
By default, CentralNotice has no client-side GeoIP lookup service configured.
This is optimised for the Wikimedia Foundation production configuration where Varnish populates the
Geo
cookie from the server-side.
(See
wikitech:Geolocation
.)
You can configure CentralNotice to use a custom data source client-side through the
CentralNoticeGeoIPBackgroundLookupModule
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.
Usage
Full usage instructions can be found at
meta:Help:CentralNotice
New Banner
Load
Special:CentralNoticeBanners
Click on the add banner link at the bottom of the page (must be logged in as an admin).
Enter in a name and the raw HTML for the given banner.
If this banner is going to be translated then enclose any text to be translated with triple parens - {{{FOO}}}.
Submit
(TODO: move and expand this snippet)
Each banner has its banner definition stored in MediaWiki:Centralnotice-template-
All of its messages are stored below the banner defined in MediaWiki:Centralnotice-template--/
New Campaign
Load
Special:CentralNotice
Add a campaign with a given start time at the bottom portion of the page, leave a comment, and click submit.
If this campaign is only run on a specific wiki and or language then select it from the pull downs.
Click on the new campaign and add the banners you want within this running campaign and their respective weights.
If all looks well then set this campaign to enabled and it will show at the corresponding time.
Overriding selection
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=

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-character
ISO 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]
Debugging problematic banners
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
Limitations
Banners
do not display
on pages in the
Special
namespace, as well as edit pages and diff pages.
API
CentralNotice adds two API modules,
centralnoticechoicedata
and
centralnoticequerycampaign
(The API module
centralnoticeallocations
was deprecated and removed in MediaWiki 1.25.)
The following documentation is the output of
Special:
ApiHelp/
centralnoticechoicedata
, automatically generated by the pre-release version of MediaWiki that is running on this site (MediaWiki.org).
action=centralnoticechoicedata
main
centralnoticechoicedata
This module requires read rights.
Source:
CentralNotice
License:
GPL-2.0-or-later
Get data needed to choose a banner for a given project and language
Specific parameters:
Other general parameters are available.
project
The project to get banner choice data for.
This parameter is required.
language
The language to get banner choice data for.
This parameter is required.
Example:
Get the data for choosing a banner for English Wikipedia users.
api.php?action=centralnoticechoicedata&project=wikipedia&language=en
[open in sandbox]
The following documentation is the output of
Special:
ApiHelp/
centralnoticequerycampaign
, automatically generated by the pre-release version of MediaWiki that is running on this site (MediaWiki.org).
action=centralnoticequerycampaign
main
centralnoticequerycampaign
This module requires read rights.
Source:
CentralNotice
License:
GPL-2.0-or-later
Get all configuration settings for a campaign.
Specific parameter:
Other general parameters are available.
campaign
Campaign name. Separate multiple values with a "|" (vertical bar).
This parameter is required.
Example:
Show campaign "Plea_US"
api.php?action=centralnoticequerycampaign&format=json&campaign=Plea_US
[open in sandbox]
See also
Help:CentralNotice
and
Changes 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 more
Wikimedia 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's
CommonSettings.php
and
InitialiseSettings.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's
Special:Version
page.
This extension is included in the following wiki farms/hosts and/or packages:
Miraheze
Retrieved from "
Categories
Stable extensions
Special page extensions
API extensions
CanonicalNamespaces extensions
ChangeTagsListActive extensions
GetPreferences extensions
ListDefinedTags extensions
LoadExtensionSchemaUpdates extensions
PreferencesGetIcon extensions
ResourceLoaderRegisterModules extensions
SkinTemplateNavigation::Universal extensions
UserMergeAccountFields extensions
GPL licensed extensions
Extensions in Wikimedia version control
All extensions
Extensions used on Wikimedia
Extensions included in Miraheze
Extensions for data exchange with other local wikis
Extensions supporting fundraising and donations
Fundraising
Hidden category:
Extensions with release branches compatibility policy
Extension
CentralNotice
Add topic