browser.privacy

说明

使用 chrome.privacy API 控制 Chrome 中可能影响用户隐私的功能的使用。此 API 依赖于 Types API 的 ChromeSetting 原型来获取和设置 Chrome 的配置。

权限

privacy

您必须在扩展程序的清单中声明“privacy”权限，才能使用该 API。例如：

{
  "name": "My extension",
  ...
  "permissions": [
    "privacy"
  ],
  ...
}

概念和用法

读取 Chrome 设置的当前值非常简单。您首先需要找到您感兴趣的属性，然后对该对象调用 get()，以检索其当前值和扩展程序的控制级别。例如，如需确定是否启用了 Chrome 的信用卡自动填充功能，您可以编写以下代码：

browser.privacy.services.autofillCreditCardEnabled.get({}, function(details) {
  if (details.value) {
    console.log('Autofill is on!');
  } else {
    console.log('Autofill is off!');
  }
});

更改设置的值稍微复杂一些，因为您必须首先验证您的扩展程序是否可以控制该设置。如果您的扩展程序切换的设置已被企业政策锁定为特定值（levelOfControl 将设置为“not_controllable”），或者另一个扩展程序正在控制该值（levelOfControl 将设置为“controlled_by_other_extensions”），则用户不会看到其设置发生任何变化。set() 调用会成功，但设置会立即被覆盖。由于这可能会造成混淆，因此建议在用户选择的设置未实际应用时向用户发出警告。

这意味着您应该使用 get() 方法来确定您的访问权限级别，然后仅在您的扩展程序可以控制设置时调用 set()（事实上，如果您的扩展程序无法控制设置，最好以直观的方式停用该功能，以减少用户困惑）：

browser.privacy.services.autofillCreditCardEnabled.get({}, function(details) {
  if (details.levelOfControl === 'controllable_by_this_extension') {
    browser.privacy.services.autofillCreditCardEnabled.set({ value: true }, function() {
      if (browser.runtime.lastError === undefined) {
        console.log("Hooray, it worked!");
      } else {
        console.log("Sadness!", browser.runtime.lastError);
      }
    });
  }
});

如果您对设置值的更改感兴趣，请为其 onChange 事件添加监听器。除其他用途外，这还可让您在以下情况下向用户发出警告：新安装的扩展程序控制了某项设置，或者企业政策覆盖了您的控制。例如，如需监听信用卡自动填充状态的变化，以下代码就足够了：

browser.privacy.services.autofillCreditCardEnabled.onChange.addListener(
  function (details) {
    // The new value is stored in `details.value`, the new level of control
    // in `details.levelOfControl`, and `details.incognitoSpecific` will be
    // `true` if the value is specific to Incognito mode.
  }
);

示例

如需试用此 API，请从 chrome-extension-samples 代码库中安装隐私 API 示例。

类型

AutofillBlockedType

Chrome 151 及更高版本

自动填充数据的类别。

枚举

"contact_info"

"payments"

"identity_docs"

"travel"

"all"

IPHandlingPolicy

Chrome 48+ browser.*（自 Chrome 148 起）

WebRTC 的 IP 处理政策。

枚举

"default"

"default_public_and_private_interfaces"

"default_public_interface_only"

"disable_non_proxied_udp"

属性

network

影响 Chrome 处理网络连接的一般方式的设置。

类型

对象

属性

  • networkPredictionEnabled

    types.ChromeSetting<boolean>

    如果启用此设置，Chrome 会尝试通过以下方式加快您的网页浏览体验：预解析 DNS 条目、抢先打开与服务器的 TCP 和 SSL 连接，以及预加载网页。停用此偏好设置会覆盖网站所有者推测加载内容（例如通过 Speculation Rules API 预提取或预渲染）的能力。它不会影响由网页发起的预连接或 DNS 预提取。此偏好设置的值为布尔值，默认值为 true。

  • webRTCIPHandlingPolicy

    types.ChromeSetting<IPHandlingPolicy>

    Chrome 48+ browser.*（自 Chrome 148 起）

    允许用户指定媒体性能/隐私权权衡，这会影响 WebRTC 流量的路由方式以及公开的本地地址信息量。此偏好设置的值类型为 IPHandlingPolicy，默认值为 default。

services

这些设置可启用或停用需要 Google 和默认搜索服务提供商提供的第三方网络服务的功能。

类型

对象

