SharePoint Online: Collection Server & SPFx
This article provides setup instructions for tracking SharePoint Online with the Collection Server & SPFx method.
Angelfish has two methods for tracking SharePoint Online: both are explained in this help article:
OVERVIEW: Collection Server & SPFx Method
- Angelfish is self-hosted analytics software that creates reports from access logs
- SharePoint Online (SPO) is a SaaS application
- Microsoft doesn't provide access logs for SPO
- You can create your own access logs with a simple web server and a SP Framework Extension
- Tracking data is sent to the web server and Angelfish reads the web server's access logs
- Angelfish can track SharePoint Online in the following environments
- Microsoft 365 Commercial
- GCC (Government Community Cloud)
- GCC High
- DoD Government
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 with this method.
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 uses one of the following Log Formats to create access logs:
- W3C (with default fields)
- IIS
- NCSA Combined
If these Log Formats are not available in your Collection Server, here are the fields the 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 questions about 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. 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.
3) Upload SharePoint Framework Extension 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 with 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):
Connect-PnPOnline -Url https://MYCORP.sharepoint.com/sites/MYSITE
- 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 values for -Name and -Title
- ClientSideComponentId is a static value that identifies the sppkg
- Update the value for trackingCodeURL with the full URL path to angelfish.js on the Collection Server
- You can 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.
- You can rename angelfish.js - be sure to update trackingCodeURL with the new filename
- Update the value for trackingCodeURL with the full URL path to angelfish.js on the Collection Server
{"trackingCodeURL":"https://MYWEBSERVER.com/path/to/angelfish.js"}
Verify Installation
Once the Collection Server is online and the SPFx File is uploaded and configured, you should verify things are working correctly. Use either of the below methods:
From Your Browser
- open your browser's Developer Tools (press the F12 key, or open it from the browser menu)
- select the Network tab
- load a Page in your SPO website: you should see separate requests for angelfish.js and agf.gif
From the Collection Server
- tail the current access log
- open a Page in your SPO website in a browser
- you should see separate hits for angelfish.js and agf.gif in the access log
Next Steps
Once the access logs are successfully created, you can process them in Angelfish.
Simply create a new Profile that uses the AGF Tracking Method and process the logs from the Collection Server.
Angelfish can directly download logs off the Collection Server via SFTP, FTP, or UNC. Just create a Datasource and choose the appropriate Datasource Type.
Alternatively, you can independently copy the access logs to a location where your Angelfish instance can read them.
We don't recommend installing Angelfish directly on the Collection Server.
HELPFUL LINKS
Get help for this page
Jitbit HelpDesk