WebView: update SafeBrowsing documentation
No change in logic, only docs changes:
* Docs about Safe Browsing feature as a whole.
* Expand the docs for initSafeBrowsing/shutdownSafeBrowsing
Bug: 63660204
Bug: 62192626
Test: make update-api and manually check javadocs
Change-Id: I6526a0f1ce1327f6eff416c27ded89866587f173
diff --git a/core/java/android/webkit/WebSettings.java b/core/java/android/webkit/WebSettings.java
index 3a6de96..82cff7c 100644
--- a/core/java/android/webkit/WebSettings.java
+++ b/core/java/android/webkit/WebSettings.java
@@ -1390,17 +1390,15 @@
* Sets whether Safe Browsing is enabled. Safe browsing allows WebView to
* protect against malware and phishing attacks by verifying the links.
*
- * Safe browsing is disabled by default. The recommended way to enable
- * Safe browsing is using a manifest tag to change the default value to
- * enabled for all WebViews.
* <p>
- * <pre>
- * <meta-data android:name="android.webkit.WebView.EnableSafeBrowsing"
- * android:value="true" />
- * </pre>
+ * Safe browsing is disabled by default. The recommended way to enable Safe browsing is using a
+ * manifest tag to change the default value to enabled for all WebViews (read <a
+ * href="{@docRoot}reference/android/webkit/WebView.html">general Safe Browsing info</a>).
* </p>
*
+ * <p>
* This API overrides the manifest tag value for this WebView.
+ * </p>
*
* @param enabled Whether Safe browsing is enabled.
*/
diff --git a/core/java/android/webkit/WebView.java b/core/java/android/webkit/WebView.java
index 333c44c..b9abadb 100644
--- a/core/java/android/webkit/WebView.java
+++ b/core/java/android/webkit/WebView.java
@@ -319,6 +319,22 @@
* out.
* </p>
*
+ * <h3>Safe Browsing</h3>
+ *
+ * <p>
+ * If Safe Browsing is enabled, WebView will block malicious URLs and present a warning UI to the
+ * user to allow them to navigate back safely or proceed to the malicious page.
+ * </p>
+ * <p>
+ * The recommended way for apps to enable the feature is putting the following tag in the manifest:
+ * </p>
+ * <p>
+ * <pre>
+ * <meta-data android:name="android.webkit.WebView.EnableSafeBrowsing"
+ * android:value="true" />
+ * </pre>
+ * </p>
+ *
*/
// Implementation notes.
// The WebView is a thin API class that delegates its public API to a backend WebViewProvider
@@ -1622,8 +1638,24 @@
}
/**
- * Starts Safe Browsing initialization. This should only be called once. This does not require
- * an Activity Context, and will always use the application Context to do its work.
+ * Starts Safe Browsing initialization. This should only be called once.
+ *
+ * <p>
+ * Because the Safe Browsing feature takes time to initialize, WebView may temporarily whitelist
+ * URLs until the feature is ready. The callback will be invoked with true once initialization
+ * is complete.
+ * </p>
+ *
+ * <p>
+ * This does not enable the Safe Browsing feature itself, and should only be used if the feature
+ * is otherwise enabled.
+ * </p>
+ *
+ * <p>
+ * This does not require an Activity Context, and will always use the application Context to do
+ * its work.
+ * </p>
+ *
* @param context Application Context.
* @param callback will be called with the value true if initialization is
* successful. The callback will be run on the UI thread.
@@ -1633,7 +1665,9 @@
}
/**
- * Shuts down Safe Browsing. This should only be called once.
+ * Shuts down Safe Browsing. This should only be called once. This does not disable the feature,
+ * it only frees resources used by Safe Browsing code. To disable Safe Browsing on an individual
+ * WebView, see {@link WebSettings#setSafeBrowsingEnabled}
*/
public static void shutdownSafeBrowsing() {
getFactory().getStatics().shutdownSafeBrowsing();