Webkit API Development

AndroidX WebKit API Implementation Guide

Overview

This guide defines the workflow for implementing WebKit features or APIs in the AndroidX repository (frameworks/support/webkit/).

When to use this skill

• When adding feature flags to WebViewFeature and WebViewFeatureInternal.
• When implementing or modifying AndroidX WebKit APIs in frameworks/support/webkit/.
• When writing AndroidX WebKit instrumentation tests in webkit/integration-tests/instrumentation/.
• When unhiding an existing @RestrictTo(LIBRARY_GROUP) WebKit API for public release.

Workflow Overview

1. Step 0: Verify Boundary Interface: Check Features.java and boundary interfaces in external/webview_support_interfaces/. Roll from Chromium if missing.
2. Step 1: Feature Flags: Add @RestrictTo(LIBRARY_GROUP) constant in WebViewFeature.java and map in internal/WebViewFeatureInternal.java (NO @RestrictTo in internal package).
3. Step 2: App-Facing API Design:
   • Interfaces (Option A): Only for developer-implemented callbacks. Provide default method throwing UnsupportedOperationException.
   • Static Compat Classes (Option B): For extending framework classes (WebViewCompat, WebSettingsCompat). Public static method.
   • Abstract Controllers (Option C): For singletons (ServiceWorkerControllerCompat). Abstract or concrete method.
   • Domain Classes (Option D): For objects created by WebView (Navigation, Page). Concrete class wrapping internal *Impl delegate.
4. Step 3: Internal Delegation: Implement in internal/*Impl.java (no @RestrictTo). Guard with isSupportedByWebView(). Callback adapters must include feature in getSupportedFeatures().
5. Step 4: Instrumentation Tests: In webkit/integration-tests/instrumentation/. Check MULTI_PROFILE in setUp() for Profile tests. Use WebkitUtils.checkFeature(<FEATURE>) (no negative fallback tests).
6. Step 5: Unhide and Release: Remove @RestrictTo from public API and WebViewFeature.java. Add mapping to PublicFeatureAvailability.kt. Run ./gradlew :webkit:webkit:updateApi. Add Relnote: following webkit/webkit/docs/release_notes.md.

Step 0: Verify or Roll Upstream Boundary Interface

Verify boundary interface and feature constant exist in external/webview_support_interfaces/:

1. Check Features.java under external/webview_support_interfaces/ for the feature constant.
2. Check the boundary interface (such as ProfileBoundaryInterface.java or WebSettingsBoundaryInterface.java) for the method signature.
3. If not present, roll boundary interface from Chromium into external/webview_support_interfaces/ on Gerrit before proceeding.

Step 1: Define Feature Flags (WebViewFeature and WebViewFeatureInternal)

1. Public Constant (WebViewFeature.java):

   • Declare a public static final String matching the boundary feature name.
   • Add constant to @StringDef annotation (WebViewSupportFeature).
   • Annotate with @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP) while in development.

   /**
    * Feature for {@link #isFeatureSupported(String)}.
    * This feature covers {@link <TargetClass>#<methodName>(...)}.
    */
   @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP)
   public static final String <FEATURE_NAME> = "<FEATURE_NAME>";

2. Internal Mapping (internal/WebViewFeatureInternal.java):

   • Map to boundary constant from org.chromium.support_lib_boundary.util.Features.
   • Do NOT add @RestrictTo in the internal package.

   public static final ApiFeature.NoFramework <FEATURE_NAME> =
           new ApiFeature.NoFramework(WebViewFeature.<FEATURE_NAME>,
                   Features.<FEATURE_NAME>);

Step 2: App-Facing API Design by Class Type

Option A: Interfaces

• Rule: Use public interfaces only for types the app developer implements (callbacks/listeners).
• Rule: When adding methods to existing interfaces, always provide a default implementation throwing UnsupportedOperationException to prevent breaking embedders and test mocks.

