feat(Matomo): add Matomo Tag Manager custom action

- Add custom action schema
- Add PowerShell script installation
- Add documentation
- Update main readme
parent 4962a4bf
......@@ -30,4 +30,10 @@ Provide a Sticky Footer for your SharePoint sites with the content provided by a
Provide a custom script to set up easily (without any more code) Matomo Analytics on SharePoint site collections with classic experience.
[Learn more ›](SharePoint.MA)
\ No newline at end of file
[Learn more ›](SharePoint.MA)
### SharePoint.MTM
Provide a custom script to set up easily (without any more code) Matomo Tag Manager on SharePoint site collections with classic experience.
[Learn more ›](SharePoint.MTM)
\ No newline at end of file
<?xml version="1.0"?>
<pnp:Provisioning xmlns:pnp="http://schemas.dev.office.com/PnP/2015/12/ProvisioningSchema">
<pnp:Preferences Generator="OfficeDevPnP.Core, Version=2.1.1602.1, Culture=neutral, PublicKeyToken=3751622786b357c2">
<pnp:Parameter Key="trackingUrl"></pnp:Parameter>
<pnp:ProvisioningTemplate ID="SP-MATOMO-TAGMANAGER">
<pnp:CustomAction Name="SPMatomoTagManager"
var headID = document.getElementsByTagName('head')[0];
var scripts = document.getElementsByTagName('script');
var scriptsSrc = [];
for (var i = 0; i &lt; scripts.length; i++) {
if (scripts[i].type === 'text/javascript') {
if (scripts[i].id) {
if (scriptsSrc.indexOf('SPMatomoTagManager') === -1) {
var newScript = document.createElement('script');
newScript.id = 'SPMatomoTagManager';
newScript.type = 'text/javascript';
newScript.text = `
var _mtm = _mtm || [];
_mtm.push({'mtm.startTime': (new Date().getTime()), 'event': 'mtm.Start'});
var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
g.type='text/javascript'; g.async=true; g.defer=true; g.src='{parameter:trackingUrl}'; s.parentNode.insertBefore(g,s);
}" />
\ No newline at end of file
## Matomo Tag Manager for SharePoint 2013/2016/2019/Online
This solution demonstrates how to implement Matomo Tag Manager in Microsoft SharePoint 2013/2016/2019 On-Premises or SharePoint Online using the PowerShell script SPMTM.ps1, and also provides you the capability to enable a Tag Management System for a Site Collection.
### Setup Instructions
In order to set the solution up on a target Site Collection, you simply need to:
* [Download the files included in this solution](#download)
* [Setup software requirements](#requirements)
* [Execute the *SPMTM* script](#execute)
>**Note**: If you are using SharePoint 2013 environment, setup scripts are assuming that you are running at least the April 2015 CU.
<a name="download"></a>
#### Download the files
You can download the files manually, one by one, or you can download as ZIP the repository with all custom actions. Within the ZIP archive, under the `/SharePoint.MTM` folder, you will find all the required files.
<a name="requirements"></a>
#### Setup software requirements
This solution requires the SharePointPnP.PowerShell commands, which you can install from one of the following link, depending on your target platform:
(see the [SharePointPnP.PowerShell installation instructions](https://github.com/OfficeDev/PnP-PowerShell#installation) for further details):
* [SharePointPnP.PowerShell package for SharePoint 2013](https://github.com/SharePoint/PnP-PowerShell/releases)
* [SharePointPnP.PowerShell package for SharePoint 2016](https://github.com/SharePoint/PnP-PowerShell/releases)
* [SharePointPnP.PowerShell package for SharePoint Online](https://github.com/SharePoint/PnP-PowerShell/releases)
>**Note**: Depending on your target platform (SharePoint 2013/2016/2019 On-Premises or SharePoint Online) you should refer to
the right build of the SharePointPnP.PowerShell commands. Nevertheless, even the SharePointPnPPowerShellOnline version, which
targets SharePoint Online, is viable to setup this solution on-premises. If you are running SharePoint 2013 environment,
PowerShell cmdlets used by the automation scripts have dependency on April 2015 CU to be installed on server side.
<a name="execute"></a>
#### Execute the *SPMTM* script
Once you have installed the SharePointPnP.PowerShell commands, you can open a PowerShell console, go to the path where you stored the files and execute the *SPMTM.ps1* script.
The *SPMTM* script accepts the following parameters:
| Parameter | Required | Default value | Description |
| `-siteUrl` | yes | `undefined` | URL of the site to provision and/or enable the custom action |
| `-trackingUrl` | yes | `undefined` | Matomo Tag Manager URL |
| `-Credentials` | no | `undefined` | User credentials that will be used to authenticate against both the target Site Collection. Should be the credentials of a user, who is Site Collection Administrator for the target Site Collections. If you don't provide this parameter, the script will directly prompt you for credentials. |
You can here see a couple of examples about how to invoke the *SPMTM* script:
##### EXAMPLE 1
> Change *https://matomo.my-domain.com/js/container_[contrainer ID].js* in accordance with your environment.
PS C:\> .\SPMTM.ps1 -siteUrl "https://intranet.mydomain.com/sites/targetSite" -trackingUrl https://matomo.my-domain.com/js/container_[contrainer ID].js
The example above enables the Matomo Tag Manager on the target Site Collection with URL https://intranet.mydomain.com/sites/targetSite.
The user's credentials are not provided, the script will therefore directly prompt the user.
##### EXAMPLE 2
> Change *https://matomo.my-domain.com/js/container_[contrainer ID].js* in accordance with your environment.
PS C:\> $creds = Get-Credential
PS C:\> .\SPMTM.ps1 -siteUrl "https://intranet.mydomain.com/sites/targetSite" -trackingUrl -trackingUrl https://matomo.my-domain.com/js/container_[contrainer ID].js -Credentials $creds
The example above enables the Matomo Tag Manager on the target Site Collection with the user's credentials provided through the *$creds* variable.
\ No newline at end of file
Enables Matomo Tag Manager on a target classic SharePoint site collection.
PS C:\> .\SPMTM.ps1 -siteUrl "https://intranet.mydomain.com/sites/targetSite" -trackingUrl https://matomo.my-domain.com/js/container_[contrainer ID].js
PS C:\> $creds = Get-Credential
PS C:\> .\SPMTM.ps1 -siteUrl "https://intranet.mydomain.com/sites/targetSite" -trackingUrl https://matomo.my-domain.com/js/container_[contrainer ID].js -Credentials $creds
Version :
File Name : SPMTM.ps1
Author : Laurent Sittler - [email protected]
[Parameter(Mandatory = $true, HelpMessage="Enter the URL of the target site collection, e.g. 'https://intranet.mydomain.com/sites/targetSite'")]
[Parameter(Mandatory = $true, HelpMessage="Matomo Tag Manager URL, e.g. 'https://matomo.my-domain.com/js/container_v34567ftgj.js'")]
[Parameter(Mandatory = $false, HelpMessage="Optional administration credentials")]
If ($Credentials -eq $null)
$Credentials = Get-Credential -Message "Enter Admin Credentials"
Write-Host -ForegroundColor White "--------------------------------------------------------"
Write-Host -ForegroundColor White "| Enabling Matomo Tag Manager |"
Write-Host -ForegroundColor White "--------------------------------------------------------"
Write-Host -ForegroundColor Yellow "Connecting to target site URL: $siteUrl"
Connect-PnPOnline $siteUrl -Credentials $Credentials
Write-Host -ForegroundColor Yellow "Enabling Matomo Tag Manager to the target site"
# PnP Parameters used by the XML Template
$pnpParams = @{
"trackingUrl" = $trackingUrl;
# Retrieve all current CustomAction and remove old Matomo Tag Manager first
Get-PnPCustomAction -Scope site | ForEach-Object {
If ($_.Name -eq "SPMatomoTagManager") {
Write-Host -ForegroundColor Yellow "Remove old Matomo Tag Manager Custom Action from target site"
Remove-PnPCustomAction -Identity $_.Id -scope site -Force -Confirm:$false
# Apply PnP Template = create custom action script
Write-Host -ForegroundColor Yellow "Apply PnP schema to target site"
Apply-PnPProvisioningTemplate -Path .\MatomoTagManager.xml -Parameters $pnpParams -Handlers CustomAction
Write-Host -ForegroundColor Green "Matomo Tag Manager implementation succeeded"
Write-Host -ForegroundColor Red "Exception occurred!"
Write-Host -ForegroundColor Red "Exception Type: $($_.Exception.GetType().FullName)"
Write-Host -ForegroundColor Red "Exception Message: $($_.Exception.Message)"
\ No newline at end of file
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment