Manual Install Web Tracking and Config

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

Deploy AITracker via PowerShell

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.

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

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

To deploy AITracker.js to SharePoint site-collection(s):

1. Open the Microsoft 365 Advanced Analytics Engine build folder, then "Scripts.AITrackerInstaller".
2. Create/edit install json config file used by the PowerShell install script in the configuration file (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. AdminUsername – a user ID with site-collection admin rights to the target site-collection (not needed for PnP PowerShell version)
   3. ApplicationInsightsKey – the "instrumentation key" for the Application Insights application created.
   4. The other keys can be changed if desired but aren’t critical.

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

Run one of the scripts to deploy, depending on target needs, passing config filename as a parameter:

• InstallSPOInsightsTracker.ps1 to install AITracker.js to SharePoint Online site-collections(s). Use this one by default if the SharePoint account isn’t strictly limited to multi-factor authentication logins.
• InstallSPOInsightsTracker-OnPrem.ps1 for on-premises SharePoint.
• InstallSPOInsightsTracker.PnP.ps1 for SharePoint Online with multi-factor authentication (MFA) enabled. This uses a web-login, so no username is read from the configuration file.

Example

1. Example execution:

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

2. The first time it runs, it’ll need to save credentials in a secure-string file. A login box will appear; use the same username as configured in AdminUsername, set the password and click "OK".

   

   The script will test if the user has site-collection admin rights. If it does it’ll save the credentials in a secure string.

   ERROR: Problem reading password cipher from SecureString.txt. Please enter the password for <admin@M365x246423.onmicrosoft.com> in a sec...
   
   Refreshing secure-string file - please enter credentials
   
   Updated .\\SecureString.txt with refreshed password
   
   SUCCESS! .\\SecureString.txt updated with new password hash. Please run the script again & hopefully it'll work now!
   
   Couldn't upload tracker JS - see above!

3. Run the PowerShell script again to now successfully install the tracker.

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.

Read configuration for environment name 'Development M365x246423 - <sambetts@microsoft.com>'...

Read encrypted password from .\\SecureString.txt. Installing AITracker.js...

Checking if <https://M365x246423.sharepoint.com/sites/spoinsights/Style%20Library/AITracker.js> exists...

AITracker.js doesn't exist for user <admin@M365x246423.onmicrosoft.com>!

AITracker.js uploaded to <https://M365x246423.sharepoint.com/sites/spoinsights/Style%20Library/AITracker.js>

File is checked-out. Checking in major version of AITracker.js...

Setting custom-action on all subsites to include AITracker.js in the HTML header...

Checking SPWeb.UserCustomActions...

Inserted custom-action into web: '<https://m365x246423.sharepoint.com/sites/spoinsights>'...

Checking sub-webs for site 'Microsoft 365 Advanced Analytics Engine Classic'...

18:39:04 - AITracker.js uploaded to site-collection root & referencing custom-actions inserted in all sub-sites!

This is what you should see if it worked.

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.