Google Maps Error Handling Documentation

Overview

This document describes the robust error handling implementation for Google Maps API integration on public event pages. The solution ensures that event pages load successfully even when Google Maps API is unavailable or fails to load.

Problem Statement

Previously, when the Google Maps API failed to load or was slow to initialize, the public event page would encounter JavaScript errors that could block page functionality:

Uncaught TypeError: Cannot read properties of undefined (reading 'addDomListener')
Uncaught TypeError: google.maps.LatLng is not a constructor

These errors prevented the event page from loading correctly and resulted in a poor user experience.

Solution

1. Strict API Validation

Location: resources/views/visual-aspect/show-public.blade.php The initMap() function now performs strict validation before attempting to initialize the map:

function initMap() {
    // Check if Google Maps API core constructors are present
    if (typeof google === 'undefined' || typeof google.maps === 'undefined' ||
        typeof google.maps.Map === 'undefined' || typeof google.maps.LatLng === 'undefined') {
        // Show non-blocking error message
        var errorEl = document.getElementById('google-map-error');
        if (errorEl) {
            errorEl.classList.remove('d-none');
        }
        return;
    }
    // ... continue with map initialization
}

Key Points:

Validates presence of google, google.maps, google.maps.Map, and google.maps.LatLng
Does not attempt initialization if core constructors are missing
Displays user-friendly error message instead of throwing exceptions

2. Exception Handling

All map creation and marker placement operations are wrapped in try-catch blocks:

var map;
try {
    map = new google.maps.Map(mapContainer, mapOptions);
} catch (err) {
    var errorElInit = document.getElementById('google-map-error');
    if (errorElInit) {
        errorElInit.classList.remove('d-none');
    }
    return;
}

This prevents uncaught exceptions from breaking the page.

3. Non-Blocking Error UI

HTML Addition:

<div id="google-map-error" class="alert alert-warning mt-2 d-none" role="alert" aria-live="polite">
    {{ __('event.map_unavailable', ['default' => 'Map temporarily unavailable. The event information is still available below.']) }}
</div>

Features:

Hidden by default (d-none class)
Revealed when map fails to load
Non-blocking: event information remains accessible
Accessibility-friendly with role="alert" and aria-live="polite"

4. Enhanced Polling Mechanism

Location: resources/views/visual-aspect/show-public.blade.php

function waitForGoogleMaps() {
    if (typeof google !== 'undefined' && typeof google.maps !== 'undefined' && typeof google.maps.Map !== 'undefined') {
        initMap();
    } else {
        // Listen for custom Google Maps loaded event
        window.addEventListener('google-maps-loaded', function() {
            initMap();
        }, { once: true });

        // Fallback: check periodically for Google Maps to load
        var checkInterval = setInterval(function() {
            if (typeof google !== 'undefined' && typeof google.maps !== 'undefined' && typeof google.maps.Map !== 'undefined') {
                clearInterval(checkInterval);
                initMap();
            }
        }, 100);

        // Stop checking after 10 seconds
        setTimeout(function() {
            clearInterval(checkInterval);
            // If still not loaded, reveal error but keep page functional
            var errorElTimeout = document.getElementById('google-map-error');
            if (errorElTimeout && (typeof google === 'undefined' || typeof google.maps === 'undefined' || typeof google.maps.Map === 'undefined')) {
                errorElTimeout.classList.remove('d-none');
            }
        }, 10000);
    }
}

Features:

Multiple detection strategies (immediate, event-based, polling)
10-second timeout with graceful degradation
Error message display after timeout
Page remains fully functional regardless of map status

5. Safe Stub for script.min.js

Location: resources/views/layouts/events.blade.php A minimal stub is created before loading script.min.js to prevent errors from addDomListener calls:

(function() {
    try {
        // Only create a minimal stub for the event namespace to avoid breaking addDomListener calls
        if (typeof window.google === 'undefined') {
            window.google = {};
        }
        if (typeof window.google.maps === 'undefined') {
            window.google.maps = {};
        }
        if (typeof window.google.maps.event === 'undefined') {
            window.google.maps.event = {
                addDomListener: function() {
                    // No-op until real Google Maps loads
                }
            };
        }
    } catch (e) {
        // Silently handle errors
    }
})();

Important:

Only stubs the event namespace, not constructors
Prevents premature initialization attempts
Does not interfere with validation checks in initMap()
Allows legacy scripts to call addDomListener safely

User Experience

When Google Maps Loads Successfully

