WebView

Configure App Transport Security on iOS and Mac Catalyst

Since version 9, iOS will only allow your app to communicate with secure servers. An app has to opt into enabling communication with insecure servers.

The following Info.plist configuration shows how to enable a specific domain to bypass Apple Transport Security (ATS) requirements:

	<key>NSAppTransportSecurity</key>
	<dict>
		<key>NSExceptionDomains</key>
		<dict>
			<key>mydomain.com</key>
			<dict>
				<key>NSIncludesSubdomains</key>
				<true/>
				<key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
				<true/>
				<key>NSTemporaryExceptionMinimumTLSVersion</key>
				<string>TLSv1.1</string>
			</dict>
		</dict>
	</dict>

It's best practice to only enable specific domains to bypass ATS, allowing you to use trusted sites while benefitting from additional security on untrusted domains.

The following Info.plist configuration shows how to disable ATS for an app:

	<key>NSAppTransportSecurity</key>
	<dict>
		<key>NSAllowsArbitraryLoads</key>
		<true/>
	</dict>

Handle permissions on Android

When browsing to a page that requests access to the device's recording hardware, such as the camera or microphone, permission must be granted by the WebView control. The WebView control uses the Android.Webkit.WebChromeClient type on Android to react to permission requests. However, the WebChromeClient implementation provided by .NET MAUI ignores permission requests. You must create a new type that inherits from MauiWebChromeClient and approves the permission requests.

The permission requests from a web page to the WebView control are different than permission requests from the .NET MAUI app to the user. .NET MAUI app permissions are requested and approved by the user, for the whole app. The WebView control is dependent on the apps ability to access the hardware. To illustrate this concept, consider a web page that requests access to the device's camera. Even if that request is approved by the WebView control, yet the .NET MAUI app didn't have approval by the user to access the camera, the web page wouldn't be able to access the camera.

The following steps demonstrate how to intercept permission requests from the WebView control to use the camera. If you are trying to use the microphone, the steps would be similar except that you would use microphone-related permissions instead of camera-related permissions.

1. First, add the required app permissions to the Android manifest. Open the Platforms/Android/AndroidManifest.xml file and add the following in the manifest node:

   <uses-permission android:name="android.permission.CAMERA" />
   

2. At some point in your app, such as when the page containing a WebView control is loaded, request permission from the user to allow the app access to the camera.

   private async Task RequestCameraPermission()
   {
       PermissionStatus status = await Permissions.CheckStatusAsync<Permissions.Camera>();
   
       if (status != PermissionStatus.Granted)
           await Permissions.RequestAsync<Permissions.Camera>();
   }
   

3. Add the following class to the Platforms/Android folder, changing the root namespace to match your project's namespace:

   using Android.Webkit;
   using Microsoft.Maui.Handlers;
   using Microsoft.Maui.Platform;
   
   namespace MauiAppWebViewHandlers.Platforms.Android;
   
   internal class MyWebChromeClient: MauiWebChromeClient
   {
       public MyWebChromeClient(IWebViewHandler handler) : base(handler)
       {
   
       }
   
       public override void OnPermissionRequest(PermissionRequest request)
       {
           // Process each request
           foreach (var resource in request.GetResources())
           {
               // Check if the web page is requesting permission to the camera
               if (resource.Equals(PermissionRequest.ResourceVideoCapture, StringComparison.OrdinalIgnoreCase))
               {
                   // Get the status of the .NET MAUI app's access to the camera
                   PermissionStatus status = Permissions.CheckStatusAsync<Permissions.Camera>().Result;
   
                   // Deny the web page's request if the app's access to the camera is not "Granted"
                   if (status != PermissionStatus.Granted)
                       request.Deny();
                   else
                       request.Grant(request.GetResources());
   
                   return;
               }
           }
   
           base.OnPermissionRequest(request);
       }
   }
   

   In the previous snippet, the MyWebChromeClient class inherits from MauiWebChromeClient, and overrides the OnPermissionRequest method to intercept web page permission requests. Each permission item is checked to see if it matches the PermissionRequest.ResourceVideoCapture string constant, which represents the camera. If a camera permission is matched, the code checks to see if the app has permission to use the camera. If it has permission, the web page's request is granted.

