Setup Instructions: SharePoint Online

If you use Angelfish Software v2.4+, please use the new Help Center:
https://help.angelfishstats.com/helpdesk/?aa=200

 

How to Track SharePoint Online (SPO) websites with Angelfish

You can use Angelfish to track any SaaS application, like SharePoint Online. Here's how it works:

• Angelfish is a self-hosted analytics tool that creates reports from web server logs.
• SharePoint Online (SPO) is a SaaS application, and Microsoft doesn't provide access to the SPO web server logs.
• You can collect your own tracking data from SPO and process it with Angelfish - basically, you create your own logs.

Angelfish can track SharePoint Online in the Microsoft 365 Commercial environment, and in the GCC (Government Community Cloud) & GCC High environments.

This solution is self-hosted so it requires a bit of setup. However the tracking and report data never leaves your environment, which lets you maintain data security and access control.  This will become more important as GDPR | CCPA | data privacy regulations continue to increase.

Setup Steps 

1) Setup a Collection Server

At a basic level, you need a web server that will host the Tracking Files and create log files that Angelfish can process.  You can setup this web server yourself - any web server is fine as long as it creates access logs that Angelfish can process.

The Collection Server needs a TLS certificate so the Tracking Files don't trigger security warnings (SPO uses https).

We recommend that the Collection Server uses one of the following Log Formats:

• W3C (with default fields)
• IIS
• NCSA Combined

If these defined Log Formats are not available in your Collection Server, here are the fields a custom log format should contain:

• IP Address
• Date & Time
• cs-request (or Method, Request Stem, Request Query)
• User Agent
• Referrer
• Status Code
• Bytes

Please open a support ticket if you have any questions about custom log formats in the Collection Server.

 

2) Upload Tracking Files to Collection Server

The AGF Tracking Method is used to track SharePoint Online.  You can read more about AGF here:
https://support.angelfishstats.com/hc/en-us/articles/231569748

"Tracking Files" means these two files:

• angelfish.js
• agf.gif

The Tracking Files must be stored on the Collection Server setup in step 1. The files should be placed in the same directory on the web server, and both should be publicly accessible via a URL.

You can download the Tracking Files from the Custom Tracking Code Generator page but you'll want to customize the following fields in angelfish.js first:

• Gif Info - Collection Server Hostname:  enter the hostname of the Collection Server created in Step 1 (e.g. www.yoursite.com)
• Gif Info - Tracking File Path & Name:  this only needs to be changed if agf.gif resides in a different folder than the website root.  e.g. /files/tracking/agf.gif
• LinkTagger: when enabled, LinkTagger automatically tracks outbound links.  Click the tooltips (gray question marks) in the code generator for more info.

Once the changes are made, click the button at the bottom of the page to download angelfish.js.  You can download agf.gif via the link at the top of the code generator page.

 

3) Upload SharePoint Framework Extension (.sppkg file) to SP Online

The framework extension adds the tracking code reference to your pages. Once uploaded, you must configure the extension to use the correct location for the tracking files.

We have framework extensions for tenant-wide and site-wide deployment.

The .sppkg files are not linked on this page - please open a support ticket and let us know which one you need, and we'll send it to you. 

Site-Wide Configuration (apply framework to a single site)

1. Upload the sppkg file to App Catalog and deploy.
2. Add the framework extension to a site by using the "Add an app" option for the site.
3. Use powershell to add a custom user action that sets the client side properties for the extension on that site:

a) connect to site (replace MYCORP and MYSITE with your site details):

Connect-PnPOnline -Url https://MYCORP.sharepoint.com/sites/MYSITE

b) add custom action (replace MYWEBSERVER with the correct hostname):

Add-PnPCustomAction -Name "Angelfish Tracking MYSITE" -Title "Angelfish Tracking" -Location "ClientSideExtension.ApplicationCustomizer" -ClientSideComponentId 91319ec7-c16f-4a9c-9348-c47034096fa9 -ClientSideComponentProperties "{`"trackingCodeURL`":`"https://MYWEBSERVER.com/path/to/angelfish.js`"}"

• You can rename the -Name and -Title values if you prefer
• ClientSideComponentId is a static value that identifies the sppkg
• The trackingCodeURL variable stores the URL where angelfish.js is hosted
• You can rename angelfish.js - be sure to update trackingCodeURL with the new filename

 

Tenant-Wide Configuration (apply framework to all sites)

1. Upload sppkg to App Catalog and deploy for all sites.
2. Navigate to app catalog -> site contents -> tenant-wide extensions list.
3. Edit the list and update the trackingCodeURL variable in the component properties for this extension (replace MYWEBSERVER with the correct hostname):

   {"trackingCodeURL":"https://MYWEBSERVER.com/path/to/angelfish.js"}

• The trackingCodeURL variable stores the URL where angelfish.js is hosted
• You can rename angelfish.js - be sure to update trackingCodeURL with the new filename

 

If everything is working correctly, you should be able to open a browser console (press the F12 key) and see requests for angelfish.js and agf.gif in the Network tab.

 

Next Steps

 

Configuration Tips for SharePoint Profiles