How to Debug iOS WebViews with Safari Web Inspector

Debugging web content embedded within native iOS applications is essential for ensuring a seamless user experience in hybrid apps. This article provides a step-by-step guide on how developers can use macOS Safari's built-in Web Inspector to inspect, debug, and profile WebViews inside third-party iOS applications currently under development. By configuring your iOS device, enabling developer tools in desktop Safari, and adding a single property to your app's source code, you can access the full suite of web debugging tools in real time.

Prerequisites

To debug a WebView inside a third-party iOS app, you need the following:

  • A Mac with the Safari web browser installed.
  • An iOS device connected to your Mac via cable, or the iOS Simulator running on your Mac.
  • The iOS application must be a development build signed with a development provisioning profile and installed via Xcode. Production apps downloaded from the App Store cannot be inspected.

Step 1: Enable Web Inspector on the iOS Device

If you are using the iOS Simulator, Web Inspector is enabled by default, and you can skip to Step 2. If you are using a physical iPhone or iPad, you must enable the feature manually:

  1. Open the Settings app on your iOS device.
  2. Scroll down and tap Safari.
  3. Scroll to the bottom and tap Advanced.
  4. Toggle on the Web Inspector switch.

Step 2: Enable the Develop Menu in macOS Safari

By default, Safari on macOS hides its web development tools. To turn them on:

  1. Open Safari on your Mac.
  2. In the top menu bar, click Safari and select Settings (or Preferences on older macOS versions).
  3. Click the Advanced tab.
  4. At the bottom of the window, check the box next to Show features for web developers (or Show Develop menu in menu bar on older Safari versions).
  5. Close the Settings window. You will now see a Develop menu in the top menu bar.

Step 3: Enable WebView Inspection in Your App's Code

Starting with iOS 16.4 and iPadOS 16.4, Apple disabled the ability to inspect WKWebView instances by default, even in development builds. You must explicitly enable inspection in your application's source code.

In the view controller or class where you initialize your WKWebView, set the isInspectable property to true.

For Swift:

import WebKit

let webView = WKWebView(frame: .zero)
if #available(iOS 16.4, *) {
    webView.isInspectable = true
}

For Objective-C:

#import <WebKit/WebKit.h>

WKWebView *webView = [[WKWebView alloc] initWithFrame:CGRectZero];
if (@available(iOS 16.4, *)) {
    webView.inspectable = YES;
}

Note: If you are using a cross-platform framework like Cordova, Ionic, or React Native, ensure your framework and its WebView plugins are updated to versions that support iOS 16.4+, as they handle this property automatically in debug builds.

Step 4: Connect and Inspect the WebView

Once your devices and code are configured, you can begin debugging:

  1. Connect your iOS device to your Mac using a USB or USB-C cable. If prompted on the iOS device, tap Trust This Computer and enter your passcode.
  2. Build and run your application from Xcode onto your iOS device or Simulator.
  3. In the running app, navigate to the specific screen that loads and displays the WKWebView. The WebView must be active on the screen to be detected.
  4. Switch to Safari on your Mac.
  5. Click Develop in the top menu bar.
  6. Find and hover over your iOS device's name or the Simulator in the dropdown menu.
  7. A submenu will appear showing your app's name and the currently active URLs or page titles inside the WebView. Click on the WebView entry you wish to debug.

A Safari Web Inspector window will immediately open on your Mac. From this window, you can modify the DOM and CSS in the Elements tab, view logs and run JavaScript commands in the Console tab, debug scripts in the Sources tab, and monitor API calls in the Network tab, just as you would for a standard website.