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
Constants |
|
|---|---|
default static final String |
DEFAULT_PROFILE_NAME = "Default"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")Add a header for outgoing requests that match the given origin rules. |
default void |
@RequiresFeature(name = WebViewFeature.CUSTOM_REQUEST_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")Remove any currently set headers from being applied to network requests. |
abstract void |
@RequiresFeature(name = WebViewFeature.ORIGIN_MATCHED_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")Remove any currently set headers from being applied to network requests. |
default void |
@RequiresFeature(name = WebViewFeature.CUSTOM_REQUEST_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")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")Removes the specified header from the set of headers attached to requests. |
abstract void |
@RequiresFeature(name = WebViewFeature.ORIGIN_MATCHED_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")Removes the specified header from the set of headers attached to requests. |
abstract void |
@RequiresFeature(name = WebViewFeature.PROFILE_URL_PREFETCH, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")Removes a cached prefetch response for the provided url if it exists, otherwise does nothing. |
abstract @NonNull CookieManager |
@AnyThreadReturns the profile's cookie manager. |
default @NonNull Set<CustomHeader> |
@RequiresFeature(name = WebViewFeature.CUSTOM_REQUEST_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")Returns all custom headers set with |
default @NonNull Set<CustomHeader> |
@RequiresFeature(name = WebViewFeature.CUSTOM_REQUEST_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")Returns all custom headers set with |
default @NonNull Set<CustomHeader> |
@RequiresFeature(name = WebViewFeature.CUSTOM_REQUEST_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")Returns all custom headers set with |
abstract @NonNull GeolocationPermissions |
@AnyThreadReturns the geolocation permissions of the profile. |
abstract @NonNull String |
@AnyThread |
abstract @NonNull ServiceWorkerController |
@AnyThreadReturns the service worker controller of the profile. |
abstract @NonNull WebStorage |
@AnyThreadReturns the profile's web storage. |
default boolean |
@RequiresFeature(name = WebViewFeature.CUSTOM_REQUEST_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")Returns true if the profile has a value set for the given header name. |
abstract boolean |
@RequiresFeature(name = WebViewFeature.ORIGIN_MATCHED_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")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")Preconnects to the given origin, this can speed up future loads. |
abstract void |
@RequiresFeature(name = WebViewFeature.PROFILE_URL_PREFETCH, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")Starts a URL prefetch request. |
abstract void |
@RequiresFeature(name = WebViewFeature.PROFILE_URL_PREFETCH, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")Starts a URL prefetch request. |
abstract void |
@RequiresFeature(name = WebViewFeature.ORIGIN_MATCHED_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")Set a custom header to be applied to HTTP requests to the specified origins. |
abstract void |
@RequiresFeature(name = WebViewFeature.SPECULATIVE_LOADING_CONFIG, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")Sets the |
abstract void |
@RequiresFeature(name = WebViewFeature.WARM_UP_RENDERER_PROCESS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")Initiates warm-up of the renderer process associated with this Profile. |
Constants
DEFAULT_PROFILE_NAME
default static final String DEFAULT_PROFILE_NAME = "Default"
Represents the name of the default profile which can't be deleted.
Public methods
addCustomHeader
@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.
It applies to all requests that are initiated after this method is called, including prefetch requests and requests sent from service workers. It does not apply the header to WebSocket requests.
Headers added through this API will be present in the set returned by getRequestHeaders provided in shouldInterceptRequest.
If this method is called multiple times with headers that have the same name and value, then the sets of 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.
| Parameters | |
|---|---|
@NonNull CustomHeader header |
The header to add. |
clearAllCustomHeaders
@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.
| See also | |
|---|---|
addCustomHeader |
|
setOriginMatchedHeader |
clearAllOriginMatchedHeaders
@RequiresFeature(name = WebViewFeature.ORIGIN_MATCHED_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalOriginMatchedHeader
abstract void clearAllOriginMatchedHeaders()
Remove any currently set headers from being applied to network requests.
| See also | |
|---|---|
setOriginMatchedHeader |
clearCustomHeader
@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.
It is safe to call this method even if headerName has not previously been set via addCustomHeader or setOriginMatchedHeader.
| See also | |
|---|---|
addCustomHeader |
clearCustomHeader
@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.
It is safe to call this method even if (headerName, headerValue) has not previously been set via addCustomHeader or setOriginMatchedHeader.
| Parameters | |
|---|---|
@NonNull String headerName |
Header name to remove. |
@NonNull String headerValue |
Header value to remove. |
| See also | |
|---|---|
addCustomHeader |
clearOriginMatchedHeader
@RequiresFeature(name = WebViewFeature.ORIGIN_MATCHED_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalOriginMatchedHeader
abstract void clearOriginMatchedHeader(@NonNull String headerName)
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
| See also | |
|---|---|
setOriginMatchedHeader |
clearPrefetchAsync
@RequiresFeature(name = WebViewFeature.PROFILE_URL_PREFETCH, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalUrlPrefetch
abstract void clearPrefetchAsync(
@NonNull String url,
@NonNull Executor callbackExecutor,
@NonNull OutcomeReceiverCompat<Void, PrefetchException> operationCallback
)
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 | |
|---|---|
@NonNull String url |
the url associated with the prefetch request. Should be an exact match with the URL passed to prefetchUrlAsync. |
@NonNull Executor callbackExecutor |
the executor to resolve the callback with. |
@NonNull OutcomeReceiverCompat<Void, PrefetchException> operationCallback |
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
@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 |
getCustomHeaders
@RequiresFeature(name = WebViewFeature.CUSTOM_REQUEST_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@RequiresApi(api = Build.VERSION_CODES.N)
default @NonNull Set<CustomHeader> getCustomHeaders()
Returns all custom headers set with addCustomHeader or setOriginMatchedHeader.
getCustomHeaders
@RequiresFeature(name = WebViewFeature.CUSTOM_REQUEST_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@RequiresApi(api = Build.VERSION_CODES.N)
default @NonNull Set<CustomHeader> getCustomHeaders(@NonNull String name)
Returns all custom headers set with addCustomHeader or setOriginMatchedHeader which have the specified name.
getCustomHeaders
@RequiresFeature(name = WebViewFeature.CUSTOM_REQUEST_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@RequiresApi(api = Build.VERSION_CODES.N)
default @NonNull Set<CustomHeader> getCustomHeaders(@NonNull String name, @NonNull String value)
Returns all custom headers set with addCustomHeader or setOriginMatchedHeader which have the specified name and value.
getGeolocationPermissions
@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 |
getName
@AnyThread
@RequiresFeature(name = WebViewFeature.MULTI_PROFILE, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
abstract @NonNull String getName()
getServiceWorkerController
@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 |
getWebStorage
@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 |
hasCustomHeader
@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.
| Returns | |
|---|---|
boolean |
|
| See also | |
|---|---|
addCustomHeader |
hasOriginMatchedHeader
@RequiresFeature(name = WebViewFeature.ORIGIN_MATCHED_HEADERS, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalOriginMatchedHeader
abstract boolean hasOriginMatchedHeader(@NonNull String headerName)
Returns true if the profile has a value set for the given header name.
| Returns | |
|---|---|
boolean |
|
| See also | |
|---|---|
setOriginMatchedHeader |
preconnect
@RequiresFeature(name = WebViewFeature.PRECONNECT, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@Profile.ExperimentalPreconnect
default void preconnect(@NonNull String url)
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.
prefetchUrlAsync
@RequiresFeature(name = WebViewFeature.PROFILE_URL_PREFETCH, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@AnyThread
@Profile.ExperimentalUrlPrefetch
abstract void prefetchUrlAsync(
@NonNull String url,
@Nullable CancellationSignal cancellationSignal,
@NonNull Executor callbackExecutor,
@NonNull OutcomeReceiverCompat<Void, PrefetchException> operationCallback
)
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. |
@NonNull Executor callbackExecutor |
the executor to resolve the callback with. |
@NonNull OutcomeReceiverCompat<Void, PrefetchException> operationCallback |
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
abstract void prefetchUrlAsync(
@NonNull String url,
@Nullable CancellationSignal cancellationSignal,
@NonNull Executor callbackExecutor,
@NonNull SpeculativeLoadingParameters speculativeLoadingParameters,
@NonNull OutcomeReceiverCompat<Void, PrefetchException> operationCallback
)
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. |
@NonNull Executor callbackExecutor |
the executor to resolve the callback with. |
@NonNull SpeculativeLoadingParameters speculativeLoadingParameters |
parameters to customize the prefetch request. |
@NonNull OutcomeReceiverCompat<Void, PrefetchException> operationCallback |
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
abstract void setOriginMatchedHeader(
@NonNull String headerName,
@NonNull String headerValue,
@NonNull Set<String> originRules
)
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.
setSpeculativeLoadingConfig
@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. |
warmUpRendererProcess
@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.