Sharepointcms Troubleshooting: Common Issues and Fixes | OpsBlu Docs

Sharepointcms Troubleshooting: Common Issues and Fixes

Debug analytics issues on SharePoint — SPFx web part injection, tenant-level script policies, modern vs classic page differences, and Microsoft 365 CDN...

SharePoint (as a CMS for public-facing or intranet sites) has unique analytics constraints imposed by Microsoft's security model. You cannot freely inject JavaScript on modern SharePoint pages. Analytics integration requires SPFx (SharePoint Framework) extensions, tenant-level custom script settings, or the built-in Microsoft Clarity/Application Insights integration.

SharePoint-Specific Debugging Approach

SharePoint Online and SharePoint Server have different capabilities. Modern SharePoint pages block inline scripts by default — this is the number one source of analytics failures.

Check Custom Script Policy

// In browser console on your SharePoint site
// Check if custom scripts are allowed
console.log('Custom scripts:', _spPageContextInfo?.allowCustomScript || 'check tenant settings');
console.log('Site type:', _spPageContextInfo?.isModernPage ? 'Modern' : 'Classic');

// Check for SPFx extensions
console.log('SPFx extensions:', document.querySelectorAll('[data-sp-feature-tag]').length);

Verify Tenant-Level Settings

For SharePoint Online, custom scripts must be enabled at the tenant level:

# PowerShell (SharePoint Online Management Shell)
Connect-SPOService -Url https://yourtenant-admin.sharepoint.com
Get-SPOSite -Identity https://yourtenant.sharepoint.com/sites/yoursite | Select CustomScriptSafeDomains

# Check if NoScript is set (blocks custom scripts)
Get-SPOSite -Identity https://yourtenant.sharepoint.com/sites/yoursite | Select DenyAddAndCustomizePages
# DenyAddAndCustomizePages = Enabled means custom scripts are BLOCKED

Most Common SharePoint Analytics Issues

1. Modern Pages Blocking All Custom JavaScript

Symptoms: Analytics code added via Script Editor web part does not execute. No errors visible but tracking never fires.

Root cause: SharePoint modern pages enforce the NoScript policy by default. Inline JavaScript, Script Editor web parts, and Content Editor web parts with scripts are all blocked on modern pages.

Fix: Use one of these approved methods:

# Method 1: SPFx Application Customizer (recommended)
# Build a custom SPFx extension that injects analytics
# This is the Microsoft-approved way to add scripts to modern pages

# Method 2: Enable custom scripts (reduces security)
# SharePoint Admin Center > Settings > Custom Script
# Or via PowerShell:
Set-SPOSite -Identity https://yourtenant.sharepoint.com/sites/yoursite -DenyAddAndCustomizePages 0
# WARNING: Takes up to 24 hours to take effect

SPFx Application Customizer approach:

// In your SPFx extension's onInit method
export default class AnalyticsApplicationCustomizer extends BaseApplicationCustomizer {
  public onInit(): Promise<void> {
    const script = document.createElement('script');
    script.async = true;
    script.src = 'https://www.googletagmanager.com/gtag/js?id=G-XXXXXXX';
    document.head.appendChild(script);

    window.dataLayer = window.dataLayer || [];
    function gtag(...args: any[]) { window.dataLayer.push(args); }
    gtag('js', new Date());
    gtag('config', 'G-XXXXXXX');
    return Promise.resolve();
  }
}

2. Classic vs Modern Pages Having Different Tracking

Symptoms: Analytics works on classic pages but not modern pages, or vice versa.

Root cause: Classic SharePoint pages allow Script Editor web parts and inline JavaScript. Modern pages do not. If your site has a mix of classic and modern pages, only one type may have working analytics.

Fix: Use an SPFx Application Customizer that runs on both page types, or ensure all pages are converted to the same type.

3. Microsoft 365 CDN Caching SPFx Extensions

Symptoms: Updated SPFx analytics extension deployed but the old version still loads for users.

Root cause: SharePoint uses the Microsoft 365 CDN (or a private CDN) to serve SPFx assets. CDN cache TTL can be 24+ hours.

Fix:

# Force CDN cache refresh
# In SharePoint Online Management Shell:
Set-SPOTenantCdnEnabled -CdnType Public -Enable $true
# This does not clear cache, but forces a re-evaluation

# Better approach: version your SPFx package
# Update the version in package-solution.json before deploying

4. SPA Navigation in Modern SharePoint Not Tracked

Symptoms: Only the first page load fires analytics. Navigating between modern pages produces no additional pageviews.

Root cause: Modern SharePoint uses client-side page transitions (SPA behavior). Traditional pageview tracking misses these transitions.

Fix: In your SPFx Application Customizer, listen for SharePoint navigation events:

// In your SPFx extension
import { SPEventArgs } from '@microsoft/sp-core-library';

this.context.application.navigatedEvent.add(this, (args: SPEventArgs) => {
  gtag('event', 'page_view', {
    page_path: window.location.pathname,
    page_title: document.title
  });
});

5. Intranet vs Public Site Analytics Separation

Symptoms: Internal employee traffic is mixed with public website visitor data.

Root cause: SharePoint is used for both intranets and public-facing communication sites. If the same GA property tracks both, internal and external traffic gets mixed.

Fix: Use separate GA properties or filter by authentication status:

// Detect authenticated SharePoint users
var isInternalUser = _spPageContextInfo?.userId > 0;
var gaPropertyId = isInternalUser ? 'G-INTERNAL' : 'G-PUBLIC';
gtag('config', gaPropertyId);

Environment Considerations

  • SharePoint Online vs On-Premises: Online has stricter script policies. On-premises SharePoint Server allows more customization but may lack modern page support
  • Microsoft 365 compliance: Enterprise SharePoint deployments may have DLP (Data Loss Prevention) policies that block external analytics scripts
  • Azure AD authentication: SharePoint uses Azure AD. All logged-in users have an identity, which affects how you filter internal vs external traffic
  • Hub sites: SharePoint hub sites aggregate multiple site collections. Analytics may need to span hub sites while maintaining per-site granularity
  • Power Automate: SharePoint integrates with Power Automate flows. Consider using flows for server-side analytics event tracking as an alternative to client-side scripts

Performance Issues

  • LCP Issues - SPFx extension loading and Microsoft 365 CDN latency
  • CLS Issues - Layout shifts from web part rendering and modern page SPA transitions

Tracking Issues

  • Events Not Firing - Debug NoScript policies, SPFx deployment, and SPA navigation tracking
Nach oben