Profile


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

const String!

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

Public functions

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

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

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

This function is deprecated.

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

Boolean

Returns whether configureIsolatedSites can be called on this profile.

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

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

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

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

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

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

Unit
@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.

Unit

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.

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

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

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

Returns the profile's cookie manager.

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

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

Returns all custom headers set with addCustomHeader.

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

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

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

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

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

Returns the geolocation permissions of the profile.

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

Returns the HttpCache associated with this Profile.

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.

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

Returns the name of this Profile.

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

Returns the service worker controller of the profile.

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

Returns the profile's web storage.

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

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

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

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

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

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

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

This function is deprecated.

Use prefetchUrlAsync instead.

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

This function is deprecated.

Use prefetchUrlAsync instead.

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

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

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

Sets the max prerenders for the current profile session.

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

This function is deprecated.

use setMaxPrerenders, setMaxPrefetches and setPrefetchTtlSeconds instead.

Unit
@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
const val DEFAULT_PROFILE_NAME = "Default": String!

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

Public functions

addCustomHeader

Added in 1.15.0
@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.

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
header: CustomHeader

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

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
urls: (Mutable)Set<String>

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
fun canConfigureIsolatedSites(): Boolean

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
fun clearAllCustomHeaders(): Unit

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

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
headerName: String

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
fun clearCustomHeader(headerName: String, headerValue: String): Unit

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
headerName: String

Header name to remove.

headerValue: String

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

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
fun configureIsolatedSites(sites: (Mutable)Set<String>): Unit

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
sites: (Mutable)Set<String>

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

Parameters
url: String

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")
fun getCookieManager(): CookieManager

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

Returns
(Mutable)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
fun getCustomHeaders(): (Mutable)Set<CustomHeader!>

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
fun getCustomHeaders(name: String): (Mutable)Set<CustomHeader!>

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

This method is case insensitive.

Parameters
name: String

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

Parameters
name: String

Name of headers to get. Case sensitive.

value: String

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")
fun getGeolocationPermissions(): GeolocationPermissions

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
fun getHttpCache(): HttpCache

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
fun getMaxPrerenders(): Int

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")
fun getName(): String

Returns the name of this Profile.

Returns
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")
fun getServiceWorkerController(): ServiceWorkerController

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")
fun getWebStorage(): WebStorage

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
fun hasCustomHeader(headerName: String): Boolean

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

This method is case insensitive.

Parameters
headerName: String

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

Parameters
url: String

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

Parameters
urls: (Mutable)Set<String>

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

Parameters
url: String

the url associated with the prefetch request.

cancellationSignal: CancellationSignal?

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

callbackExecutor: Executor?

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

outcomeReceiver: WebViewOutcomeReceiver<Void?, PrefetchException!>

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

Parameters
url: String

the url associated with the prefetch request.

cancellationSignal: CancellationSignal?

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

callbackExecutor: Executor?

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

speculativeLoadingParameters: SpeculativeLoadingParameters

parameters to customize the prefetch request.

outcomeReceiver: WebViewOutcomeReceiver<Void?, PrefetchException!>

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

Parameters
allowedOriginRules: (Mutable)Set<String!>

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

Parameters
maxPrerenders: @IntRange(from = 1) Int

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

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

Throws
java.lang.UnsupportedOperationException

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