用户交互¶

后台挂起报告器是一个工具，用于在预发布通道上挂起期间收集堆栈。用户交互是一种使用有关用户在挂起发生时正在执行的操作的附加信息来注释后台挂起报告的方法。这允许根据发生挂起的用户交互对挂起进行分组和优先级排序。

由于内置的分析器通常是开发人员用来调试性能问题的第一个工具，因此用户交互还将为每个记录添加分析器标记。

重要

Firefox 中的每个新的或更改的数据收集都需要来自数据管理员的数据收集审查。

序列化格式¶

用户交互以 “backgroundhangmonitor” Ping 的形式提交，作为挂起 annotations 下的一个属性，例如：

...
{
  "duration": 105.547582,
  // ...
  "annotations": [
    ["UserInteracting", "true"]
    ["browser.tabs.opening", "animated"]
  ],
  "stack": [
    "XREMain::XRE_main",
    "-[GeckoNSApplication nextEventMatchingMask:untilDate:inMode:dequeue:]",
    "nsAppShell::ProcessGeckoEvents",
    "nsRefreshDriver::Tick",
    "EventDispatcher::Dispatch",
    "EventDispatcher::Dispatch",
    "",
    "browser/content/tabbrowser-tabs.js:1699",
    "browser/content/tabbrowser-tabs.js:1725",
    "browser/content/tabbrowser-tabs.js:142",
    "browser/content/tabbrowser-tabs.js:153",
    "(jit frame)",
    "(unresolved)",
    [
      1,
      "418de17"
    ],
    [
      1,
      "418de91"
    ],
    [
      1,
      "4382e56"
    ],
    [
      8,
      "108e3"
    ],
    [
      9,
      "2624"
    ],
    [
      9,
      "129f"
    ]
  ]
  // ...
},

每个用户交互都采用以下形式

["User Interaction ID", "value"]

“用户交互 ID”是其类别与名称的组合。例如，类别为 browser.tabs 且名称为 opening 的用户交互的 ID 为 browser.tabs.opening。

限制¶

每个标记为标识符的 String（用户交互 name、category、value）都限制为由字母数字 ASCII 字符 ([a-zA-Z0-9]) 以及中缀下划线（“_” 字符，不能作为第一个或最后一个字符）组成。category 还允许中缀句点（“.” 字符，只要它们不是第一个或最后一个字符）。

几个字段受长度限制

category：最大字节长度为 40。
User Interaction 名称：最大字节长度为 40。
value：UTF-8 字符串，最大字节长度为 50。

任何超过其限制的 String 将报告为错误，并且操作将中止。

YAML 定义文件¶

记录到 Firefox 遥测中的任何用户交互都必须在记录之前进行注册。对于作为 Firefox 的一部分发布的任何代码，这发生在 UserInteractions.yaml 中。

定义文件中的用户交互以固定深度的三级结构表示。第一级包含类别名称（将多个用户交互分组在一起），第二级包含用户交互 ID，用户交互属性列在该 ID 下。例如：

# The following is a category of User Interactions named "browser.tabs".
browser.tabs:
  opening: # This is the name of the User Interaction. The ID for the
           # User Interaction is browser.tabs.opening
    description: >
      Describes this User Interaction in detail, potentially over
      multiple lines.
    # ... and more User Interaction properties.
  # ... and more User Interactions.
# This is the "browser.places" category.
browser.places:
  # And the "history" search User Interaction. Its User Interaction ID is
  # browser.places.history_async
  history_async:
    # ...
    description: Session History is searched asynchronously.
    # ... and more User Interaction properties.
  # ...

类别和用户交互名称受上面指定的限制。

分析器标记¶

为每个用户交互自动添加的分析器标记将具有与用户交互记录相对应的起点和终点。标记的名称将是用户交互类别加上用户交互 ID。标记的值将是通过 UserInteraction API 传递的值，以及在记录完成后可选添加的任何其他文本。

