Help:CentralNotice/Changes following refactoring (2015-09)

From Meta, a Wikimedia project coordination wiki

On September 2, 2015, a major CentralNotice update was deployed to WMF wikis (version 2.6.0). The update improves CentralNotice performance and provides an initial version of a system for studying the sequences of banners shown to or hidden from users ("Banner History Logger").

For CentralNotice admins, minor changes in campaign setup may be required, depending on what kind of banner display statistics are needed, and on whether the banners always display themselves to the user. This is because the existing system for recording banner displays, Special:RecordImpression, now defaults to only record a sample of banner displays, and will be completely removed in the near future.

The update also changes the CentralNotice JavaScript API available to banners.

Here are the details.

Campaign setup and banner display statistics[edit]

Banners that always display when loaded[edit]

For campaigns with banners that always display when loaded: no changes in campaign configuration are necessary, unless near real-time access to banner display statistics at a sample rate greater than 1:10000 is required. If such access is truly needed, Special:RecordImpression client-side sampling rate may be increased by enabling the "Legacy support" option for the campaign, checking the "Set sample rate for Special:RecordImpression" option, and increasing the sample rate. This must be fully justified due to the extra server resources involved. For near real-time stats, the actual sample rate of the data provided is 1/100 of the client-side Special:RecordImpression sample rate. So, for example, for a near real-time sample rate of 1:100, set the Special:RecordImpression sample rate to 1.

For banners that always display when loaded, unsampled data can be obtained after several days (from Hive, via Special:BannerLoader). No special configuration is needed to make this to work. Note that this unsampled data won't include information about banners that were automatically hidden as a result of the user previously clicking on the "close" button. For statistics about about banner hides, the delayed, 1:100 sampled data will be available via Hive and Special:RecordImpression, for the time being. Later on, similar data will be available through the new Banner History Logger feature.

Banners that sometimes hide themselves using JavaScript[edit]

For campaigns with banners that sometimes hide themselves using JavaScript, no configuration changes are necessary if display statistics are not required.

If display statistics are needed, then the "Legacy support" campaign option should be enabled, and "Banners might not display, as determined by in-banner JavaScript" should be checked. Without this, the alterImpressionData hook won't run. (As before, information about the banner being hidden must be set from that hook in order to be sent with Special:RecordImpression.)

If it's acceptable to get near-real time display data at a sample rate of 1:10000 and delayed data at a sample rate of 1:100, no other configuration changes are needed. In that case, please do not check the "Set sample rate for Special:RecordImpression" option.

If a higher sample rate is truly needed for near real-time or delayed data, the "Set sample rate for Special:RecordImpression" option may be checked. Again, this must be fully justified due to the extra server resources involved.

JavaScript API changes[edit]

Legacy method of Special:RecordImpression throttling[edit]

To enable sampling of Special:RecordImpression, it used to be necessary to include the following JavaScript in banners: mw.centralNotice.onlySampleRI = true. This is no longer needed, since sampling is now the default.

Switching buckets via JavaScript[edit]

To change buckets via JavaScript in a banner, just say, mw.centralNotice.setBucket( newBucket ). The legacy method of calling mw.cnBannerControllerLib.storeBucket() won't work anymore.

Need more help?[edit]

If you have questions about any of these changes or need help setting up a campaign, please write to the CentralNotice admins mailing list, or send a message on the #wikimedia-fundraisingconnect IRC channel. Thanks!