Manual Install Web Tracking and Config

Manual installation - stage 3 of 3. Prev: 2. Deploy the binaries | Overview

Deploy AITracker

Once Application Insights is setup & we have the AITrackerInstaller source, we need to deploy the Microsoft 365 Advanced Analytics Engine AITracker.js file to the SharePoint Online sites we want to track users on.

There are two ways to do this:

• Recommended — use the installer. Even in an otherwise manual deployment, the installer's SharePoint tab does this step for you: it signs you in through your browser, uploads and tenant-deploys the SPFx package to the app catalog, and stapes AITracker.js onto each site collection you list. See Install with the installer → SharePoint.
• PowerShell — for SharePoint Server on-premises, or to script deployment to new site collections later.

Note: this method can also be used later to automate the deployment to new SharePoint Online sites.

Deploy AITracker via PowerShell

Download AITrackerInstaller.zip from the builds website, and extract to your PC if you don’t have it already.

1. Open the Microsoft 365 Advanced Analytics Engine build folder, then "Scripts.AITrackerInstaller".

2. Create/edit the install json config file used by the PowerShell install script (DevConfig.json for example – edit or create your own).

3. Change mandatory values in your new configuration file:

   1. TargetSites – a JSon array of the root sites (all sub-sites will be included automatically) to deploy to. Important – URL is the root-site URL only, with no trailing backslashes or pages/lists. See example config files shipped with the script.
   2. ApplicationInsightsKey – the "instrumentation key" for the Application Insights application created.
   3. The other keys can be changed if desired but aren’t critical.

4. Run the script for your target, passing the config filename as a parameter:

   .\InstallSPOInsightsTracker.PnP.ps1 -ConfigFileName "MyConfig.json"

   • InstallSPOInsightsTracker.PnP.ps1 — SharePoint Online. Uses a web login, so no username is read from the configuration file, and it works with MFA.
   • InstallSPOInsightsTracker-OnPrem.ps1 — for SharePoint Server on-premises.

Note: you may need to unblock the script for it to run:

AITracker uploads results to Application Insights to track "page views" and "custom events", containing the time the users spent on the previous page. Accurate time-tracking for users on pages is not standard Application Insights functionality.

When it works, the script reports that AITracker.js was uploaded to the site-collection root and that referencing custom-actions were inserted in all sub-sites.

The older InstallSPOInsightsTracker.ps1 script (username + password, with a saved SecureString.txt) is retained but will fail against SharePoint Online, which no longer accepts basic authentication. Its full walkthrough and sample output are preserved on Legacy SPO web setup.

Deploy Modern UI Extension to App Catalog

In order that modern sites load the AITracker too, we have a SharePoint Framework (SPFx) Extension that needs to be deployed to the SharePoint app catalogue.

Upload spoinsights-modern-ui-aitracker.sppkg, and you’ll be prompted with this dialogue:

Important: ensure this option is selected. This does not deploy the analytics solution to all sites but makes it available to "staple" (activate) – done by the PowerShell on the sites you select only.

Verify the extension is loaded once you’ve run the PowerShell/installer by checking the JavaScript console on a SharePoint site page:

Messages from this solution can be seen in the JavaScript console in sites where the PowerShell has added the tracker, prefixed with "SPOInsights ModernUI".

On a site not targeted by the PowerShell/installer stage, you will see no messages of this type.

Configure Reply URLs for Azure AD Runtime Application

Part of the solution is an ASP.Net administration website that is protected with Azure AD. So that access to the administration website login works, the reply URLs need to be set in your runtime account in Azure AD.

For the full walkthrough — exact URL format, token settings, multiple environments and troubleshooting — see Runtime app reply URLs.

Under the runtime account in Azure AD, in "authentication" settings of the application registration ensure the URL matches exactly the root address of your app-service URL:

This value needs to be set to what was picked for your service-app URL:

Important: enable access tokens & ID tokens on the same page.

See below to check if these settings are correct & valid.

Configure Filtered URLs

All SharePoint data for any import is ignored if it’s outside the scope of the org_urls table in the SQL database.

In this table the only important fields are url_base and exact_match.

"Exact match" is used to limit URLs accepted as only that site-collection, rather than a "starts-with" filter.

With the above table contents, valid & imported URLs would be:

• https://m365x72460609.sharepoint.com/sites/Comms/SitePages/Home.aspx
• https://m365x72460609.sharepoint.com/sites/Comms/subsite1/SitePages/MyInfo.aspx
• https://m365x72460609.sharepoint.com/SitePages/Intranet.aspx
• https://m365x72460609.sharepoint.com/Documents/Welcome.docx

Ignored URLs would be:

• https://m365x72460609.sharepoint.com/sites/HR/Intranet.aspx (root site demands exact match).

If you’re not seeing data from any given site, ensure that there’s an entry in this table for that root site-collection URL.

---

Manual installation complete. Now verify the deployment.