4. Use the SetWebChromeClient method on the Android's WebView control to set the chrome client to MyWebChromeClient. The following two items demonstrate how you can set the chrome client:

   • Given a .NET MAUI WebView control named theWebViewControl, you can set the chrome client directly on the platform view, which is the Android control:

     ((IWebViewHandler)theWebViewControl.Handler).PlatformView.SetWebChromeClient(new MyWebChromeClient((IWebViewHandler)theWebViewControl.Handler));
     

   • You can also use handler property mapping to force all WebView controls to use your chrome client. For more information, see Handlers.

     The following snippet's CustomizeWebViewHandler method should be called when the app starts, such as in the MauiProgram.CreateMauiApp method.

     private static void CustomizeWebViewHandler()
     {
     #if ANDROID26_0_OR_GREATER
         Microsoft.Maui.Handlers.WebViewHandler.Mapper.ModifyMapping(
             nameof(Android.Webkit.WebView.WebChromeClient),
             (handler, view, args) => handler.PlatformView.SetWebChromeClient(new MyWebChromeClient(handler)));
     #endif
     }
     

Configure the native WebView on iOS and Mac Catalyst

The native WebView control is a MauiWKWebView on iOS and Mac Catalyst, which derives from WKWebView. One of the MauiWKWebView constructor overloads enables a WKWebViewConfiguration object to be specified, which provides information about how to configure the WKWebView object. Typical configurations include setting the user agent, specifying cookies to make available to your web content, and injecting custom scripts into your web content.

You can create a WKWebViewConfiguration object in your app, and then configure its properties as required. Alternatively, you can call the static MauiWKWebView.CreateConfiguration method to retrieve .NET MAUI's WKWebViewConfiguration object and then modify it. The WKWebViewConfiguration object can then be specified as an argument to the MauiWKWebView constructor overload.

Since the configuration of the native WebView can't be changed on iOS and Mac Catalyst once the handler's platform view is created, you should create a custom handler factory delegate to modify it:

#if IOS || MACCATALYST
using WebKit;
using CoreGraphics;
using Microsoft.Maui.Platform;
using Microsoft.Maui.Handlers;
#endif
...

#if IOS || MACCATALYST
    Microsoft.Maui.Handlers.WebViewHandler.PlatformViewFactory = (handler) =>
    {
        WKWebViewConfiguration config = MauiWKWebView.CreateConfiguration();
        config.ApplicationNameForUserAgent = "MyProduct/1.0.0";
        return new MauiWKWebView(CGRect.Empty, (WebViewHandler)handler, config);
    };
#endif

Set media playback preferences on iOS and Mac Catalyst

Inline media playback of HTML5 video, including autoplay and picture in picture, is enabled by default for the WebView on iOS and Mac Catalyst. To change this default, or set other media playback preferences, you should create a custom handler factory delegate since media playback preferences can't be changed once the handler's platform view is created. The following code shows an example of doing this:

#if IOS || MACCATALYST
using WebKit;
using CoreGraphics;
using Microsoft.Maui.Platform;
using Microsoft.Maui.Handlers;
#endif
...

#if IOS || MACCATALYST
    Microsoft.Maui.Handlers.WebViewHandler.PlatformViewFactory = (handler) =>
    {
        WKWebViewConfiguration config = MauiWKWebView.CreateConfiguration();

        // True to play HTML5 videos inliine, false to use the native full-screen controller.
        config.AllowsInlineMediaPlayback = false;

        // True to play videos over AirPlay, otherwise false.
        config.AllowsAirPlayForMediaPlayback = false;

        // True to let HTML5 videos play Picture in Picture.
        config.AllowsPictureInPictureMediaPlayback = false;

        // Media types that require a user gesture to begin playing.
        config.MediaTypesRequiringUserActionForPlayback = WKAudiovisualMediaTypes.All;

        return new MauiWKWebView(CGRect.Empty, (WebViewHandler)handler, config);
    };
#endif

For more information about configuring a WebView on iOS, see Configure the native WebView on iOS and Mac Catalyst.

Inspect a WebView on Mac Catalyst

To use Safari developer tools to inspect the content of a WebView on Mac Catalyst, add the following code to your app:

#if MACCATALYST
        Microsoft.Maui.Handlers.WebViewHandler.Mapper.AppendToMapping("Inspect", (handler, view) =>
        {
            if (OperatingSystem.IsMacCatalystVersionAtLeast(16, 6))
                handler.PlatformView.Inspectable = true;
        });
#endif

This code customizes the property mapper for the WebViewHandler on Mac Catalyst, to make WebView content inspectable by Safari developer tools. For more information about handlers, see Handlers.

To use Safari developer tools with a Mac Catalyst app:

1. Open Safari on your Mac.
2. In Safari, select the Safari > Settings > Advanced > Show Develop menu in menu bar checkbox.
3. Run your .NET MAUI Mac Catalyst app.
4. In Safari, select the Develop > {Device name} menu, where the {Device name} placeholder is your device name such as Macbook Pro. Then select the entry under your app name, which will also highlight your running app. This will cause the Web inspector window to appear.