CX Documentation
Umbraco Documentation

Table of Contents

Health Check Script

Umbraco Engage Health Check Script

Script

A browser console script to verify that Umbraco Engage is properly configured and functioning on your website.

Note: Headless Engage setups are not supported.

Overview

This script performs automated checks to ensure that Umbraco Engage is correctly installed and configured. It validates critical configuration aspects and optional features.

Features

The script checks:

  1. ✅ Ping Script Available - Verifies the ping script is present in the HTML

  2. ✅ Ping Endpoint - Tests the /umbraco/engage/pagedata/ping endpoint (should return 204)

  3. ✅ Output Caching - Confirms output caching is disabled by comparing pageviewIds

  4. 📊 Client-Side Analytics - Checks if analytics script is installed (recommended)

  5. 📊 Analytics Loaded - Verifies the analytics script loaded properly

  6. 🔧 GA Blocker Detection - Optional feature check

  7. 🔧 GA4 Bridge - Optional feature check

Usage

Step 1: Open Your Website

Navigate to the website you want to check in your browser.

Step 2: Accept Cookies

If a cookie consent banner appears, accept all cookies.

Step 3: Reload the Page

Reload the page to ensure all scripts are loaded.

Step 4: Open Developer Console

  • Windows/Linux: Press F12 or Ctrl+Shift+J

  • Mac: Press Cmd+Option+J

Step 5: Run the Script

  1. Copy the entire content of umbraco-engage-healthcheck.js file

  2. Paste it into the console

  3. Press Enter

Step 6: Review Results

The script will output a table showing the results of each check.

  • TRUE = Check passed ✅

  • FALSE = Check failed ❌

Interpreting Results

Critical Checks (Must be TRUE)

  • 1_Ping_Script_Available: The Engage ping script must be present

  • 2_Ping_Successful: The ping endpoint must respond with status 204

  • 3_OutputCachingDisabled: Different pageviewIds should be returned on each request

If any of these return false, Umbraco Engage will not function correctly.

Recommended Check

  • 4_ClientSideAnalyticsScript_Installed_OPTIONAL: Required for client-side analytics (time on page, scroll depth, etc.)

  • 5_ClientSideAnalyticsScript_Loaded_Only_If_4_is_installed: Confirms the analytics script loaded successfully

Optional Checks

  • 6_GA_BlockerDetection_Script_Installed_OPTIONAL: For detecting ad blockers

  • 7_GA4_Bridge_Script_Installed_OPTIONAL: For Google Analytics 4 integration

Troubleshooting

Ping Endpoint Returns False

  • Ensure the /umbraco/engage/pagedata/ping endpoint is accessible

  • Check firewalls or network restrictions that might block the endpoint

  • See: Bot Detection Ping Documentation

Output Caching Returns False

  • Disable output caching on your CDN for pages using Umbraco Engage

  • Each request must generate a unique pageviewId

  • See: CDN Recommendations

Checking the Visitor Cookie

The script cannot check for the umbracoAnalyticsVisitorId cookie due to browser security restrictions. You must check this manually:

Chrome/Edge

  1. Open Developer Tools (F12)

  2. Go to the Application tab

  3. In the left sidebar, expand Cookies under Storage

  4. Click on your website's domain

  5. Look for umbracoAnalyticsVisitorId in the cookie list

Firefox

  1. Open Developer Tools (F12)

  2. Go to the Storage tab

  3. Expand Cookies in the left sidebar

  4. Click on your website's domain

  5. Look for umbracoAnalyticsVisitorId

The cookie should be present for Umbraco Engage to function properly.

Requirements

  • Umbraco Engage installed on your Umbraco website

  • Modern web browser with developer console access

  • Cookie consent given (if applicable)

License

MIT License - Feel free to use and modify as needed.

Resources


There is also a video that explains how to use this, see it here:
https://drive.google.com/file/d/1pOSRrhiNjiCziKBexCN7v8uIJWsvo8zA/view