feat: add support to track user id and track heart beat timer

- Update deployment scripts
- Update documentation
- Update extension

README.md

@@ -23,6 +23,8 @@ This repo provide the SharePoint extension based on the SPFx Framework and all s
 |`-siteUrl`|yes|`undefined`|URL of the site to provision and/or enable the extension|
 |`-trackingUrl`|yes|`undefined`|Matomo Analytics server URL|
 |`-trackingSiteId`|yes|`undefined`|Matomo Analytics Tracking Site ID|
+|`-trackHeartBeatTimer`|false|`true`|Track the time spent on the page accurately|
+|`-trackUserId`|false|`false`|Accurately measure your unique users based on their login name|
 |`-tenantSolutionDeployment`|no|`false`|Set `true`, to deploy the solution package to the whole tenant. If not specified, the package will be deployed to the current Site App Catalog|
 |`-skipCustomAction`|no|`false`|Don't enable the custom action to the target site|
 |`-checkPoint`|no|`0`|Check point from which to resume executing the setup script|
@@ -80,6 +82,8 @@ In this example, deploy and install the package only (the custom action will be
 |`-s`,`--siteUrl`|yes|`undefined`|URL of the site to provision and/or enable the extension|
 |`--trackingUrl`|yes|`undefined`|Matomo Analytics server URL|
 |`--trackingSiteId`|yes|`undefined`|Matomo Analytics Tracking Site ID|
+|`--trackHeartBeatTimer`|no|`true`|Track the time spent on the page accurately|
+|`--trackUserId`|no|`false`|Accurately measure your unique users based on their login name|
 |`--tenantSolutionDeployment`|no|`false`|Set `true`, to deploy the solution package to the whole tenant. If not specified, the package will be deployed to the current Site App Catalog|
 |`--skipCustomAction`|no|`false`|Don't enable the custom action to the target site|
 |`--checkPoint`|no|`0`|Check point from which to resume executing the setup script|

_functions.sh

@@ -10,6 +10,8 @@ help() {
  echo "-s, --siteUrl <tenantUrl> URL of the site to provision and/or enable the extension"
  echo "--trackingUrl <trackingUrl> Matomo Analytics Server URL"
  echo "--trackingSiteId <trackingSiteId> Matomo Analytics Tracking Site Id"
+ echo "--trackHeartBeatTimer [trackHeartBeatTimer] Track the time spent on the page accurately. Default 'true'"
+ echo "--trackUserId [trackUserId] Accurately measure your unique users based on their login name. Default 'false'"
  echo "--tenantSolutionDeployment [tenantSolutionDeployment] Set 'true', to deploy the solution package to the whole tenant. If not specified, the package will be deployed to the current Site App Catalog"
  echo "--skipCustomAction [skipCustomAction] Don't enable the custom action to the target site"
  echo "--checkPoint [checkPoint] Check point from which to resume executing the setup script"

config/serve.json

@@ -10,7 +10,9 @@
  "location": "ClientSideExtension.ApplicationCustomizer",
  "properties": {
  "trackingUrl": "//matomo.my-domain.com",
- "trackingSiteId": "2"
+ "trackingSiteId": "2",
+ "trackHeartBeatTimer": "true",
+ "trackUserId": "false"
  }
  }
  }
@@ -22,7 +24,9 @@
  "location": "ClientSideExtension.ApplicationCustomizer",
  "properties": {
  "trackingUrl": "//matomo.my-domain.com",
- "trackingSiteId": "2"
+ "trackingSiteId": "2",
+ "trackHeartBeatTimer": "true",
+ "trackUserId": "false"
  }
  }
  }

setup.ps1

@@ -38,6 +38,12 @@ Param(
  [Parameter(Mandatory=$true, HelpMessage="Matomo Analytics Tracking Site ID, e.g. '2'")]
  [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="Define to deploy the solution package to the whole tenant. If not specified, the package will be deployed to the current Site App Catalog")]
  [switch]$tenantSolutionDeployment,
 
