Profile

const val DEFAULT_PROFILE_NAME = "Default": String!

Represents the name of the default profile which can't be deleted.

@RequiresFeature(name = WebViewFeature.CUSTOM_REQUEST_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
fun addCustomHeader(header: CustomHeader): Unit

Add a header for outgoing requests that match the given origin rules.

It applies to all requests that are initiated after this method is called, including prefetch requests and requests sent from service workers. It does not apply the header to WebSocket requests.

Headers added through this API will be present in the set returned by getRequestHeaders provided in shouldInterceptRequest.

If this method is called multiple times with headers that have the same name and value, then the sets of origin rules will be merged into a single set.

If multiple headers with the same name but different values match a request, then all the values will be sent in a comma-separated list of values following the guidance for repeated header fields. This does not take into account whether such merging is safe.

Headers are considered the same if their name matches case-insensitive and their value matches case-sensitive. This follows RFC 9110, which states that "field names are case insensitive". This API will use the casing of the first custom header encountered.

@RequiresFeature(name = WebViewFeature.ADD_QUIC_HINTS_V1, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalAddQuicHints
fun addQuicHints(urls: (Mutable)Set<String>): Unit

Advises that the given origins support the QUIC protocol and that WebView should use that to connect to them.

By default, when connecting to a new server, WebView attempts both a HTTP3 (QUIC) and HTTP2 connection, choosing the one that responds faster. This can lead to cases where HTTP2 responds faster, even though HTTP3 is supported and would result in a faster overall load. Calling this API tells WebView to prefer HTTP3 connections for these origins.

Note: addQuicHints operates on origins, but for convenience full URLs can be provided. A full URL (such as https://www.example.com/index.html) will be treated as its origin (https://www.example.com).

This method can be called multiple times and the result is additive - QUIC hints are applied to all of the origins provided to all calls. Providing the same origin multiple times has no further effect.

@RequiresFeature(name = WebViewFeature.CUSTOM_REQUEST_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
fun clearAllCustomHeaders(): Unit

Remove any currently set headers from being applied to network requests.

@RequiresFeature(name = WebViewFeature.CUSTOM_REQUEST_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
fun clearCustomHeader(headerName: String): Unit

Removes the specified headers from the set of headers attached to requests. This will remove all configured headers that match headerName.

It is safe to call this method even if headerName has not previously been set via addCustomHeader.

This method is case insensitive.

@RequiresFeature(name = WebViewFeature.CUSTOM_REQUEST_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
fun clearCustomHeader(headerName: String, headerValue: String): Unit

Removes the specified header from the set of headers attached to requests.

It is safe to call this method even if (headerName, headerValue) has not previously been set via addCustomHeader.

This method is case insensitive for name but case-sensitive for value.

@RequiresFeature(name = WebViewFeature.SET_MAX_PRERENDERS_V1, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalUrlPrefetch
fun clearMaxPrerenders(): Unit

Resets the max prerenders for the current profile session to system default. This configuration will be applied to any prerender requests made after they are set; they will not be applied to in-flight requests.

This configuration will be applied to WebViews that are associated with this Profile.

@RequiresFeature(name = WebViewFeature.ENQUEUE_PRECONNECT, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalPreconnect
fun enqueuePreconnect(url: String): Unit

Enqueue a network preconnect to occur once WebView has started up.

This method acts like preconnect but doesn't trigger WebView start up. Instead, it enqueues that action for when WebView start up occurs. If the WebView has already started, this method acts exactly like preconnect

@AnyThread
@RequiresFeature(name = WebViewFeature.MULTI_PROFILE, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
fun getCookieManager(): CookieManager

Returns the profile's cookie manager.

Can be called from any thread.

@RequiresFeature(name = WebViewFeature.CROSS_ORIGIN_ISOLATED_ALLOWLIST, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
fun getCrossOriginIsolatedAllowlist(): (Mutable)Set<String!>

Get the current allowlist of origins, with explicitly written ports, for cross-origin isolated APIs.

If setting the origin rule https://example.com, this method will return the same origin rule as https://example.com:443).

@RequiresFeature(name = WebViewFeature.CUSTOM_REQUEST_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
fun getCustomHeaders(): (Mutable)Set<CustomHeader!>

Returns all custom headers set with addCustomHeader.

@RequiresFeature(name = WebViewFeature.CUSTOM_REQUEST_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
fun getCustomHeaders(name: String): (Mutable)Set<CustomHeader!>

Returns all custom headers set with addCustomHeader which have the specified name.

This method is case insensitive.

@RequiresFeature(name = WebViewFeature.CUSTOM_REQUEST_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
fun getCustomHeaders(name: String, value: String): (Mutable)Set<CustomHeader!>

Returns all custom headers set with addCustomHeader which have the specified name and value.

This method is case insensitive for name but case-sensitive for value.

@AnyThread
@RequiresFeature(name = WebViewFeature.MULTI_PROFILE, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
fun getGeolocationPermissions(): GeolocationPermissions

Returns the geolocation permissions of the profile.

Can be called from any thread.

@RequiresFeature(name = WebViewFeature.HTTP_CACHE_MANAGER, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
fun getHttpCache(): HttpCache

Returns the HttpCache associated with this Profile.

@RequiresFeature(name = WebViewFeature.SET_MAX_PRERENDERS_V1, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalUrlPrefetch
fun getMaxPrerenders(): Int

Returns maximum prerenders for the current profile session.

@AnyThread
@RequiresFeature(name = WebViewFeature.MULTI_PROFILE, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
fun getName(): String

Returns the name of this Profile.

@AnyThread
@RequiresFeature(name = WebViewFeature.MULTI_PROFILE, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
fun getServiceWorkerController(): ServiceWorkerController

Returns the service worker controller of the profile.

Can be called from any thread.

@AnyThread
@RequiresFeature(name = WebViewFeature.MULTI_PROFILE, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
fun getWebStorage(): WebStorage

Returns the profile's web storage.

Can be called from any thread.

@RequiresFeature(name = WebViewFeature.CUSTOM_REQUEST_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
fun hasCustomHeader(headerName: String): Boolean

Returns true if the profile has a value set for the given header name.

This method is case insensitive.

@RequiresFeature(name = WebViewFeature.PRECONNECT, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalPreconnect
fun preconnect(url: String): Unit

Preconnect to the given origin to speed up future network requests.

Opens a connection to the provided origin, performing DNS lookup and TCP/TLS handshakes. This can speed up future loads to the origin which could use the open connection. The connection will remain open (and can be reused by future loads) until it times out (roughly 30s).

The main benefit of this API is to preconnect to origins that haven't yet been visited by a WebView - it provides no further performance benefit to origins that have already been loaded.

Note: Preconnect operates on origins, but for convenience full URLs can be provided. A call with a full URL (such as https://www.example.com/index.html) will be treated as a call to the origin (https://www.example.com).

Multiple origins can be connected to by calling this API multiple times.

See: HTML Preconnect Specification

@RequiresFeature(name = WebViewFeature.ADD_QUIC_HINTS_V1, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalAddQuicHints
fun preferQuicFor(urls: (Mutable)Set<String>): Unit

Advises that the given origins support the QUIC protocol and that WebView should use that to connect to them.

By default, when connecting to a new server, WebView attempts both a HTTP3 (QUIC) and HTTP2 connection, choosing the one that responds faster. This can lead to cases where HTTP2 responds faster, even though HTTP3 is supported and would result in a faster overall load. Calling this API tells WebView to prefer HTTP3 connections for these origins.

Note: preferQuicFor operates on origins, but for convenience full URLs can be provided. A full URL (such as https://www.example.com/index.html) will be treated as its origin (https://www.example.com).

This method can be called multiple times and the result is additive - QUIC hints are applied to all of the origins provided to all calls. Providing the same origin multiple times has no further effect.

@RequiresFeature(name = WebViewFeature.PROFILE_URL_PREFETCH, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@AnyThread
@Profile.ExperimentalUrlPrefetch
fun prefetchUrlAsync(
    url: String,
    cancellationSignal: CancellationSignal?,
    callbackExecutor: Executor?,
    outcomeReceiver: WebViewOutcomeReceiver<Void?, PrefetchException!>
): Unit

Starts a URL prefetch request.

All WebViews associated with this Profile will use a URL request matching algorithm during execution of all variants of loadUrl for determining if there was already a prefetch request executed for the provided URL. This includes prefetches that are "in progress". If a prefetch is matched, WebView will leverage that for handling the URL, otherwise the URL will be handled normally (i.e. through a network request).

Applications will still be responsible for calling loadUrl to display web contents in a WebView.

NOTE: Additional headers passed to loadUrl are not considered in the matching algorithm for determining whether or not to serve a prefetched response to a navigation.

For max latency saving benefits, it is recommended to call this method as early as possible (i.e. before any WebView associated with this profile is created).

Only supports HTTPS scheme.

@RequiresFeature(name = WebViewFeature.PROFILE_URL_PREFETCH, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@AnyThread
@Profile.ExperimentalUrlPrefetch
fun prefetchUrlAsync(
    url: String,
    cancellationSignal: CancellationSignal?,
    callbackExecutor: Executor?,
    speculativeLoadingParameters: SpeculativeLoadingParameters,
    outcomeReceiver: WebViewOutcomeReceiver<Void?, PrefetchException!>
): Unit

Starts a URL prefetch request.

All WebViews associated with this Profile will use a URL request matching algorithm during execution of all variants of loadUrl for determining if there was already a prefetch request executed for the provided URL. This includes prefetches that are "in progress". If a prefetch is matched, WebView will leverage that for handling the URL, otherwise the URL will be handled normally (i.e. through a network request).

Applications will still be responsible for calling loadUrl to display web contents in a WebView.

NOTE: Additional headers passed to loadUrl are not considered in the matching algorithm for determining whether or not to serve a prefetched response to a navigation.

For max latency saving benefits, it is recommended to call this method as early as possible (i.e. before any WebView associated with this profile is created).

Only supports HTTPS scheme.

@RequiresFeature(name = WebViewFeature.CROSS_ORIGIN_ISOLATED_ALLOWLIST, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
fun setCrossOriginIsolatedAllowlist(
    allowedOriginRules: (Mutable)Set<String!>
): Unit

Set the list of origin patterns where Cross Origin Isolated APIs should be accessible.

This API allows you to set an allowlist of origins where potentially risky APIs will be enabled, provided the loaded page has the correct Document-Isolation-Policy response header.

WebView does not enable this feature by default because WebView does not support renderer process isolation. By calling this API, you acknowledge that it is OK to relax this security guarantee and allow pages to use cross-origin-isolated APIs, for example SharedArrayBuffer even if they are running in a shared renderer process. For this reason, you should only use this API with origins you trust.

You should also avoid using the wildcard matcher ("*") in the originPatterns for the same reason.

This method will affect pages that are already loaded.

@RequiresFeature(name = WebViewFeature.SET_MAX_PRERENDERS_V1, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalUrlPrefetch
fun setMaxPrerenders(maxPrerenders: @IntRange(from = 1) Int): Unit

Sets the max prerenders for the current profile session. These configurations will be applied to any prerender requests made after they are set; they will not be applied to in-flight requests.

These configurations will be applied to WebViews that are associated with this Profile.

@RequiresFeature(name = WebViewFeature.SPECULATIVE_LOADING_CONFIG, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalUrlPrefetch
fun setSpeculativeLoadingConfig(
    speculativeLoadingConfig: SpeculativeLoadingConfig
): Unit

Sets the SpeculativeLoadingConfig for the current profile session. These configurations will be applied to any Prefetch requests made after they are set; they will not be applied to in-flight requests.

These configurations will be applied to any prefetch requests initiated by a prerender request. This applies specifically to WebViews that are associated with this Profile.

@RequiresFeature(name = WebViewFeature.WARM_UP_RENDERER_PROCESS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalWarmUpRendererProcess
fun warmUpRendererProcess(): Unit

Initiates warm-up of the renderer process associated with this Profile.

If no renderer currently exists for the profile, this will kick off the process of starting one in the background. This call does not block or guarantee that the renderer will be fully started by the time it returns.

This can be used to reduce perceived latency when a renderer is needed shortly after.