SharePoint Online: Tracking Server & SPFx
This article provides setup instructions for tracking SharePoint Online with the Tracking Server & SPFx method.
OVERVIEW
- Angelfish is self-hosted analytics software that creates reports from access logs
- Microsoft doesn't provide access logs for SPO
- This solution uses a simple web server and a SP Framework Extension to create access logs
- Tracking data is sent to the web server and Angelfish reads the web server's access logs
- The AGF Tracking Method is used with this solution.
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.
Setup Steps
1) Setup a Tracking 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 Tracking Server needs a TLS certificate so the Tracking Files don't trigger security warnings (SPO uses https).
We recommend the Tracking 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 Tracking 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 Tracking Server.
2) Upload AGF Tracking Files to Tracking Server
"AGF Tracking Files" means these two files:
- angelfish.js
- agf.gif
The AGF Tracking Files must be stored on the Tracking 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 - Tracking Server Hostname:
- enter the hostname of the Tracking 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 Tracking 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 Tracking 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 Tracking Server
{"trackingCodeURL":"https://MYWEBSERVER.com/path/to/angelfish.js"}
Verify Installation
Once the Tracking 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 Tracking 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 Tracking Server.
Angelfish can directly download logs off the Tracking 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 Tracking Server, as you don't want a large data operation to affect the server's ability to respond to HTTP requests.
HELPFUL LINKS