有关分析器是什么以及分析器标记是什么的更多详细信息，请参见此处。

API¶

公共 JS API¶

此 API 仅限主线程，如果从主线程之外访问所有函数，则将返回 false。

`start()`¶

UserInteraction.start(id, value, object);

开始记录用户交互。在此用户交互记录期间在主线程上发生的任何挂起都会导致向后台挂起报告添加注释。

如果使用相同的 id 和相同的 object 已经存在一个预先存在的 UserInteraction，则该预先存在的 UserInteraction 将被覆盖。新创建的 UserInteraction 将在其 BHR 注释名称上包含“（覆盖）”后缀。

id：必需。字符串值，限制为 80 个字符。这是类别名称与用户交互名称的组合。
value：必需。字符串值，限制为 50 个字符。
object：可选。如果指定，则用户交互与该对象相关联，因此可以同时进行多次记录。

示例

UserInteraction.start("browser.tabs.opening", "animated", window1);
UserInteraction.start("browser.tabs.opening", "animated", window2);

如果由于某种原因记录未开始，则返回 false 并将消息记录到浏览器控制台。

示例

UserInteraction.start("browser.tabs.opening", "animated", window);
UserInteraction.start("browser.places.history_search", "synchronous");

`update()`¶

UserInteraction.update(id, value, object);

使用新值更新正在记录的用户交互。在主线程上发生的任何挂起都将使用新值进行注释。更新仅适用于正在记录的用户交互。

id：必需。字符串值，限制为 80 个字符。这是类别名称与用户交互名称的组合。
value：必需。新的字符串值，限制为 50 个字符。
object：可选。如果指定，则用户交互与该对象相关联，因此可以同时进行多次记录。

如果由于某种原因无法进行更新，则返回 false 并将消息记录到浏览器控制台。

示例

// At this point, we don't know if the tab will open with animation
// or not.
UserInteraction.start("browser.tabs.opening", "initting", window);
// ...
if (animating) {
  UserInteraction.update("browser.tabs.opening", "animating", window);
} else {
  UserInteraction.update("browser.tabs.opening", "not-animating", window);
}

`cancel()`¶

UserInteraction.cancel(id, object);

取消正在记录的用户交互。在这种情况下不会添加分析器标记，并且不会注释其他挂起。但是，在用户交互取消之前发生的挂起不会被删除。

id：必需。字符串值，限制为 80 个字符。这是类别名称与用户交互名称的组合。
object：可选。如果指定，则用户交互与该对象相关联，因此可以同时进行多次记录。

如果由于某种原因无法完成取消，则返回 false 并将消息记录到浏览器控制台。

`running()`¶

UserInteraction.running(id, object);

检查用户交互是否已经在运行。

id：必需。字符串值，限制为 80 个字符。这是类别名称与用户交互名称的组合。
object：可选。如果指定，则用户交互与该对象相关联，因此可以同时进行多次记录。如果您正在检查使用对象启动的正在运行的计时器，则需要在此处传入相同的对象以检查其运行状态。

如果用户交互已经在运行，则返回 true。

`finish()`¶

UserInteraction.finish(id, object, additionalText);

完成用户交互的记录。在主线程上发生的任何挂起将不再使用此用户交互进行注释。还将添加一个分析器标记，从 UserInteraction.start 点开始，到 UserInteraction.finish 点结束，以及作者想要包含的任何其他文本。

id：必需。字符串值，限制为 80 个字符。这是类别名称与用户交互名称的组合。
object：可选。如果指定，则用户交互与该对象相关联，因此可以同时进行多次记录。
additionalText：可选。如果指定，则分析器标记将附加此文本到 value，并用逗号分隔。

如果由于某种原因无法完成完成，则返回 false 并将消息记录到浏览器控制台。

版本历史¶

Firefox 84：初始用户交互支持（请参见错误 1661304）。