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 OriginMatchedHeader API surface is experimental.

Denotes that the Profile#preconnect 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.ORIGIN_MATCHED_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalOriginMatchedHeader
clearAllOriginMatchedHeaders()

Remove any currently set headers from being applied to network requests.
Unit
@RequiresFeature(name = WebViewFeature.ORIGIN_MATCHED_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalOriginMatchedHeader
clearOriginMatchedHeader(headerName: String)

Removes the specified header from the set of headers attached to requests.
Unit
@RequiresFeature(name = WebViewFeature.PROFILE_URL_PREFETCH, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalUrlPrefetch
clearPrefetchAsync(
    url: String,
    callbackExecutor: Executor,
    operationCallback: OutcomeReceiverCompat<Void!, PrefetchException!>
)

Removes a cached prefetch response for the provided url if it exists, otherwise does nothing.
CookieManager
@AnyThread
@RequiresFeature(name = WebViewFeature.MULTI_PROFILE, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
getCookieManager()

Returns the profile's cookie manager.
GeolocationPermissions
@AnyThread
@RequiresFeature(name = WebViewFeature.MULTI_PROFILE, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
getGeolocationPermissions()

Returns the geolocation permissions of the profile.
String
@AnyThread
@RequiresFeature(name = WebViewFeature.MULTI_PROFILE, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
getName()
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.ORIGIN_MATCHED_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalOriginMatchedHeader
hasOriginMatchedHeader(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)

Preconnects to the given origin, this can speed up future loads.
Unit
@RequiresFeature(name = WebViewFeature.PROFILE_URL_PREFETCH, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@AnyThread
@Profile.ExperimentalUrlPrefetch
prefetchUrlAsync(
    url: String,
    cancellationSignal: CancellationSignal?,
    callbackExecutor: Executor,
    operationCallback: OutcomeReceiverCompat<Void!, PrefetchException!>
)

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

Starts a URL prefetch request.
Unit
@RequiresFeature(name = WebViewFeature.ORIGIN_MATCHED_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalOriginMatchedHeader
setOriginMatchedHeader(
    headerName: String,
    headerValue: String,
    originRules: (Mutable)Set<String!>
)

Set a custom header to be applied to HTTP requests to the specified origins.
Unit
@RequiresFeature(name = WebViewFeature.SPECULATIVE_LOADING_CONFIG, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalUrlPrefetch
setSpeculativeLoadingConfig(
    speculativeLoadingConfig: SpeculativeLoadingConfig
)

Sets the SpeculativeLoadingConfig for the current profile session.
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

clearAllOriginMatchedHeaders

@RequiresFeature(name = WebViewFeature.ORIGIN_MATCHED_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalOriginMatchedHeader
fun clearAllOriginMatchedHeaders(): Unit

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

See also
setOriginMatchedHeader

clearOriginMatchedHeader

@RequiresFeature(name = WebViewFeature.ORIGIN_MATCHED_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalOriginMatchedHeader
fun clearOriginMatchedHeader(headerName: String): Unit

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

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

Parameters
headerName: String

Header to remove.
See also
setOriginMatchedHeader

clearPrefetchAsync

@RequiresFeature(name = WebViewFeature.PROFILE_URL_PREFETCH, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalUrlPrefetch
fun clearPrefetchAsync(
    url: String,
    callbackExecutor: Executor,
    operationCallback: OutcomeReceiverCompat<Void!, PrefetchException!>
): Unit

Removes a cached prefetch response for the provided url if it exists, otherwise does nothing.

Calling this does not guarantee that the prefetched response will not be served to a WebView before it is cleared.

Parameters
url: String

the url associated with the prefetch request. Should be an exact match with the URL passed to prefetchUrlAsync.
callbackExecutor: Executor

the executor to resolve the callback with.
operationCallback: OutcomeReceiverCompat<Void!, PrefetchException!>

runs when the clear operation is complete Or and error occurred during it.
Throws
java.lang.IllegalArgumentException

if the url or callback is null.

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

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

getName

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

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

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

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

hasOriginMatchedHeader

@RequiresFeature(name = WebViewFeature.ORIGIN_MATCHED_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalOriginMatchedHeader
fun hasOriginMatchedHeader(headerName: String): Boolean

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

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.
See also
setOriginMatchedHeader

preconnect

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

Preconnects to the given origin, this can speed up future loads.

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.

prefetchUrlAsync

@RequiresFeature(name = WebViewFeature.PROFILE_URL_PREFETCH, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@AnyThread
@Profile.ExperimentalUrlPrefetch
fun prefetchUrlAsync(
    url: String,
    cancellationSignal: CancellationSignal?,
    callbackExecutor: Executor,
    operationCallback: OutcomeReceiverCompat<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.
operationCallback: OutcomeReceiverCompat<Void!, PrefetchException!>

callbacks for reporting result back to application.
Throws
java.lang.IllegalArgumentException

if the url or callback is null.

prefetchUrlAsync

@RequiresFeature(name = WebViewFeature.PROFILE_URL_PREFETCH, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@AnyThread
@Profile.ExperimentalUrlPrefetch
fun prefetchUrlAsync(
    url: String,
    cancellationSignal: CancellationSignal?,
    callbackExecutor: Executor,
    speculativeLoadingParameters: SpeculativeLoadingParameters,
    operationCallback: OutcomeReceiverCompat<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.
speculativeLoadingParameters: SpeculativeLoadingParameters

parameters to customize the prefetch request.
operationCallback: OutcomeReceiverCompat<Void!, PrefetchException!>

callbacks for reporting result back to application.
Throws
java.lang.IllegalArgumentException

if the url or callback is null.

setOriginMatchedHeader

@RequiresFeature(name = WebViewFeature.ORIGIN_MATCHED_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalOriginMatchedHeader
fun setOriginMatchedHeader(
    headerName: String,
    headerValue: String,
    originRules: (Mutable)Set<String!>
): Unit

Set a custom header to be applied to HTTP requests to the specified origins.

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

Calling this method again with the same headerName parameter will overwrite any previously set mapping.

Parameters
headerName: String

A valid HTTP header name string
headerValue: String

A valid HTTP value name string
originRules: (Mutable)Set<String!>

a set of origin rules following the same format as addWebMessageListener

setSpeculativeLoadingConfig

Added in 1.13.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.

warmUpRendererProcess

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