Skip to content

Commit

Permalink
Merge branch 'release/v1.3.0'
Browse files Browse the repository at this point in the history
  • Loading branch information
octfx committed Aug 11, 2023
2 parents 326335a + c999857 commit 57ae1bb
Show file tree
Hide file tree
Showing 13 changed files with 760 additions and 30 deletions.
122 changes: 109 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,19 +4,32 @@ Plausible Analytics is a simple, lightweight (< 1 KB), open-source and privacy-f

See https://github.com/plausible/analytics

## Installation
* Download, extract and place the file(s) in a directory called Plausible in your extensions/ folder.
* Add the following code at the bottom of your LocalSettings.php file:
```php
wfLoadExtension( 'Plausible' );
$wgPlausibleDomain = "https://plausible.io";
$wgPlausibleDomainKey = "mywiki.example.com"; // change to your site address
$wgPlausibleApikey = ''; // Only necessary when using Extension:PageViewInfo
```
* Configure as required.
* Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

## Configuration
| Key | Description | Example | Default |
|-----------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------|---------|
| $wgPlausibleDomain | Plausible Domain. **Required** | https://plausible.io | null |
| $wgPlausibleDomainKey | Domain Key set on the plausible website. **Required** | plausible.io | null |
| $wgPlausibleHonorDNT | Honor the Do Not Track header and disable tracking. | false | true |
| $wgPlausibleTrackOutboundLinks | Enable Tracking of outbound link clicks. | true | false |
| $wgPlausibleTrackFileDownloads | Enable Tracking of link clicks that lead to files, sending a `File Download` event. See [the official docs](https://plausible.io/docs/file-downloads-tracking). | true | false |
| $wgPlausibleTrackFileDownloadExtensions | List of additional file extensions to track. See [the official docs](https://plausible.io/docs/file-downloads-tracking#which-file-types-are-tracked). | ['js', 'py'] | [] |
| $wgPlausibleTrackLoggedIn | Enable Tracking for logged in users. | true | false |
| $wgPlausibleEnableCustomEvents | Enable to add the global `window.plausible` function needed for custom event tracking. | true | false |
| $wgPlausibleIgnoredTitles | List of page titles that should not be tracked. [Examples](https://github.com/plausible/docs/blob/master/docs/excluding-pages.md#common-use-cases-and-examples). | ['/Page1', '/Special:*', ] | [] |
| $wgPlausibleEnableOptOutTag | Enables or disables the `<plausible-opt-out />` tag that allows users to opt-out from being tracked. | false | true |
| Key | Description | Example | Default |
|-----------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------|---------|
| $wgPlausibleDomain | Plausible Domain. **Required** | https://plausible.io | null |
| $wgPlausibleDomainKey | Domain Key set on the plausible website. **Required** | plausible.io | null |
| $wgPlausibleHonorDNT | Honor the Do Not Track header and disable tracking. | false | true |
| $wgPlausibleTrackOutboundLinks | Enable Tracking of outbound link clicks. | true | false |
| $wgPlausibleTrackFileDownloads | Enable Tracking of link clicks that lead to files, sending a `File Download` event. See [the official docs](https://plausible.io/docs/file-downloads-tracking). | true | false |
| $wgPlausibleTrackFileDownloadExtensions | List of additional file extensions to track. See [the official docs](https://plausible.io/docs/file-downloads-tracking#which-file-types-are-tracked). | ['js', 'py'] | [] |
| $wgPlausibleTrackLoggedIn | Enable Tracking for logged in users. | true | false |
| $wgPlausibleEnableCustomEvents | Enable to add the global `window.plausible` function needed for custom event tracking. | true | false |
| $wgPlausibleIgnoredTitles | List of page titles that should not be tracked. [Examples](https://github.com/plausible/docs/blob/master/docs/excluding-pages.md#common-use-cases-and-examples). | ['/Page1', '/Special:*', ] | [] |
| $wgPlausibleEnableOptOutTag | Enables or disables the `<plausible-opt-out />` tag that allows users to opt-out from being tracked. | false | true |
| $wgPlausibleApiKey | Auth Bearer key for integration with [Extension:PageViewInfo](https://www.mediawiki.org/wiki/Extension:PageViewInfo) | | |


### Included tracking scripts
Expand All @@ -32,7 +45,26 @@ The following tracking modules can be activated by setting the provided configur
| $wgPlausibleTrackCitizenSearchLinks | Only for [Skin:Citizen](https://github.com/StarCitizenTools/mediawiki-skins-Citizen). Track clicks to search result links found in `#typeahead-suggestions`. Event is named `CitizenSearchLinkClick`. | `CitizenSearchLinkClick` |
| $wgPlausibleTrackCitizenMenuLinks | Only for [Skin:Citizen](https://github.com/StarCitizenTools/mediawiki-skins-Citizen). Track clicks to links in the sidebar menu. Event is named `CitizenMenuLinkClick`. | `CitizenMenuLinkClick` |


### Server Side Tracking
Some events can be sent serverside without having to rely on the included plausible client script.

The following custom events can be activated:
```php
$wgPlausibleServerSideTracking = [
'pageview' => false,
'page404' => false,
'pageedit' => true,
'pagedelete' => true,
'pageundelete' => true,
'pagemove' => true,
'userregister' => true,
'userlogin' => true,
'userlogout' => true,
'fileupload' => true,
'filedelete' => true,
'fileundelete' => true,
];
```

## Tracking Custom Events
https://github.com/plausible/docs/blob/master/docs/custom-event-goals.md
Expand Down Expand Up @@ -67,3 +99,67 @@ By default, Plausible Analytics tracks every page you install the snippet on. If
| `/*/priv/*` | `/<anything>/priv/<anything>` - for example, `/admin/priv/sites`, but not `/priv` nor `/priv/page` nor `/admin/priv` |
| `/rule/*/*` | `/rule/<anything>/<anything>` - for example, `/rule/4/new/` or `/rule/10/edit`, but not `/rule` nor `/rule/10/new/save` |
| `/wp/**` | `/wp<anything, even slashes>` - for example, `/wp/assets/subdirectory/another/image.png` or `/wp/admin`, and everything in between, but not `/page/wp` |

## Lua Integration
With [Extension:PageViewInfo](https://www.mediawiki.org/wiki/Extension:PageViewInfo) active, plausible exposes the following functions:

1. `mw.ext.plausible.topPages()`
Returns the top pages and the views for the last day. The table is ordered by the number of page views, and can be iterated by using `ipairs`.
Example:
```lua
local result = mw.ext.plausible.topPages()
> {
{
page = "Foo",
views = 100
},
{
page = "Bar",
views = 80
},
{ [...] }
}
```

Alternatively this function can be called with the number of days to calculate the views over, e.g. `mw.ext.plausible.topPages( 30 )`.
This is _expensive_ as no caching is employed.

2. `mw.ext.plausible.pageData( titles, days )`
Returns the page views for the given titles over the last N days.
Example:
```lua
local result = mw.ext.plausible.pageData( { "Foo", "Bar" }, 5 )
> {
["Foo"] = {
["2023-08-04"] = 10,
["2023-08-05"] = 1,
["2023-08-06"] = 4,
["2023-08-07"] = 7,
["2023-08-08"] = 1,
["2023-08-09"] = 4,
},
["Bar"] = {
["2023-08-04"] = 100,
["2023-08-05"] = 14,
["2023-08-06"] = 54,
["2023-08-07"] = 7,
["2023-08-08"] = 31,
["2023-08-09"] = 1,
},
}
```

3. `mw.ext.plausible.siteData( days )`
Returns the site views for the given last N days.
Example:
```lua
local result = mw.ext.plausible.siteData( 5 )
> {
["2023-08-04"] = 10,
["2023-08-05"] = 1,
["2023-08-06"] = 4,
["2023-08-07"] = 7,
["2023-08-08"] = 1,
["2023-08-09"] = 4,
}
```
2 changes: 1 addition & 1 deletion composer.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "octfx/plausible",
"version": "1.2.1",
"version": "1.3.0",
"type": "mediawiki-extension",
"description": "Integrates plausible analytics",
"homepage": "https://www.mediawiki.org/wiki/Extension:Plausible",
Expand Down
65 changes: 61 additions & 4 deletions extension.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "Plausible",
"version": "1.2.1",
"version": "1.3.0",
"author": [
"[https://www.mediawiki.org/wiki/User:Octfx Octfx]"
],
Expand All @@ -9,7 +9,7 @@
"license-name": "GPL-2.0-or-later",
"type": "other",
"requires": {
"MediaWiki": ">= 1.35.0",
"MediaWiki": ">= 1.39.0",
"platform": {
"php": ">=7.3.19"
}
Expand Down Expand Up @@ -86,6 +86,25 @@
"PlausibleApiKey": {
"description": "API Key used for querying statistics when Extension:PageViewInfo is active",
"value": ""
},
"PlausibleServerSideTracking": {
"description": "Server side events that get sent as custom events to plausible",
"value": {
"pageview": false,
"page404": false,
"pageedit": true,
"pagedelete": true,
"pageundelete": true,
"pagemove": true,
"userregister": true,
"userlogin": true,
"userlogout": true,
"fileupload": true,
"filedelete": true,
"fileundelete": true,
"searchnotfound": true,
"searchfound": true
}
}
},
"ConfigRegistry": {
Expand All @@ -105,7 +124,32 @@
},
"HookHandlers": {
"PageHooks": {
"class": "MediaWiki\\Extension\\Plausible\\Hooks\\PageHooks"
"class": "MediaWiki\\Extension\\Plausible\\Hooks\\PageHooks",
"services": [
"MainConfig",
"JobQueueGroup"
]
},
"UserHooks": {
"class": "MediaWiki\\Extension\\Plausible\\Hooks\\UserHooks",
"services": [
"MainConfig",
"JobQueueGroup"
]
},
"FileHooks": {
"class": "MediaWiki\\Extension\\Plausible\\Hooks\\FileHooks",
"services": [
"MainConfig",
"JobQueueGroup"
]
},
"SearchHooks": {
"class": "MediaWiki\\Extension\\Plausible\\Hooks\\SearchHooks",
"services": [
"MainConfig",
"JobQueueGroup"
]
},
"ParserHooks": {
"class": "MediaWiki\\Extension\\Plausible\\Hooks\\ParserHooks"
Expand All @@ -116,8 +160,18 @@
},
"Hooks": {
"BeforePageDisplay": "PageHooks",
"PageSaveCompleteHook": "PageHooks",
"ArticleDeleteAfterSuccessHook": "PageHooks",
"ParserFirstCallInit": "ParserHooks",
"MediaWikiServices": "MediaWikiServices"
"MediaWikiServices": "MediaWikiServices",
"LocalUserCreatedHook": "UserHooks",
"UserLogoutCompleteHook": "UserHooks",
"UserLoginCompleteHook": "UserHooks",
"UploadCompleteHook": "FileHooks",
"FileDeleteCompleteHook": "FileHooks",
"SpecialSearchNogomatchHook": "SearchHooks",
"SpecialSearchGoResultHook": "SearchHooks",
"ScribuntoExternalLibraries": "MediaWiki\\Extension\\Plausible\\Hooks\\ScribuntoHooks::onScribuntoExternalLibraries"
},
"ResourceModules": {
"ext.plausible.opt-out": {
Expand Down Expand Up @@ -170,5 +224,8 @@
]
}
},
"JobClasses": {
"PlausibleEvent": "MediaWiki\\Extension\\Plausible\\PlausibleEventJob"
},
"manifest_version": 2
}
55 changes: 55 additions & 0 deletions includes/Hooks/FileHooks.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
<?php

namespace MediaWiki\Extension\Plausible\Hooks;

use Config;
use JobQueueGroup;
use MediaWiki\Extension\Plausible\PlausibleEventJob;
use MediaWiki\Hook\FileDeleteCompleteHook;
use MediaWiki\Hook\FileUndeleteCompleteHook;
use MediaWiki\Hook\UploadCompleteHook;
use RequestContext;

class FileHooks implements UploadCompleteHook, FileDeleteCompleteHook, FileUndeleteCompleteHook {

private array $config;
private JobQueueGroup $jobs;

public function __construct( Config $config, JobQueueGroup $group ) {
$this->config = $config->get( 'PlausibleServerSideTracking' );
$this->jobs = $group;
}

/**
* @inheritDoc
*/
public function onFileDeleteComplete( $file, $oldimage, $article, $user, $reason ) {
if ( !$this->config['filedelete'] ) {
return;
}

$this->jobs->push( PlausibleEventJob::newFromRequest( $user->getRequest(), 'filedelete' ) );
}

/**
* @inheritDoc
*/
public function onUploadComplete( $uploadBase ) {
if ( !$this->config['fileupload'] ) {
return;
}

$this->jobs->push( PlausibleEventJob::newFromRequest( RequestContext::getMain()->getRequest(), 'fileupload' ) );
}

/**
* @inheritDoc
*/
public function onFileUndeleteComplete( $title, $fileVersions, $user, $reason ) {
if ( !$this->config['fileundelete'] ) {
return;
}

$this->jobs->push( PlausibleEventJob::newFromRequest( $user->getRequest(), 'fileundelete' ) );
}
}
2 changes: 1 addition & 1 deletion includes/Hooks/MediaWikiServices.php
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ public function onMediaWikiServices( $services ) {
global $wgPageViewApiMaxDays;

$cache = ObjectCache::getLocalClusterInstance();
$logger = LoggerFactory::getInstance( 'PageViewInfoGA' );
$logger = LoggerFactory::getInstance( 'Plausible' );
$cachedDays = max( 30, $wgPageViewApiMaxDays );

$services->redefineService(
Expand Down
Loading

0 comments on commit 57ae1bb

Please sign in to comment.