Setup Instructions: SharePoint Online

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.

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 (or use CodeGif)

At a basic level, you need a web server that will host the tracking files and create log files. The web server should create web logs in NCSA Combined format, and you'll want to install a TLS certificate so the tracking files don't trigger security warnings (SPO uses https).

You can setup this web server yourself (any web server is fine) or you can use CodeGif.

CodeGif is a self-hosted product that performs three main functions:

  • hosts the tracking files
  • creates log files
  • securely transfers these logs to your Angelfish instance

To learn more about CodeGif, please contact us.


2) Upload Tracking Files to Collection Server

If you're using CodeGif you can skip this setp - CodeGif automatically creates & uploads the tracking files when you create a Property.

The AGF Tracking Method is used to track SharePoint Online.  You can read more about AGF here:

The Tracking Files (angelfish.js and agf.gif) 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.
  • 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. Enable Office 365 CDN
  2. Upload sppkg file to App Catalog and deploy.
  3. Add the framework extension to a site by using the "Add an app" option for the site.
  4. 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

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`":`"`"}"
  • 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. Enable Office 365 CDN
  2. Upload sppkg to App Catalog and deploy for all sites.
  3. Navigate to app catalog -> site contents -> tenant-wide extensions list.
  4. Edit the list and update the trackingCodeURL variable in the component properties for this extension (replace MYWEBSERVER with the correct hostname):
  • 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




Was this article helpful?
0 out of 0 found this helpful


Article is closed for comments.