Debugging Google Maps Black Screen Issues in iOS Safari Iframes

During a routine QA cycle, a black screen issue was reported when embedding Google Maps within an iOS Safari iframe. Initial troubleshooting ruled out browser compatibility and network resource blocking by comparing normal and abnormal network requests and HTML structures. The investigation revealed that the target container element remained empty, indicating that Google Maps failed to inject its content.

To trace the DOM manipulation, the developer attempted to override the Element.prototype.appendChild method in the console. However, this approach failed because the iframe operates in a sandboxed environment, isolating it from the parent page's console modifications.

To bypass the sandbox restriction, Chrome DevTools' Local Overrides feature was utilized to inject custom debugging code directly into the third-party JavaScript file. The following prototype override was implemented to log append operations and trigger a debugger breakpoint specifically for the map container:

const appendChild = Element.prototype.appendChild;
Element.prototype.appendChild = function(...args) {
  console.log('append', this.className);
  if (this.id === 'mapDiv') {
    debugger;
  }
  appendChild.bind(this, ...args)();
}

After successfully applying the override and analyzing the JavaScript execution stack, the root cause was identified. Google Maps checks the document body's dimensions during initialization. If the width and height are both zero, the initialization logic returns false and skips rendering. Since the iframe was dynamically created without predefined dimensions, this condition triggered the black screen.

The issue was resolved by implementing a post-load refresh mechanism. By waiting for the iframe to fully load and then triggering a map refresh, the container acquires valid dimensions, allowing Google Maps to initialize and render correctly.