@@ -140,7 +146,7 @@ If ($tenantSolutionDeployment) {
 
  If ($checkPoint -lt 300) {
  # Install solution to site collection
- Write-Verbose "Installing the Matomo Analytics Package with ID : $appId..."
+ Write-Verbose "Installing the Matomo Analytics Package with ID: $appId..."
  
  Install-PnPApp -Identity $appId -Scope Site
 
@@ -151,5 +157,20 @@ If ($tenantSolutionDeployment) {
 If (!$skipCustomAction) {
  Write-Host "Enabling the Matomo Analytics extension..."
 
- Add-PnPCustomAction -ClientSideComponentId a66f9d15-fcd2-4d37-8f8d-f76a4a7cae02 -Name "Matomo Analytics for SharePoint" -Title "Matomo Analytics for SharePoint" -Location ClientSideExtension.ApplicationCustomizer -ClientSideComponentProperties "{`"trackingUrl`":`"$trackingUrl`",`"trackingSiteId`":`"$trackingSiteId`"}" -Scope site
+ # Build SPFx extension propreties
+ $str = "{`"trackingUrl`":`"$trackingUrl`",`"trackingSiteId`":`"$trackingSiteId`""
+
+ If ($trackHeartBeatTimer) {
+ $str += ",`"trackHeartBeatTimer`":`"$trackHeartBeatTimer`""
+ }
+ If ($trackUserId) {
+ $str += ",`"trackUserId`":`"$trackUserId`""
+ }
+
+ $str += "}"
+
+ Write-Verbose "SPFx properties: $str"
+
+ # Add Custom action to site collection
+ Add-PnPCustomAction -ClientSideComponentId a66f9d15-fcd2-4d37-8f8d-f76a4a7cae02 -Name "Matomo Analytics for SharePoint" -Title "Matomo Analytics for SharePoint" -Location ClientSideExtension.ApplicationCustomizer -ClientSideComponentProperties $str -Scope site
 }

setup.sh

@@ -7,6 +7,8 @@
 siteUrl=
 trackingUrl=""
 trackingSiteId=""
+trackHeartBeatTimer=""
+trackUserId=""
 tenantSolutionDeployment=false
 verbose=false
 skipCustomAction=false
@@ -28,6 +30,14 @@ while [ $# -gt 0 ]; do
  shift
  trackingSiteId=$1
  ;;
+ --trackHeartBeatTimer)
+ shift
+ trackHeartBeatTimer=$1
+ ;;
+ --trackUserId)
+ shift
+ trackUserId=$1
+ ;;
  --tenantSolutionDeployment)
  tenantSolutionDeployment=true
  ;;
@@ -155,7 +165,7 @@ else
  if (( $checkPoint < 300 )); then
  # Install solution to site collection
  if [ "$verbose" = true ]; then
- msg "Installing the Matomo Analytics Package with ID : $appId...\n"
+ msg "Installing the Matomo Analytics Package with ID: $appId...\n"
  fi
  o365 spo app install --id $appId --siteUrl $siteUrl --scope sitecollection
 
@@ -166,8 +176,20 @@ fi
 if [ "$skipCustomAction" = false ]; then
  msg "Enabling the Matomo Analytics extension...\n"
 
- # Add Custom action to site collection
- str="'{\"trackingUrl\":\"$trackingUrl\",\"trackingSiteId\":\"$trackingSiteId\"}'"
+ # Build SPFx extension propreties
+ str="'{\"trackingUrl\":\"$trackingUrl\",\"trackingSiteId\":\"$trackingSiteId\""
+ if [ -n "$trackHeartBeatTimer" ]; then
+ str="$str,\"trackHeartBeatTimer\":\"$trackHeartBeatTimer\""
+ fi
+ if [ -n "$trackUserId" ]; then
+ str="$str,\"trackUserId\":\"$trackUserId\""
+ fi
+ str="$str}'"
+
+ if [ "$verbose" = true ]; then
+ msg "SPFx properties: $str\n"
+ fi
 
+ # Add Custom action to site collection
  o365 spo customaction add --url $siteUrl --clientSideComponentId a66f9d15-fcd2-4d37-8f8d-f76a4a7cae02 --name 'Matomo Analytics' --title 'Matomo Analytics' --location 'ClientSideExtension.ApplicationCustomizer' --scope Site -p $str
 fi

sharepoint/assets/clientsideinstance.xml

@@ -4,6 +4,6 @@
  Title="Matomo Analytics for SharePoint"
  Location="ClientSideExtension.ApplicationCustomizer"
  ComponentId="a66f9d15-fcd2-4d37-8f8d-f76a4a7cae02"
- Properties="{"trackingUrl":"//matomo.my-domain.com","trackingSiteId":"2"}">
+ Properties="{"trackingUrl":"//matomo.my-domain.com","trackingSiteId":"2","trackHeartBeatTimer":"true","trackUserId":"false"}">
  </ClientSideComponentInstance>
 </Elements>
\ No newline at end of file

sharepoint/assets/elements.xml

@@ -4,6 +4,6 @@
  Title="Matomo Analytics for SharePoint"
  Location="ClientSideExtension.ApplicationCustomizer"
  ClientSideComponentId="a66f9d15-fcd2-4d37-8f8d-f76a4a7cae02"
- ClientSideComponentProperties="{"trackingUrl":"//matomo.my-domain.com","trackingSiteId":"2"}">
+ ClientSideComponentProperties="{"trackingUrl":"//matomo.my-domain.com","trackingSiteId":"2","trackHeartBeatTimer":"true","trackUserId":"false"}">
  </CustomAction>-->
 </Elements>
\ No newline at end of file

src/extensions/matomo/MatomoApplicationCustomizer.ts

@@ -17,6 +17,8 @@ const LOG_SOURCE: string = 'MatomoApplicationCustomizer';
 export interface IMatomoApplicationCustomizerProperties {
  trackingUrl: string;
  trackingSiteId: string;
+ trackHeartBeatTimer: string;
+ trackUserId: string;
 }
 
 /** Deployement of Matomo Analytics through Custom Action
@@ -111,8 +113,10 @@ export default class MatomoApplicationCustomizer
  let codeTracker = `
  var _paq = window._paq || [];
  _paq.push(['trackPageView']);
- _paq.push(['enableLinkTracking']);
- _paq.push(['setTrackerUrl', '${this.properties.trackingUrl.replace(/\/\s*$/, '')}/matomo.php']);
+ _paq.push(['enableLinkTracking']);`;
+ codeTracker += this.getEnableHeartBeatTimer() ? `_paq.push(['enableHeartBeatTimer']);` : ``;
+ codeTracker += this.gettTrackUserId() ? `_paq.push(['setUserId', '${this.context.pageContext.user.loginName}']);` : ``;
+ codeTracker += `_paq.push(['setTrackerUrl', '${this.properties.trackingUrl.replace(/\/\s*$/, '')}/matomo.php']);
  _paq.push(['setSiteId', '${this.properties.trackingSiteId}']);
  `;
 
@@ -184,6 +188,43 @@ export default class MatomoApplicationCustomizer
  }
  }
 
+ /** Get if enable Heart Timer have to be enable
+ * @see https://developer.matomo.org/guides/tracking-javascript-guide#accurately-measure-the-time-spent-on-each-page
+ * @returns True by default and false if specified
+ */
+ private getEnableHeartBeatTimer() {
+ if (this.properties.trackHeartBeatTimer !== undefined && this.properties.trackHeartBeatTimer != null) {
+ switch (this.properties.trackHeartBeatTimer) {
+ case '0':
+ return false;
+ case 'false':
+ return false;
+ default:
+ return true;
+ }
+ } else {
+ return true;
+ }
+ }
+
+ /** Get if the user ID have to be tracked
+ * @see https://developer.matomo.org/guides/tracking-javascript-guide#user-id
+ * @returns False by default and true if specified
+ */
+ private gettTrackUserId() {
+ if (this.properties.trackUserId !== undefined && this.properties.trackUserId != null) {
+ switch (this.properties.trackUserId) {
+ case '1':
+ return true;
+ case 'true':
+ return true;
+ default:
+ return false;
+ }
+ } else {
+ return false;
+ }
+ }
  @override
  public onInit(): Promise<void> {
  Log.info(LOG_SOURCE, `Initialized Matomo Analytics`);