属性

  • alternateErrorPagesEnabled

    types.ChromeSetting<boolean>

    如果启用此设置，Chrome 会使用网络服务来帮助解决导航错误。此偏好设置的值为布尔值，默认值为 true。

  • autofillAddressEnabled

    types.ChromeSetting<boolean>

    Chrome 70 及更高版本 browser.*（自 Chrome 148 起）

    如果启用此设置，Chrome 会提供自动填充地址和其他表单数据的功能。此偏好设置的值为布尔值，默认值为 true。

  • autofillCreditCardEnabled

    types.ChromeSetting<boolean>

    Chrome 70 及更高版本 browser.*（自 Chrome 148 起）

    如果启用此设置，Chrome 会提供自动填充信用卡表单的功能。此偏好设置的值为布尔值，默认值为 true。

  • autofillEnabled

    types.ChromeSetting<boolean>

    自 Chrome 70 起已弃用

    请使用 privacy.services.autofillAddressEnabled 和 privacy.services.autofillCreditCardEnabled。此版本中保留了该字段，以实现向后兼容性，但未来会将其移除。

    如果启用此设置，Chrome 会提供自动填充表单功能。此偏好设置的值为布尔值，默认值为 true。

  • passwordSavingEnabled

    types.ChromeSetting<boolean>

    如果启用此设置，密码管理工具会询问您是否要保存密码。此偏好设置的值为布尔值，默认值为 true。

  • safeBrowsingEnabled

    types.ChromeSetting<boolean>

    启用后，Chrome 会尽力保护您免受钓鱼式攻击和恶意软件的侵害。此偏好设置的值为布尔值，默认值为 true。

  • safeBrowsingExtendedReportingEnabled

    types.ChromeSetting<boolean>

    如果启用此设置，当安全浏览功能屏蔽某个网页时，Chrome 会向 Google 发送更多信息，例如被屏蔽网页的内容。此偏好设置的值为布尔值，默认值为 false。

  • searchSuggestEnabled

    types.ChromeSetting<boolean>

    如果启用此设置，Chrome 会将您在多功能框中输入的文字发送给您的默认搜索引擎，后者会根据您目前输入的内容提供可能的网站和搜索预测。此偏好设置的值为布尔值，默认值为 true。

  • spellingServiceEnabled

    types.ChromeSetting<boolean>

    如果启用此设置，Chrome 会使用网络服务来帮助更正拼写错误。此偏好设置的值为布尔值，默认值为 false。

  • translationServiceEnabled

    types.ChromeSetting<boolean>

    如果启用此设置，Chrome 会询问是否翻译您看不懂的语言。此偏好设置的值为布尔值，默认值为 true。

websites

用于确定 Chrome 向网站提供哪些信息的设置。

类型

对象

属性

  • adMeasurementEnabled

    types.ChromeSetting<boolean>

    Chrome 111 及更高版本 browser.*（自 Chrome 148 起）

    如果停用，Attribution Reporting API 和 Private Aggregation API 将停用。此偏好设置的值为布尔值类型，默认值为 true。扩展程序只能通过将值设置为 false 来停用这些 API。如果您尝试将这些 API 设置为 true，系统会抛出错误。

  • doNotTrackEnabled

    types.ChromeSetting<boolean>

    Chrome 65 及更高版本 自 Chrome 148 起为 browser.*

    如果启用此设置，Chrome 会在您的请求中发送“Do Not Track”(DNT: 1) 标头。此偏好设置的值为布尔值类型，默认值为 false。

  • fledgeEnabled

    types.ChromeSetting<boolean>

    Chrome 111 及更高版本 browser.*（自 Chrome 148 起）

    如果停用，Fledge API 将处于停用状态。此偏好设置的值为布尔值类型，默认值为 true。扩展程序只能通过将值设置为 false 来停用此 API。如果您尝试将此 API 设置为 true，系统会抛出错误。

  • hyperlinkAuditingEnabled

    types.ChromeSetting<boolean>

    如果启用此设置，Chrome 会在网站请求时发送审核 ping (<a ping>)。此偏好设置的值为布尔值，默认值为 true。

  • protectedContentEnabled

    types.ChromeSetting<boolean>

    仅适用于 Windows 和 ChromeOS：如果启用此设置，Chrome 会向插件提供唯一 ID，以便运行受保护的内容。此偏好设置的值为布尔值类型，默认值为 true。

  • referrersEnabled

    types.ChromeSetting<boolean>

    如果启用此政策，Chrome 会在您的请求中发送 referer 标头。是的，此偏好设置的名称与拼写错误的标头不匹配。不，我们不会更改。此偏好设置的值为布尔值类型，默认值为 true。

  • thirdPartyCookiesAllowed

    types.ChromeSetting<boolean>

    如果停用此政策，Chrome 会阻止第三方网站设置 Cookie。此偏好设置的值为布尔值类型，默认值为 true。在无痕模式下，第三方 Cookie 会被屏蔽，并且只能在网站级别允许使用，因此扩展程序可能无法在无痕模式下启用此 API。如果您尝试在无痕模式下将此 API 设置为 true，则会抛出错误。

    注意：当此 API 返回 false 时，如果个别网站具有有效的豁免或改用 Storage Access API，则可能仍能访问第三方 Cookie。

  • topicsEnabled

    types.ChromeSetting<boolean>

    Chrome 111 及更高版本 browser.*（自 Chrome 148 起）

    如果停用，Topics API 将处于停用状态。此偏好设置的值为布尔值类型，默认值为 true。扩展程序只能通过将值设置为 false 来停用此 API。如果您尝试将此 API 设置为 true，系统会抛出错误。