触发监听器

一组操作监听器，可用于触发 CFR 消息。

用法

作为 CFR 定义的一部分，消息最多可以注册一个触发器来决定何时显示消息。

大多数触发器（除非另有说明）都采用相同的参数 hosts 和/或 patterns，用于将消息定位到特定网站。

// Optional set of hosts to filter out triggers only to certain websites
let params: string[];
// Optional set of [match patterns](https://mdn.org.cn/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns) to filter out triggers only to certain websites
let patterns: string[];

{
  ...
  // Show the message when opening mozilla.org
  "trigger": { "id": "openURL", "params": ["mozilla.org", "www.mozilla.org"] }
  ...
}

{
  ...
  // Show the message when opening any HTTP, HTTPS URL.
  trigger: { id: "openURL", patterns: ["*://*/*"] }
  ...
}

可用的触发器操作

openArticleURL

当用户加载兼容阅读模式的网页时发生。

openBookmarkedURL

当用户将 URL 添加到书签或导航到已添加书签的 URL 时发生。

不按主机或模式过滤。

frequentVisits

每次用户导航到（或切换到）提供的 hosts 或 patterns 参数中的任何一个时发生。此外，它还会存储这些访问的时间戳，并将其提供回目标上下文。它们可以在目标表达式中使用。

// Has at least 3 visits in the past hour
recentVisits[.timestamp > (currentDate|date - 3600 * 1000 * 1)]|length >= 3

interface visit {
  host: string,
  timestamp: UnixTimestamp
};
// Host and timestamp for every visit to "Host"
let recentVisits: visit[];

openURL

每次用户加载与提供的 hosts 或 patterns 匹配的新 URL 时发生。在浏览会话期间，它会跟踪对唯一 URL 的访问，这些访问可以在目标表达式中使用。

// True on the third visit for the URL which the trigger matched on
visitsCount >= 3

newSavedLogin

每次用户通过登录捕获悬挂栏保存或更新登录信息时发生。提供一个 type 来区分这两个事件，这些事件可以在目标中使用。

不按主机或模式过滤。

let type = "update" | "save";

formAutofill

当用户保存、更新或使用信用卡或地址进行表单自动填充时发生。为了减少触发器的干扰，当用户在 about:preferences 中手动编辑管理器中的这些项目时，它不会触发。出于同样的原因，触发器仅在 10 秒延迟后触发。触发器上下文包括一个 event 和 type，可用于目标。可能的事件包括 add、update 和 use。可能的类型是 card 和 address。此触发器尤其旨在与 creditCardsSaved 和 addressesSaved 目标属性 结合使用。

{
  trigger: { id: "formAutofill" },
  targeting: "type == 'card' && event in ['add', 'update']"
}

contentBlocking

在文档加载结束时以及每个后续内容阻止事件发生时，或当跟踪数据库服务达到里程碑时发生。

提供当前浏览会话中加载的页面数量的上下文，可在目标中使用。

不按主机或模式过滤。

它报告的事件是以下两件事之一

defaultBrowserCheck

在启动时、打开新标签页时以及导航到 about:home 时发生。在启动时，它将 source 报告为 startup，并提供一个上下文属性 willShowDefaultPrompt，可在目标中使用以避免在内置默认浏览器提示将要显示时显示消息。这对于避免显示两个提示的负面用户体验非常重要，尤其是在两个提示都提供类似的功能时。在新标签页/主页上，它将 source 报告为 newtab。

let source = "startup" | "newtab";
let willShowDefaultPrompt = boolean | undefined;

示例

  • 仅在启动时触发，不在新标签页/主页上触发

  • 如果内置提示将要显示，则不要显示

{
  trigger: { id: "defaultBrowserCheck" },
  targeting: "source == 'startup' && !willShowDefaultPrompt"
}

deeplinkedToWindowsSettingsUI

当用户表示他们希望将 Firefox 设置为默认网络浏览器并且需要与 Windows 设置进行交互才能完成将 Firefox 设置为默认浏览器时触发。

captivePortalLogin

当用户成功完成网络连接登录流程时发生。

preferenceObserver

监视任意数量的偏好设置的更改。当偏好设置被添加、移除或修改时运行。

// Register a message with the following trigger
{
  id: "preferenceObserver",
  params: ["pref name"]
}

featureCalloutCheck

用于在 Firefox 视图中显示功能提示。只能用于功能提示。

pdfJsFeatureCalloutCheck

用于在 PDF.js 页面上显示功能提示。只能用于功能提示。

newtabFeatureCalloutCheck

用于在 about:newtab 上显示功能提示。只能用于功能提示。

nthTabClosed

当用户在一个会话中关闭 n 个或更多标签页时发生

// Register a message with the following trigger and
// include the tabsClosedCount context variable in the targeting.
// Here, the message triggers after two or more tabs are closed.
{
  trigger: { id: "nthTabClosed" },
  targeting: "tabsClosedCount >= 2"
}

activityAfterIdle

当用户在 n 毫秒的空闲时间后恢复活动时发生。键盘/鼠标交互和音频播放算作活动。当操作系统进入睡眠状态或从睡眠状态唤醒时，空闲计时器会重置。

