Profile


public interface Profile


A Profile represents one browsing session for WebView.

You can have multiple profiles and each profile holds its own set of data. The creation and deletion of the Profile is being managed by ProfileStore.

Summary

Nested types

Denotes that the Profile#addQuicHints API surface is experimental.

Denotes that the Profile#preconnect API surface is experimental.

Denotes that the selected site isolation API surface is experimental.

Denotes that the UrlPrefetch API surface is experimental.

Denotes that the WarmUpRendererProcess API surface is experimental.

Constants

default static final String

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

Public methods

default void
@RequiresFeature(name = WebViewFeature.CUSTOM_REQUEST_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
addCustomHeader(@NonNull CustomHeader header)

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

default void
@RequiresFeature(name = WebViewFeature.ADD_QUIC_HINTS_V1, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalAddQuicHints
addQuicHints(@NonNull Set<@NonNull String> urls)

This method is deprecated.

This method is being renamed to preferQuicFor, use that instead.

default boolean

Returns whether configureIsolatedSites can be called on this profile.

default void
@RequiresFeature(name = WebViewFeature.CUSTOM_REQUEST_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
clearAllCustomHeaders()

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

default void
@RequiresFeature(name = WebViewFeature.CUSTOM_REQUEST_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
clearCustomHeader(@NonNull String headerName)

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

default void
@RequiresFeature(name = WebViewFeature.CUSTOM_REQUEST_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
clearCustomHeader(@NonNull String headerName, @NonNull String headerValue)

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

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

Resets the max prerenders for the current profile session to system default.

default void

Configures a set of sites to be isolated from all other web content in this profile by running them in a separate renderer process to the default used by other sites.

default void
@RequiresFeature(name = WebViewFeature.ENQUEUE_PRECONNECT, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalPreconnect
enqueuePreconnect(@NonNull String url)

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

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

Returns the profile's cookie manager.

default @NonNull Set<String>
@RequiresFeature(name = WebViewFeature.CROSS_ORIGIN_ISOLATED_ALLOWLIST, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
getCrossOriginIsolatedAllowlist()

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

default @NonNull Set<CustomHeader>
@RequiresFeature(name = WebViewFeature.CUSTOM_REQUEST_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
getCustomHeaders()

Returns all custom headers set with addCustomHeader.

default @NonNull Set<CustomHeader>
@RequiresFeature(name = WebViewFeature.CUSTOM_REQUEST_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
getCustomHeaders(@NonNull String name)

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

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

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

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

Returns the geolocation permissions of the profile.

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

Returns the HttpCache associated with this Profile.

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

Returns maximum prerenders for the current profile session.

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

Returns the name of this Profile.

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

Returns the service worker controller of the profile.

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

Returns the profile's web storage.

default boolean
@RequiresFeature(name = WebViewFeature.CUSTOM_REQUEST_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
hasCustomHeader(@NonNull String headerName)

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

default void
@RequiresFeature(name = WebViewFeature.PRECONNECT, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalPreconnect
preconnect(@NonNull String url)

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

default void
@RequiresFeature(name = WebViewFeature.ADD_QUIC_HINTS_V1, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalAddQuicHints
preferQuicFor(@NonNull Set<@NonNull String> urls)

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

abstract void
@RequiresFeature(name = WebViewFeature.PROFILE_URL_PREFETCH, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@AnyThread
@Profile.ExperimentalUrlPrefetch
prefetchUrlAsync(
    @NonNull String url,
    @Nullable CancellationSignal cancellationSignal,
    @Nullable Executor callbackExecutor,
    @NonNull WebViewOutcomeReceiver<@Nullable Void, PrefetchException> outcomeReceiver
)

This method is deprecated.

Use prefetchUrlAsync instead.

abstract void
@RequiresFeature(name = WebViewFeature.PROFILE_URL_PREFETCH, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@AnyThread
@Profile.ExperimentalUrlPrefetch
prefetchUrlAsync(
    @NonNull String url,
    @Nullable CancellationSignal cancellationSignal,
    @Nullable Executor callbackExecutor,
    @NonNull SpeculativeLoadingParameters speculativeLoadingParameters,
    @NonNull WebViewOutcomeReceiver<@Nullable Void, PrefetchException> outcomeReceiver
)

This method is deprecated.

Use prefetchUrlAsync instead.

default void
@RequiresFeature(name = WebViewFeature.CROSS_ORIGIN_ISOLATED_ALLOWLIST, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
setCrossOriginIsolatedAllowlist(@NonNull Set<String> allowedOriginRules)

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

default void
@RequiresFeature(name = WebViewFeature.SET_MAX_PRERENDERS_V1, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalUrlPrefetch
setMaxPrerenders(@IntRange(from = 1) int maxPrerenders)

Sets the max prerenders for the current profile session.

abstract void
@RequiresFeature(name = WebViewFeature.SPECULATIVE_LOADING_CONFIG, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalUrlPrefetch
setSpeculativeLoadingConfig(
    @NonNull SpeculativeLoadingConfig speculativeLoadingConfig
)

This method is deprecated.

use setMaxPrerenders, setMaxPrefetches and setPrefetchTtlSeconds instead.

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

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

Constants

DEFAULT_PROFILE_NAME

Added in 1.9.0
default static final String DEFAULT_PROFILE_NAME = "Default"

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

Public methods

addCustomHeader

Added in 1.15.0
@RequiresFeature(name = WebViewFeature.CUSTOM_REQUEST_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
default void addCustomHeader(@NonNull CustomHeader header)

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

Changes to custom headers take effect on document load. For document-initiated requests (such as subresources, fetch(), and XMLHttpRequest), the header will only apply to documents that begin loading after this method is called; it does not affect requests initiated by documents that are already loaded. Similarly, for requests sent from service workers, the header will only apply to service workers that are started after this method is called; it does not affect requests sent from service workers that are already running. The header also applies to navigation requests to load new documents and prefetch requests. It does not apply 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.

Parameters
@NonNull CustomHeader header

The header to add.

Throws
java.lang.UnsupportedOperationException

if the CUSTOM_REQUEST_HEADERS feature is not supported. This should be checked before use with isFeatureSupported.

addQuicHints

Added in 1.15.0
Deprecated in 1.18.0
@RequiresFeature(name = WebViewFeature.ADD_QUIC_HINTS_V1, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalAddQuicHints
default void addQuicHints(@NonNull Set<@NonNull String> urls)

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.

URLs provided can be wildcards (such as https://*.example.com or https://*) when ADD_QUIC_HINTS_WILDCARDS is supported, following the same rules as addWebMessageListener.

Parameters
@NonNull Set<@NonNull String> urls

A set of urls representing origins that support the QUIC protocol, url can be a wildcard when ADD_QUIC_HINTS_WILDCARDS is supported.

Throws
java.lang.UnsupportedOperationException

if the ADD_QUIC_HINTS_V1 feature is not supported. This should be checked before use with isFeatureSupported.

canConfigureIsolatedSites

@RequiresFeature(name = WebViewFeature.PROFILE_SELECTED_SITE_ISOLATION_EXPERIMENTAL_V1, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@Profile.ExperimentalSelectedSiteIsolation
@UiThread
default boolean canConfigureIsolatedSites()

Returns whether configureIsolatedSites can be called on this profile.

Isolated sites may only be configured once per profile, and must be configured before any renderer process has been used by this profile. This generally means you should configure this before performing any action that loads web content, such as loading a page into a WebView or performing a pre-render.

This method also checks for runtime support that isn't implied by the presence of the PROFILE_SELECTED_SITE_ISOLATION_EXPERIMENTAL_V1 feature. As such, you should always call this method before calling configureIsolatedSites, even if you know this configuration is the first action being performed on the profile.

Returns
boolean

true if configureIsolatedSites can be called on this profile, false otherwise.

Throws
java.lang.UnsupportedOperationException

if the PROFILE_SELECTED_SITE_ISOLATION_EXPERIMENTAL_V1 feature is not supported. This should be checked before use with isFeatureSupported.

clearAllCustomHeaders

Added in 1.15.0
@RequiresFeature(name = WebViewFeature.CUSTOM_REQUEST_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
default void clearAllCustomHeaders()

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

Changes to custom headers take effect on document load. For document-initiated requests, headers will only be removed for documents that begin loading after this method is called; requests initiated by documents that are already loaded will continue to send previously configured headers.

Throws
java.lang.UnsupportedOperationException

if the CUSTOM_REQUEST_HEADERS feature is not supported. This should be checked before use with isFeatureSupported.

See also
addCustomHeader

clearCustomHeader

Added in 1.15.0
@RequiresFeature(name = WebViewFeature.CUSTOM_REQUEST_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
default void clearCustomHeader(@NonNull String headerName)

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

Changes to custom headers take effect on document load. For document-initiated requests, the header will only be removed for documents that begin loading after this method is called; requests initiated by documents that are already loaded will continue to send previously configured headers.

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

This method is case insensitive.

Parameters
@NonNull String headerName

Header to remove.

Throws
java.lang.UnsupportedOperationException

if the CUSTOM_REQUEST_HEADERS feature is not supported. This should be checked before use with isFeatureSupported.

See also
addCustomHeader

clearCustomHeader

Added in 1.15.0
@RequiresFeature(name = WebViewFeature.CUSTOM_REQUEST_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
default void clearCustomHeader(@NonNull String headerName, @NonNull String headerValue)

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

Changes to custom headers take effect on document load. For document-initiated requests, the header will only be removed for documents that begin loading after this method is called; requests initiated by documents that are already loaded will continue to send previously configured headers.

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.

Parameters
@NonNull String headerName

Header name to remove.

@NonNull String headerValue

Header value to remove.

Throws
java.lang.UnsupportedOperationException

if the CUSTOM_REQUEST_HEADERS feature is not supported. This should be checked before use with isFeatureSupported.

See also
addCustomHeader

clearMaxPrerenders

Added in 1.17.0
@RequiresFeature(name = WebViewFeature.SET_MAX_PRERENDERS_V1, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalUrlPrefetch
default void clearMaxPrerenders()

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.

Throws
java.lang.UnsupportedOperationException

if the SET_MAX_PRERENDERS_V1 feature is not supported. This should be checked before use with isFeatureSupported.

configureIsolatedSites

@RequiresFeature(name = WebViewFeature.PROFILE_SELECTED_SITE_ISOLATION_EXPERIMENTAL_V1, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@Profile.ExperimentalSelectedSiteIsolation
@UiThread
default void configureIsolatedSites(@NonNull Set<@NonNull String> sites)

Configures a set of sites to be isolated from all other web content in this profile by running them in a separate renderer process to the default used by other sites.

Sites in the supplied Set will never share a renderer process with sites outside of this Set, though sites within the Set may still share a renderer process with each other. This can be used, for example, to ensure privileged first-party content does not run in the same renderer process as untrusted third-party content.

Each entry in sites must be a valid HTTP or HTTPS site (scheme + registrable domain or host) in canonical form (for example, "https://example.com", with no port, trailing slash, path, query, or fragment).

Note that this API does not accept wildcards, and does not need to: specifying a site such as "https://google.com" automatically includes subdomain origins under it (such as "https://mail.google.com"), provided that no subdomain is itself a distinct site on the Public Suffix List. Conversely, specifying a public suffix itself (such as "https://github.io") only covers that exact origin and not its subdomains (such as "https://foo.github.io"), which are distinct sites.

Note that because what constitutes a site depends on the Public Suffix List, updates to the Public Suffix List between WebView versions may change whether a given domain is considered a valid site.

You should specifically supply higher trust or first-party sites to this API, rather than lower trust or third-party sites, as it is trivial for content in the selected sites' renderer to spin off controlled secondary content to run in the default renderer.

Avoid including sites that use plaintext HTTP ("http://...") unless necessary, as unencrypted traffic may allow network attackers to compromise the renderer process used specifically for isolated sites and thus weaken the security of the sites running within it.

If using this API, use caution when using evaluateJavascript on an unnavigated WebView, as this may potentially execute code in either renderer process. This may either leak sensitive information to a less-trusted process, or execute untrusted code in a more-trusted process. If you need to call evaluateJavascript, consider first navigating to an appropriate site in order to ensure a specific renderer process is used for the evaluation, though be aware of the consequences of evaluating such code within the security context of a specific origin.

You must check the result of canConfigureIsolatedSites before calling this method in order to check for the required runtime support and to ensure the profile is in an appropriate state. You may only configure isolated sites once per profile, and it must be done before any renderer process has been used by this profile.

Parameters
@NonNull Set<@NonNull String> sites

A non-empty set of HTTP or HTTPS sites in canonical form to isolate.

Throws
java.lang.IllegalArgumentException

if sites is empty, or if any entry in sites is malformed, not HTTP/HTTPS, not a site, or not in canonical form.

java.lang.IllegalStateException

if isolated sites have already been configured for this profile, or if a renderer process has already been used by this profile.

java.lang.UnsupportedOperationException

if the PROFILE_SELECTED_SITE_ISOLATION_EXPERIMENTAL_V1 feature is not supported. This should be checked before use with isFeatureSupported.

enqueuePreconnect

Added in 1.17.0
@RequiresFeature(name = WebViewFeature.ENQUEUE_PRECONNECT, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalPreconnect
default void enqueuePreconnect(@NonNull String url)

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

Parameters
@NonNull String url

A url containing the origin to open a connection to.

Throws
java.lang.UnsupportedOperationException

if the ENQUEUE_PRECONNECT feature is not supported.

See also
preconnect

getCookieManager

Added in 1.9.0
@AnyThread
@RequiresFeature(name = WebViewFeature.MULTI_PROFILE, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
abstract @NonNull CookieManager getCookieManager()

Returns the profile's cookie manager.

Can be called from any thread.

Throws
java.lang.IllegalStateException

if the profile has been deleted by deleteProfile}.

java.lang.UnsupportedOperationException

if the MULTI_PROFILE feature is not supported. This should be checked before use with isFeatureSupported.

getCrossOriginIsolatedAllowlist

Added in 1.18.0
@RequiresFeature(name = WebViewFeature.CROSS_ORIGIN_ISOLATED_ALLOWLIST, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
default @NonNull Set<String> getCrossOriginIsolatedAllowlist()

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).

Returns
@NonNull Set<String>

An empty set if no allowlist has been set.

Throws
java.lang.UnsupportedOperationException

if the CROSS_ORIGIN_ISOLATED_ALLOWLIST feature is not supported. This should be checked before use with isFeatureSupported.

getCustomHeaders

Added in 1.15.0
@RequiresFeature(name = WebViewFeature.CUSTOM_REQUEST_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
default @NonNull Set<CustomHeader> getCustomHeaders()

Returns all custom headers set with addCustomHeader.

Throws
java.lang.UnsupportedOperationException

if the CUSTOM_REQUEST_HEADERS feature is not supported. This should be checked before use with isFeatureSupported.

getCustomHeaders

Added in 1.15.0
@RequiresFeature(name = WebViewFeature.CUSTOM_REQUEST_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
default @NonNull Set<CustomHeader> getCustomHeaders(@NonNull String name)

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

This method is case insensitive.

Parameters
@NonNull String name

Name of headers to get. Case sensitive.

Throws
java.lang.UnsupportedOperationException

if the CUSTOM_REQUEST_HEADERS feature is not supported. This should be checked before use with isFeatureSupported.

getCustomHeaders

Added in 1.15.0
@RequiresFeature(name = WebViewFeature.CUSTOM_REQUEST_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
default @NonNull Set<CustomHeader> getCustomHeaders(@NonNull String name, @NonNull String value)

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.

Parameters
@NonNull String name

Name of headers to get. Case sensitive.

@NonNull String value

Value of headers to get. Case sensitive.

Throws
java.lang.UnsupportedOperationException

if the CUSTOM_REQUEST_HEADERS feature is not supported. This should be checked before use with isFeatureSupported.

getGeolocationPermissions

Added in 1.9.0
@AnyThread
@RequiresFeature(name = WebViewFeature.MULTI_PROFILE, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
abstract @NonNull GeolocationPermissions getGeolocationPermissions()

Returns the geolocation permissions of the profile.

Can be called from any thread.

Throws
java.lang.IllegalStateException

if the profile has been deleted by deleteProfile}.

java.lang.UnsupportedOperationException

if the MULTI_PROFILE feature is not supported. This should be checked before use with isFeatureSupported.

getHttpCache

Added in 1.17.0
@RequiresFeature(name = WebViewFeature.HTTP_CACHE_MANAGER, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
default @NonNull HttpCache getHttpCache()

Returns the HttpCache associated with this Profile.

Throws
java.lang.UnsupportedOperationException

if the HTTP_CACHE_MANAGER feature is not supported. This should be checked before use with isFeatureSupported.

getMaxPrerenders

Added in 1.17.0
@RequiresFeature(name = WebViewFeature.SET_MAX_PRERENDERS_V1, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalUrlPrefetch
default int getMaxPrerenders()

Returns maximum prerenders for the current profile session.

Throws
java.lang.UnsupportedOperationException

if the SET_MAX_PRERENDERS_V1 feature is not supported. This should be checked before use with isFeatureSupported.

getName

Added in 1.9.0
@AnyThread
@RequiresFeature(name = WebViewFeature.MULTI_PROFILE, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
abstract @NonNull String getName()

Returns the name of this Profile.

Returns
@NonNull String

the name of this Profile which was used to create the Profile from ProfileStore create methods.

Throws
java.lang.UnsupportedOperationException

if the MULTI_PROFILE feature is not supported. This should be checked before use with isFeatureSupported.

getServiceWorkerController

Added in 1.9.0
@AnyThread
@RequiresFeature(name = WebViewFeature.MULTI_PROFILE, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
abstract @NonNull ServiceWorkerController getServiceWorkerController()

Returns the service worker controller of the profile.

Can be called from any thread.

Throws
java.lang.IllegalStateException

if the profile has been deleted by deleteProfile}.

java.lang.UnsupportedOperationException

if the MULTI_PROFILE feature is not supported. This should be checked before use with isFeatureSupported.

getWebStorage

Added in 1.9.0
@AnyThread
@RequiresFeature(name = WebViewFeature.MULTI_PROFILE, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
abstract @NonNull WebStorage getWebStorage()

Returns the profile's web storage.

Can be called from any thread.

Throws
java.lang.IllegalStateException

if the profile has been deleted by deleteProfile}.

java.lang.UnsupportedOperationException

if the MULTI_PROFILE feature is not supported. This should be checked before use with isFeatureSupported.

hasCustomHeader

Added in 1.15.0
@RequiresFeature(name = WebViewFeature.CUSTOM_REQUEST_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
default boolean hasCustomHeader(@NonNull String headerName)

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

This method is case insensitive.

Parameters
@NonNull String headerName

A valid HTTP header name string

Returns
boolean

true if there is a value mapped for the provided headerName, {code false} otherwise.

Throws
java.lang.UnsupportedOperationException

if the CUSTOM_REQUEST_HEADERS feature is not supported. This should be checked before use with isFeatureSupported.

See also
addCustomHeader

preconnect

Added in 1.15.0
@RequiresFeature(name = WebViewFeature.PRECONNECT, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalPreconnect
default void preconnect(@NonNull String url)

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

Parameters
@NonNull String url

A url containing the origin to open a connection to.

Throws
java.lang.UnsupportedOperationException

if the PRECONNECT feature is not supported. This should be checked before use with isFeatureSupported.

preferQuicFor

Added in 1.18.0
@RequiresFeature(name = WebViewFeature.ADD_QUIC_HINTS_V1, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalAddQuicHints
default void preferQuicFor(@NonNull Set<@NonNull String> urls)

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.

Parameters
@NonNull Set<@NonNull String> urls

A set of urls representing origins that support the QUIC protocol.

Throws
java.lang.UnsupportedOperationException

if the ADD_QUIC_HINTS_V1 feature is not supported. This should be checked before use with isFeatureSupported.

prefetchUrlAsync

Added in 1.16.0
Deprecated in 1.17.0
@RequiresFeature(name = WebViewFeature.PROFILE_URL_PREFETCH, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@AnyThread
@Profile.ExperimentalUrlPrefetch
abstract void prefetchUrlAsync(
    @NonNull String url,
    @Nullable CancellationSignal cancellationSignal,
    @Nullable Executor callbackExecutor,
    @NonNull WebViewOutcomeReceiver<@Nullable Void, PrefetchException> outcomeReceiver
)

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.

Parameters
@NonNull String url

the url associated with the prefetch request.

@Nullable CancellationSignal cancellationSignal

will make the best effort to cancel an in-flight prefetch request, However cancellation is not guaranteed.

@Nullable Executor callbackExecutor

the executor to resolve the callback with. If null, the callback will be executed on the main thread.

@NonNull WebViewOutcomeReceiver<@Nullable Void, PrefetchException> outcomeReceiver

callbacks for reporting result back to application.

Throws
java.lang.IllegalArgumentException

if the url or callback is null.

java.lang.UnsupportedOperationException

if the PROFILE_URL_PREFETCH feature is not supported. This should be checked before use with isFeatureSupported.

prefetchUrlAsync

Added in 1.16.0
Deprecated in 1.17.0
@RequiresFeature(name = WebViewFeature.PROFILE_URL_PREFETCH, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@AnyThread
@Profile.ExperimentalUrlPrefetch
abstract void prefetchUrlAsync(
    @NonNull String url,
    @Nullable CancellationSignal cancellationSignal,
    @Nullable Executor callbackExecutor,
    @NonNull SpeculativeLoadingParameters speculativeLoadingParameters,
    @NonNull WebViewOutcomeReceiver<@Nullable Void, PrefetchException> outcomeReceiver
)

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.

Parameters
@NonNull String url

the url associated with the prefetch request.

@Nullable CancellationSignal cancellationSignal

will make the best effort to cancel an in-flight prefetch request, However cancellation is not guaranteed.

@Nullable Executor callbackExecutor

the executor to resolve the callback with. If null, the callback will be executed on the main thread.

@NonNull SpeculativeLoadingParameters speculativeLoadingParameters

parameters to customize the prefetch request.

@NonNull WebViewOutcomeReceiver<@Nullable Void, PrefetchException> outcomeReceiver

callbacks for reporting result back to application.

Throws
java.lang.IllegalArgumentException

if the url or callback is null.

java.lang.UnsupportedOperationException

if the PROFILE_URL_PREFETCH feature is not supported. This should be checked before use with isFeatureSupported.

setCrossOriginIsolatedAllowlist

Added in 1.18.0
@RequiresFeature(name = WebViewFeature.CROSS_ORIGIN_ISOLATED_ALLOWLIST, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
default void setCrossOriginIsolatedAllowlist(@NonNull Set<String> allowedOriginRules)

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.

Parameters
@NonNull Set<String> allowedOriginRules

A set of origin patterns where cross-origin-isolated APIs should be available. Avoid using the wildcard matcher. See the documentation for addWebMessageListener for syntax.

Throws
java.lang.IllegalArgumentException

if one or more of the patterns cannot be parsed.

java.lang.UnsupportedOperationException

if the CROSS_ORIGIN_ISOLATED_ALLOWLIST feature is not supported. This should be checked before use with isFeatureSupported.

setMaxPrerenders

Added in 1.17.0
@RequiresFeature(name = WebViewFeature.SET_MAX_PRERENDERS_V1, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalUrlPrefetch
default void setMaxPrerenders(@IntRange(from = 1) int maxPrerenders)

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.

Parameters
@IntRange(from = 1) int maxPrerenders

the prerender value to update.

Throws
java.lang.UnsupportedOperationException

if the SET_MAX_PRERENDERS_V1 feature is not supported. This should be checked before use with isFeatureSupported.

setSpeculativeLoadingConfig

Added in 1.13.0
Deprecated in 1.16.0
@RequiresFeature(name = WebViewFeature.SPECULATIVE_LOADING_CONFIG, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalUrlPrefetch
abstract void setSpeculativeLoadingConfig(
    @NonNull SpeculativeLoadingConfig speculativeLoadingConfig
)

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.

Parameters
@NonNull SpeculativeLoadingConfig speculativeLoadingConfig

the config to set for this profile session.

Throws
java.lang.UnsupportedOperationException

if the SPECULATIVE_LOADING_CONFIG feature is not supported. This should be checked before use with isFeatureSupported.

warmUpRendererProcess

Added in 1.15.0
@RequiresFeature(name = WebViewFeature.WARM_UP_RENDERER_PROCESS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalWarmUpRendererProcess
abstract void warmUpRendererProcess()

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.

Throws
java.lang.UnsupportedOperationException

if the WARM_UP_RENDERER_PROCESS feature is not supported. This should be checked before use with isFeatureSupported.