Map displays normally with event location marker
No error messages shown
Full interactive map functionality

When Google Maps Fails to Load

Event page loads completely and remains functional
Warning message appears in map container: “Map temporarily unavailable. The event information is still available below.”
All event information, pricing, and booking functionality remain accessible
No JavaScript errors in console
Page does not break or hang

Localization

The error message supports localization through Laravel’s translation system: Key: event.map_unavailable Default: “Map temporarily unavailable. The event information is still available below.” To customize the message, add the key to your language files:

// lang/en/event.php
'map_unavailable' => 'Map temporarily unavailable. The event information is still available below.',

// lang/es/event.php
'map_unavailable' => 'Mapa temporalmente no disponible. La información del evento sigue disponible a continuación.',

Files Modified

resources/views/visual-aspect/show-public.blade.php
- Enhanced initMap() with strict validation
- Added try-catch blocks around map creation
- Added error message UI element
- Enhanced waitForGoogleMaps() with timeout handling
resources/views/layouts/events.blade.php
- Added minimal safe stub for google.maps.event.addDomListener
- Wrapped stub in IIFE for isolation
- Positioned before script.min.js load

Testing Scenarios

Manual Testing

Normal Load: Open event page with normal internet connection
- Expected: Map loads and displays correctly
Slow Connection: Throttle network to simulate slow API load
- Expected: Page loads, polling continues, map appears when API ready
API Blocked: Block maps.googleapis.com in browser
- Expected: Page loads, error message appears after 10s, page remains functional
API Error: Simulate API key error (403)
- Expected: Page loads, error message appears, booking remains accessible

Browser Console Tests

// Test 1: Verify stub exists before API loads
console.log(typeof google.maps.event.addDomListener); // Should be 'function'

// Test 2: Verify error handling
// (Block API and wait 10s)
document.getElementById('google-map-error').classList.contains('d-none'); // Should be false

// Test 3: Verify page functionality
// All other page elements should be interactive

Performance Impact

Negligible: Polling runs every 100ms for max 10 seconds
Memory: Minimal overhead from stub and event listeners
UX: No noticeable delay in page load time

Accessibility

Error message uses role="alert" for screen reader announcement
aria-live="polite" ensures non-intrusive notification
Map container maintains min-height: 260px to prevent layout shift

Future Improvements

Add retry mechanism with exponential backoff
Implement static map fallback image
Add analytics tracking for map load failures
Consider Progressive Web App (PWA) offline map caching

Fixes: Google Maps blocking public event page load
Prevents: TypeError: Cannot read properties of undefined (reading 'addDomListener')
Prevents: TypeError: google.maps.LatLng is not a constructor

Commit Reference

Commit: fix: robust Google Maps loading with non-blocking fallback Branch: feature/869az6wak Date: October 28, 2025

Last Updated: October 28, 2025
Author: Development Team
Status: Implemented and Deployed

Core

APIs

Features

Frontend

Guías

Comandos

Rendimiento

GOOGLE MAPS ERROR HANDLING

Google Maps Error Handling Documentation

Overview

Problem Statement

Solution

1. Strict API Validation

2. Exception Handling

3. Non-Blocking Error UI

4. Enhanced Polling Mechanism

5. Safe Stub for script.min.js

User Experience

When Google Maps Loads Successfully

When Google Maps Fails to Load

Localization

Files Modified

Testing Scenarios

Manual Testing

Browser Console Tests

Performance Impact

Accessibility

Future Improvements

Commit Reference

​Google Maps Error Handling Documentation

​Overview

​Problem Statement

​Solution

​1. Strict API Validation

​2. Exception Handling

​3. Non-Blocking Error UI

​4. Enhanced Polling Mechanism

​5. Safe Stub for script.min.js

​User Experience

​When Google Maps Loads Successfully

​When Google Maps Fails to Load

​Localization

​Files Modified

​Testing Scenarios

​Manual Testing

​Browser Console Tests

​Performance Impact

​Accessibility

​Future Improvements

​Related Issues

​Commit Reference

Google Maps Error Handling Documentation

Overview

Problem Statement

Solution

1. Strict API Validation

2. Exception Handling

3. Non-Blocking Error UI

4. Enhanced Polling Mechanism

5. Safe Stub for script.min.js

User Experience

When Google Maps Loads Successfully

When Google Maps Fails to Load

Localization

Files Modified

Testing Scenarios

Manual Testing

Browser Console Tests

Performance Impact

Accessibility

Future Improvements

Related Issues

Commit Reference