没有参数或模式。 idleForMilliseconds 上下文变量可在目标中使用。此值表示自上次用户交互或音频播放以来的毫秒数。 60000 是此变量的最小值（1 分钟）。在以下示例中，当用户在至少 20 分钟的空闲时间后返回时，消息将触发。

// Register a message with the following trigger and include
// the idleForMilliseconds context variable in the targeting.
{
  trigger: { id: "activityAfterIdle" },
  targeting: "idleForMilliseconds >= 1200000"
}

cookieBannerDetected

当分派 cookiebannerdetected 窗口事件时发生。当以下条件为真时，将分派此事件

  1. 用户在他们正在查看的网页上显示了 Cookie 同意横幅，

  2. 该域具有用于自动参与同意横幅的有效规则集，以及

  3. 用户尚未明确选择加入或退出 Cookie 横幅处理功能。

cookieBannerHandled

当分派 cookiebannerhandled 窗口事件时发生。当以下条件为真时，将分派此事件

  1. 用户在他们正在查看的网页上显示了 Cookie 同意横幅，

  2. 该域具有用于自动参与同意横幅的有效规则集，以及

  3. 用户已选择加入 Cookie 横幅处理功能（在私有窗口中默认为此功能），以及

  4. Firefox 成功自动参与同意横幅。

messagesLoaded

加载消息后立即发生。此触发器不需要任何用户交互，并且可能在应用程序启动时或实验注册后的某个时间发生。通常用于覆盖实验，因为大多数消息无法路由，除非它们显示的界面在带标签的浏览器窗口中实例化（覆盖消息不会显示，但其触发器仍将被记录）。但是，对于普通消息，仍然可以安全地使用此触发器，但有一些注意事项。这在 macOS 上可能相关，在 macOS 上，应用程序可以在没有浏览器窗口打开的情况下运行，甚至在 Windows 上，关闭所有浏览器窗口但保留打开非浏览器窗口（例如库）会导致应用程序保持运行。

在以下情况下，toast_notification 或 update_action 消息可以正常运行。 toolbar_badge 消息会在有或没有窗口的情况下加载，但只有在窗口存在时才会真正显示。但是，使用 infobar 等模板的消息，除非存在窗口来显示它们，否则将没有任何效果。任何使用此触发器且不限于模板的消息，可以通过添加以下目标来排除无窗口或无浏览器上下文。这并不是严格必要的，因为消息传递表面要么正常工作，要么会优雅地失败，但可能需要在某些上下文中测试覆盖范围，因此提供了上下文对象 browser 和 browserWindow，分别对应于选定的浏览器 (gBrowser.selectedBrowser) 和最近活跃的 Chrome 窗口。

{
  trigger: { id: "messagesLoaded" },
  targeting: "browser && browserWindow"
}

pageActionInUrlbar

当页面操作出现在地址栏时发生。可以在目标表达式中通过 ID 指定要监视的特定页面操作。例如，要触发阅读器模式按钮出现时：

{
  trigger: { id: "pageActionInUrlbar" },
  targeting: "pageAction == 'reader-mode-button'"
}

onSearch

当用户使用酷炫栏中的搜索功能时发生。

布尔上下文变量 isSuggestion 在目标中可用，如果搜索是从酷炫栏中的推荐启动的，则其值为 true。

字符串上下文变量 searchSource 也在目标中可用，并返回搜索源。它将是四个值之一：如果使用了伪搜索输入之一（例如新标签页上的输入），则为 urlbar-handoff；如果用户已选择搜索引擎，则为 urlbar-searchmode；如果用户已切换标签页或窗口并返回到 URL 栏中的搜索词，则为 urlbar-persisted；如果用户通过在 URL 栏中输入词语并按 Enter 键或点击搜索建议来进行标准搜索，则为 urlbar。

布尔上下文变量 isOneOff 在目标中可用，如果使用了单次搜索功能之一（通常位于酷炫栏下拉菜单的底部），则其值为 true。

{
  trigger: { id: "onSearch" },
  targeting: "isSuggestion && searchSource === 'urlbar-handoff' && isOneOff"
}

sidebarToolOpened

当用户在侧边栏中打开工具或扩展面板时发生。

字符串上下文变量 view 在目标中可用，并且将对应于已打开的哪个侧边栏工具/扩展（例如：“viewHistorySidebar”、“viewBookmarksSidebar”等）。

对象上下文变量 clickCounts 也在目标中可用，以及有关特定工具或扩展已打开多少次的信息。如果任何工具/扩展（不包括 GenAI 聊天机器人）每个窗口和每个会话被点击了 5 次，则将针对 SIDEBAR_TOOL_SURVEY 调用显示。如果 GenAI 聊天机器人面板每个窗口和每个会话被打开了 2 次，则将针对 SIDEBAR_GENAI_SURVEY 调用显示。

{
  trigger: { id: "sidebarToolOpened" },
  targeting: `'sidebar.position_start'|preferenceValue && view != 'viewGenaiChatSidebar' && clickCounts.totalToolsMinusGenai == 5 && !'messaging-system-action.sidebar-tools-microsurvey-complete-or-dismissed'|preferenceValue`
}