Commit 6b04514f authored by Laurent Sittler's avatar Laurent Sittler

feat(Matomo Analytics): add Matomo Analytics custom action

parent 21db197f
......@@ -26,10 +26,8 @@ Provide a Sticky Footer for your SharePoint sites with the content provided by a
[Learn more ›](SharePoint.UI.StickyFooter)
### SharePoint.GA
### SharePoint.MA
> Init project only
Provide a custom script to set up easily (without any more code) Matomo Analytics on SharePoint site collections with classic experience.
Provide a script to add Google Analytics for all of your sites with your own KPIs provided by a SharePoint List or directly from the Provisioning.
Learn more ›
\ No newline at end of file
[Learn more ›](SharePoint.MA)
\ 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:Parameters>
<pnp:Parameter Key="trackingUrl"></pnp:Parameter>
<pnp:Parameter Key="trackingSiteId"></pnp:Parameter>
<pnp:Parameter Key="trackHeartBeatTimer"></pnp:Parameter>
<pnp:Parameter Key="trackUserId"></pnp:Parameter>
</pnp:Parameters>
</pnp:Preferences>
<pnp:Templates ID="CONTAINER-SP-MATOMO-ANALYTICS">
<pnp:ProvisioningTemplate ID="SP-MATOMO-ANALYTICS">
<pnp:CustomActions>
<pnp:SiteCustomActions>
<pnp:CustomAction Name="SPMatomoAnalytics"
Location="ScriptLink"
Sequence="0"
ScriptBlock="
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) {
scriptsSrc.push(scripts[i].id);
}
}
}
if (scriptsSrc.indexOf('SPMatomoAnalytics') === -1) {
var newScript = document.createElement('script');
newScript.id = 'SPMatomoAnalytics';
newScript.type = 'text/javascript';
newScript.text = `
var _paq = window._paq || [];
{parameter:trackHeartBeatTimer}
{parameter:trackUserId}
_paq.push(['trackPageView']);
_paq.push(['enableLinkTracking']);
(function() {
var u='{parameter:trackingUrl}';
_paq.push(['setTrackerUrl', u+'matomo.php']);
_paq.push(['setSiteId', '{parameter:trackingSiteId}']);
var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
g.type='text/javascript'; g.async=true; g.defer=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
})();
`;
headID.appendChild(newScript);
scriptsSrc.push('SPMatomoAnalytics');
}" />
</pnp:SiteCustomActions>
</pnp:CustomActions>
</pnp:ProvisioningTemplate>
</pnp:Templates>
</pnp:Provisioning>
\ No newline at end of file
## Matomo Analytics for SharePoint 2013/2016/2019/Online
This solution demonstrates how to enable the Matomo Analytics in Microsoft SharePoint 2013/2016/2019 On-Premises or SharePoint Online using the PowerShell script SPMA.ps1, and also provides you the capability to enable a custom Analytics Tracker 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 *SPMA* 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.MA` 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 *SPMA* 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 *SPMA.ps1* script.
The *SPMA* 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 Analytics server URL |
| `-trackingSiteId` | yes | `undefined` | Matomo Tracking ID |
| `-trackHeartBeatTimer` | no | `false` | Track the time spent on the page accurately (supported values are: 0, false, 1, true) |
| `-trackUserId` | no | `false` | Accurately measure your unique users based on their login name (supported values are: 0, false, 1, true) |
| `-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 *SPMA* script:
##### EXAMPLE 1
```PowerShell
PS C:\> .\SPMA.ps1 -siteUrl "https://intranet.mydomain.com/sites/targetSite" -trackingUrl https://matomo.my-domain.com -trackingSiteId "1"
```
The example above enables the Matomo Analytics 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
```PowerShell
PS C:\> $creds = Get-Credential
PS C:\> .\SPMA.ps1 -siteUrl "https://intranet.mydomain.com/sites/targetSite" -trackingUrl https://matomo.my-domain.com -trackingSiteId "1" -Credentials $creds
```
The example above enables the Matomo Analytics on the target Site Collection with the user's credentials provided through the *$creds* variable.
\ No newline at end of file
<#
.SYNOPSIS
Enables Matomo Analytics on a target classic SharePoint site collection.
.EXAMPLE
PS C:\> .\SPMA.ps1 -siteUrl "https://intranet.mydomain.com/sites/targetSite" -trackingUrl https://matomo.my-domain.com -trackingSiteId "1"
.EXAMPLE
PS C:\> $creds = Get-Credential
PS C:\> .\SPMA.ps1 -siteUrl "https://intranet.mydomain.com/sites/targetSite" -trackingUrl https://matomo.my-domain.com -trackingSiteId "1" -Credentials $creds
.NOTES
Version : 1.0.0.0
File Name : SPMA.ps1
Author : Laurent Sittler - [email protected]
.LINK
https://gitlab.lsonline.fr/SharePoint/javascript-customactions
#>
[CmdletBinding()]
param
(
[Parameter(Mandatory = $true, HelpMessage="Enter the URL of the target site collection, e.g. 'https://intranet.mydomain.com/sites/targetSite'")]
[String]$siteUrl,
[Parameter(Mandatory = $true, HelpMessage="Matomo Analytics server URL, e.g. 'https://matomo.my-domain.com'")]
[String]$trackingUrl,
[Parameter(Mandatory = $true, HelpMessage="Matomo Analytics Tracking Site ID, e.g. '1'")]
[String]$trackingSiteId,
[Parameter(Mandatory = $false, HelpMessage="Track the time spent on the page accurately. Default 'true'")]
[string]$trackHeartBeatTimer,
[Parameter(Mandatory = $false, HelpMessage="Accurately measure your unique users based on their login name. Default 'false'")]
[string]$trackUserId,
[Parameter(Mandatory = $false, HelpMessage="Optional administration credentials")]
[PSCredential]$Credentials
)
If ($Credentials -eq $null)
{
$Credentials = Get-Credential -Message "Enter Admin Credentials"
}
Write-Host -ForegroundColor White "--------------------------------------------------------"
Write-Host -ForegroundColor White "| Enabling Matomo Analytics |"
Write-Host -ForegroundColor White "--------------------------------------------------------"
Write-Host
try
{
Write-Host -ForegroundColor Yellow "Connecting to target site URL: $siteUrl"
Connect-PnPOnline $siteUrl -Credentials $Credentials
Write-Host -ForegroundColor Yellow "Enabling Matomo Analytics to the target site"
# Init additional parameters
$hbTimerScript = ""
$uidScript = ""
# If Track heartbeat Timer is true, then define 'enableHeartBeatTimer'
If ($trackHeartBeatTimer) {
$hbTimerScript = "_paq.push(['enableHeartBeatTimer']);"
}
# If track user id is true, then set 'setUserId' var content
If ($trackUserId) {
$uidScript = "_paq.push(['setUserId', _spPageContextInfo.userLoginName]);"
}
# PnP Parameters used by the XML Template
$pnpParams = @{
"trackingUrl" = $trackingUrl;
"trackingSiteId" = $trackingSiteId;
"trackHeartBeatTimer" = $hbTimerScript;
"trackUserId" = $uidScript;
}
# Retrieve all current CustomAction and remove old Matomo Analytics first
Get-PnPCustomAction -Scope site | ForEach-Object {
If ($_.Name -eq "SPMatomoAnalytics") {
Write-Host -ForegroundColor Yellow "Remove old Matomo Analytics 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 .\MatomoAnalytics.xml -Parameters $pnpParams -Handlers CustomAction
Write-Host -ForegroundColor Green "Matomo Analytics implementation succeeded"
}
catch
{
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