Microsoft SharePoint Online (Office 365) integration (deprecated)

Integration for: Microsoft SharePoint Online (Office 365).

When you want to collect data about SharePoint users in your company, you need to integrate Piwik PRO with SharePoint. SharePoint sites can’t be tracked like a regular website, so they need a dedicated setup. The integration takes a few larger steps and may involve a few people from your company, but we’ll try to show you the path as clearly as possible.

Steps

• Install the connector between SharePoint and Piwik PRO
• Set up tracking for a site collection
• Optional: Register new site collections manually (no Microsoft Azure)
• Turn on SharePoint reports in Piwik PRO

Install Piwik PRO components in SharePoint

As the first step, you need to install the connector between SharePoint and Piwik PRO.

To install the connector, follow these steps:

1. Run Windows PowerShell as an administrator in the context of the SharePoint folder in the installation directory.
2. Run the Provision-ToSharePoint.ps1 script and add  the correct parameters.

   Example:

   .\Provision-ToSharePoint.ps1 -SharePointUrl "https://example.sharepoint.com"

3. You’ll see the Piwik PRO connector loaded.
4. In Global configuration, enter the following details:
   • SharePoint version: Online
   • SharePoint URL: Your SharePoint account address. Example: https://example.sharepoint.com.
   • SharePoint admin: A global admin account on your SharePoint tenant. Example: admin@contoso.onmicrosoft.com.
   • SharePoint second admin (optional): An additional admin. They’ll have access to the Piwik PRO connector. Example: admin2@contoso.onmicrosoft.com.

   

5. In the Piwik PRO section, enter the following details:
   • Piwik PRO account address: The address you use to log in to Piwik PRO. Example: https://yourname.piwik.pro.
   • Piwik PRO client ID: A part of your API credentials. You can create it in Menu > Profile > API keys. Where to find it?
   • Piwik PRO client secret: A part of your API credentials. You can create it in Menu > Profile > API credentials. Where to find it?
   • Piwik PRO container address (optional):
     • For standard installation: Keep it empty.
     • For non-standard installation: Enter your Piwik PRO account address with containers added to the address.
       • For standard domains: https://yourname.containers.piwik.pro
       • For custom domains: https://yourname.piwik.pro/containers. This address may be different for Piwik PRO on-premises or private cloud accounts. Contact us to get the right address.

   

6. In SharePoint Online, enter the following information:
   • Include Azure: 
     • For standard installation: Keep it checked. We’ll install the WebJob on your Azure tenant. The WebJob connects Piwik PRO to SharePoint and registers new site collections that can be tracked. 
     • For non-standard installation: Keep it unchecked. If this option is unchecked, you’ll need to register new site collections manually in Piwik PRO.
   • Include SharePoint:
     • For standard installation: Keep it checked. We’ll install all necessary SharePoint resources for tracking your site collections with Piwik PRO.
     • For non-standard installation: You can uncheck it if you want to skip this part of the installation. This can be helpful if you already installed the SharePoint resources earlier and only want to install the Azure WebJob. 
   • Azure tenant: An Azure tenant name or resource group ID.
   • Azure subscription: An Azure subscription name or resource group ID.
   • Azure resource group: The name of a new or existing resource group.
   • Azure WebApp suffix: A suffix added to the web app name. Example: piwikpro<webAppSuffix>. The suffix needs to be globally unique in Microsoft Azure. You can use your company’s name. You can use letters and numbers.
   • Azure location: By default, the resource group is created in the West Europe region or inherits the existing location. You can use a custom location. Example: westeurope, uswest.
   • Use site scope: 
     • For standard installation: Keep it unchecked.
     • For non-standard installation: Keep it checked. The SPFx package will be installed in the site collection app catalog (not in the tenant app catalog) and available only for the site collection specified in the SharePoint URL.

   

7. Click Save and install.
8. After running the script, you’ll be asked to enter your SharePoint credentials.
9. After the script is finished, you’ll see the Piwik PRO Administration site in SharePoint. The SPFx solution will also be deployed.
10. For standard installation: The script that creates Azure part installation will ask you to log in using SharePoint Online (Office 365) tenant account. To configure app registrations, generate a certificate.
11. For standard installation: The script will then ask you to log in using the Azure account. It’ll deploy WebJob.
12. Check the status in portal.azure.com > Log in as a SharePoint tenant admin > App Registrations > Piwik PRO > API permissions.

    

13. If the status is not granted, click Grant admin consent.
14. Done! The Piwik PRO connector is all set up. 

Set up tracking for a site collection

As the second step, you need to turn on tracking for a site collection in SharePoint. A site collection is SharePoint’s name for something similar to a website. It’s a group of sites that have the same owner and share administrative settings.

To turn on tracking for a site collection in SharePoint, follow these steps:

1. Log in to SharePoint.
2. Navigate to the site collection that you want to work with.
3. Click on the settings wheel in the menu bar.
4. Choose Piwik PRO settings.

   

   Note: This setting is visible only to Site Collection Administrator in SharePoint.

5. In Site collection settings, check Enable tracking.

   

   Note: It may take up to 30 minutes for tracking to start off because SharePoint’s search crawl needs to notice changes in settings. Also you may need to empty a browser cache because it stores tracker settings for 1 hour, or you can wait for it to refresh.

6. To check if tracking for a site collection is active, look for User information under Piwik PRO Settings. This section will only appear if tracking has started.

   

7. You can also check the tracking status on SharePoint’s administration site: <your SharePoint URL>/sites/PiwikAdmin > Site contents > Piwik PRO site directory.

   

   Note: Active means that Piwik PRO tracks the site collection. The tracked site collection will be automatically added as a new site to Piwik PRO.

8.  In User information, you can choose to anonymize user IDs and collect additional data:

   

   • Send User ID anonymized: Users will still be recognized, but we’ll hide their ID.
   • Send extended user information: Check if you want to collect additional user data as custom dimensions in Piwik PRO Analytics:
     • Username (display name)
     • Office
     • JobTitle
     • Department
9. You can also change settings for all sites at once in Global Settings.

   

Optional: Register new site collections manually (no Microsoft Azure)

When you don’t have a Microsoft Azure subscription, you can use this dedicated setup to register new site collections manually.

To register a new site collection manually, follow these steps:

1. Contact us at support@piwik.pro, and we’ll send you a package with the site activator script.
2. Make sure you’ve enabled tracking for your site collection in SharePoint > Settings wheel > Piwik PRO settings >  Site collection settings > Enable tracking. Read more
3. Run the PiwikPROSitesActivator.exe script from your command line.
4. Enter your SharePoint account address on the screen. For example:

   Provide your SharePoint URL (example: https://contoso.sharepoint.com).

   Tip: The script will remember this address in the next runs.

5. Optionally, add your credentials for multi-factor authentication in SharePoint.
6. Now the script will check if site collections need to be activated or deactivated. It’s based on your settings from step 2.

   

7. Once the script has finished, your site collections are tracked (or stopped) in Piwik PRO.

Turn on SharePoint reports in Piwik PRO

As the last step, you only need to turn on SharePoint reports in Piwik PRO.

To turn SharePoint reports on, follow these steps:

Available from version 16.0.0. For versions below 16.0.0, go to Menu > Administration > Websites & apps > Settings > Integrations.

1. Go to Menu > Administration.
2. Select a website you want to work with.
3. Navigate to Reports.
4. Turn on Show SharePoint reports.

   

5. Now SharePoint reports will appear under Analytics > SharePoint.

   

   Tip: Read more about SharePoint reports.