@RequiresFeature(name = WebViewFeature.<FEATURE_NAME>,
        enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@UiThread
@RestrictTo(RestrictTo.Scope.LIBRARY_GROUP)
default <ReturnType> <methodName>(<Parameters>) {
    throw new UnsupportedOperationException(
            "<TargetClass>#<methodName> is not implemented.");
}

Option B: Static Compat Utility Classes

• Rule: When extending framework classes (WebView, WebSettings, CookieManager), add a public static method to *Compat taking the framework instance as first parameter.

@RequiresFeature(name = WebViewFeature.<FEATURE_NAME>,
        enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@RestrictTo(RestrictTo.Scope.LIBRARY_GROUP)
public static <ReturnType> <methodName>(
        @NonNull <FrameworkClass> instance, <Parameters>) {
    ApiFeature.<ApiLevel> feature = WebViewFeatureInternal.<FEATURE_NAME>;
    if (feature.isSupportedByFramework()) {
        ApiHelperFor<ApiLevel>.<methodName>(instance, <Parameters>);
    } else if (feature.isSupportedByWebView()) {
        getAdapter(instance).<methodName>(<Parameters>);
    } else {
        throw WebViewFeatureInternal.getUnsupportedOperationException();
    }
}

Option C: Abstract Controllers / Singletons

• Rule: For singleton controllers (ServiceWorkerControllerCompat), declare an abstract method (or concrete method throwing UnsupportedOperationException if subclassing is supported).

@RequiresFeature(name = WebViewFeature.<FEATURE_NAME>,
        enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
@RestrictTo(RestrictTo.Scope.LIBRARY_GROUP)
public abstract <ReturnType> <methodName>(<Parameters>);

Option D: Normal Domain Classes

• Rule: For domain objects provided by WebView (Navigation, Page), expose a public concrete class wrapping an internal *Impl delegate.

public class Navigation {
    private final NavigationImpl mImpl;

    @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP)
    public Navigation(@NonNull NavigationImpl impl) {
        mImpl = impl;
    }

    @RequiresFeature(name = WebViewFeature.<FEATURE_NAME>,
            enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
    @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP)
    public @Nullable String getUrl() {
        return mImpl.getUrl();
    }
}

Step 3: Implement Internal Delegation (internal/*Impl.java)

• For Interfaces, Controllers, and Domain Classes: Implement in internal/<Class>Impl.java. No @RestrictTo in internal/. Guard with isSupportedByWebView():

  @Override
  public <ReturnType> <methodName>(<Parameters>) {
      ApiFeature.NoFramework feature = WebViewFeatureInternal.<FEATURE_NAME>;
      if (feature.isSupportedByWebView()) {
          mBoundaryImpl.<methodName>(<Parameters>);
      } else {
          throw WebViewFeatureInternal.getUnsupportedOperationException();
      }
  }

• For Static Compat Classes: Delegation logic lives directly in the static method in *Compat.java.

Complex Types and Callbacks (Reflection Adapters)

1. Passing Adapters: Wrap parameter/callback in adapter and create InvocationHandler using BoundaryInterfaceReflectionUtil:

   InvocationHandler paramsBoundaryInterface =
           BoundaryInterfaceReflectionUtil.createInvocationHandlerFor(
                   new CustomParametersAdapter(params));
   
   mBoundaryImpl.performOperation(
           paramsBoundaryInterface,
           CustomCallbackAdapter.buildInvocationHandler(callback));

2. Callback getSupportedFeatures(): Callback adapters implementing FeatureFlagHolderBoundaryInterface must add the feature constant in getSupportedFeatures():

   public class CustomCallbackAdapter
           implements CustomCallbackBoundaryInterface {
       private final CustomCallback mCallback;
   
       public CustomCallbackAdapter(@NonNull CustomCallback callback) {
           mCallback = callback;
       }
   
       @Override
       public @NonNull String[] getSupportedFeatures() {
           return new String[] {
               Features.<FEATURE_NAME>,
           };
       }
   
       @Override
       public void onResult(int status) {
           mCallback.onResult(status);
       }
   }

3. Receiving Boundary Objects: Cast InvocationHandler back using BoundaryInterfaceReflectionUtil.castToSuppLibClass:

   InvocationHandler boundaryObject = mBoundaryImpl.getFeatureObject();
   mFeatureObject = new FeatureObject(Objects.requireNonNull(
           BoundaryInterfaceReflectionUtil.castToSuppLibClass(
                   FeatureObjectBoundaryInterface.class, boundaryObject)));