Setup Instructions: SharePoint Online

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

  • Angelfish is a self-hosted analytics software that creates reports from web server logs.
  • SharePoint Online (SPO) is a SaaS application
  • 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
  • In other words, you create your own logs
  • Angelfish can track SharePoint Online in the following environments
    • Microsoft 365 Commercial
    • GCC (Government Community Cloud)
    • GCC High

This solution is self-hosted and requires a bit of setup. However the tracking and report data never leaves your environment, which lets you maintain data security and access control.  

The AGF Tracking Method is used to track SharePoint Online.

Setup Steps


1) Setup a Collection Server

You need a simple web server that provides two functions:
  • host the AGF Tracking Files 
  • 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 the Collection Server creates log files in one of the following Log Formats:
  • W3C (with default fields)
  • IIS
  • NCSA Combined

If these 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

It's a good idea to use a daily or hourly log rotation, and use a YYYYMMDD date stamp in the filename.  If hourly, use YYYYMMDDHH.

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


2) Upload AGF Tracking Files to Collection Server

"AGF Tracking Files" means these two files:
  • angelfish.js
  • agf.gif

The AGF Tracking Files must be stored on the Collection Server, in the same directory of the web server.  Both Tracking Files should be accessible via a URL.

Download the AGF Tracking Files from the Custom Tracking Code Generator page.  Before downloading, be sure to customize the following fields:

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 the Tracking Files reside in a different folder than the website root
  • e.g. /files/tracking/agf.gif

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 .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.

The SP 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 deployments.

Site-Wide Configuration (apply framework to a single site)
  • Upload the sppkg file to App Catalog and deploy.
  • Add the framework extension to a site by using the "Add an app" option for the site.
  • Use powershell to add a custom user action that sets the client side properties for the extension on that site:
    • Connect to site (replace MYCORP and MYSITE with your site details):


    • Add custom action (replace MYWEBSERVER with Collection Server 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`"}"

Notes
  • 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
  • If you rename angelfish.js be sure to update trackingCodeURL with the new filename


Tenant-Wide Configuration (apply framework to all sites)

  • Upload sppkg to App Catalog and deploy for all sites.
  • Navigate to app catalog -> site contents -> tenant-wide extensions list.
  • 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"}

Notes
  • 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 can open a browser console (press the F12 key) and see requests for angelfish.js and agf.gif in the Network tab.

Next Steps


Once the logs are successfully created, you can process them in Angelfish.

Angelfish can download the logs off the Collection Server via SFTP, FTP, or UNC - simply create a Datasource and choose the appropriate Log Location Type.

We don't recommend installing Angelfish directly on the Collection Server unless the server is on a private network.

HELPFUL LINKS
Creation date: 5/18/2022 5:07 PM (Angelfish Support)      Updated: 5/21/2022 4:22 PM (Angelfish Support)