浏览器交互 SDK

在应用程序客户端入口处初始化一次 。 SSR期间导入软件包是安全的;被禁用/SSR初始化返回一个惰性手柄.

import { initInteractions } from "@codepress/interactions-browser";

const interactions = initInteractions({
  projectKey: "public-project-key",
  endpoint: "https://interactions.example.com",
  allowedApiOrigins: [window.location.origin],
});

终点是服务基础 URL; SDK 发送协议 v2 批次给 /v2/batches 并快照身体到 /v2/snapshots/{sha256} (单位:千美元)计划) (中文(简体) ). 使用 sink 改为 endpoint 将证据送交其他任何地方(见 银色) (中文(简体) ). 公钥解决服务项目/环境. environment 是一个本地诊断配置标签, 从来不授予权限 。 服务源准入和租赁配置必须已经允许安装。 API的出处默认为此页面的出处. 仅在您的申请和许可控制下明确添加单独的 API 来源 X-Interaction-Id cORS的配置.

初始设置抓取会点击语义控件(包括动态挂载控件),格式提交,导航信号,被绑定的结构DOM变化,以及被允许的源取/XHR观测. 它不需要每个控制的说明。 使用控制标识符 data-interaction-id编号 :data-testid 传递到 测试ID过滤器,否则,一个 - 最多五倍的祖先暗示。 这种倒计时不独有,从不扫描兄弟会收藏. 这些标识符是结构提示,在布局变化时可以改变. 标记私有子树 data-interactions-exclude。不要将用户数据或秘密输入明确的跟踪识别符.

不记录 DOM 文本, HTML, 输入值, 请求/响应机构, URL 路径, 查询, 饼干或用户ID 。 变异证据报告改变了记录计数,而不是重放或断言自旋者代表业务完成. HTTP 状态被限制 data.phase 标签, 如 http_201; 浏览器请求结果为 completed编号 :error,从不服务器商业结果。 没有使用可持久浏览器存储 .

测试身份证和隐私

测试ID常由数据构建: row-${record.id}, (中文(简体) ), domain-row-${hostname}。录制后,它会把数据从页面上移出,每个记录的ID会将一个发现分成许多。 所以每个 data-interaction-id 财务报告和审定财务报表 data-testid 在任何地方使用之前先通过过滤器:快照 test_id 词典,单击 control_id, (中文(简体) ), control_id 关于UI事件,一个发现 stable_id 还有指纹.

默认过滤器, defaultTestIdFilter,只保留一个ID 当它看起来静止。 它降低了一个值:

• 包含一个 .,或
• 有一段( 断开 -, (中文(简体) ), _, (中文(简体) ), . 或者说 :)含有数字或超过32个字符.

丢弃的身份证被视为没有。 点击时使用标记路径,发现时使用从最近的祖先发出的结构路径并保留了ID. data-interaction-id 遵循同样的规则: data-testid。当它被丢弃时,元素的 data-testid 将尝试下一个.

过滤器无法识别每个值 。 短句的一首诗(project-acme-launch),名称(row-JaneDoe)或无位数的随机ID外观为静态并被保留,而有位数的静态ID(step2)被丢弃。 如果你的ID可以持有流星或名字,或者需要ID的默认滴出,只允许您知道的ID:

const STATIC_TEST_IDS = new Set(["save-button", "nav:settings", "step2"]);

initInteractions({
  sink,
  testId: (value) => (STATIC_TEST_IDS.has(value) ? value : null),
});

这个 testId 选项替换默认值。 它运行在默认的任何地方,带有属性的值和元素. 返回值,或静态替换,以保留它 null 放弃它:

import { defaultTestIdFilter, initInteractions } from "@codepress/interactions-browser";

initInteractions({
  sink,
  // Collapse per-record rows into one ID, and use the default for the rest.
  testId: (value) => (value.startsWith("order-row-") ? "order-row" : defaultTestIdFilter(value)),
});

钩子代替了默认而非添加,所以 testId: (value) => value 保留 item-42调用 defaultTestIdFilter(value) 从钩子上保护它。 结果仍必须是明确的标识([a-zA-Z][a-zA-Z0-9_.:-]*,最多128个字符)或被删除。 丢出或返回字符串以外的任何东西的钩子 null中,放下ID;继续抓取,没有任何记录。 钩子为每个元素运行,带有一个快照行走的ID,在点击和UI状态变化时,使其快速而无副作用. 传递一个稳定函数: 如 routeTemplate,在 initInteractions 被再次调用,而使用不同钩子的调用会得到一个不活跃的手柄.

关联

自动点击是单独的交互尝试. 自动请求和突变/导航观测的归属不明:SDK没有将它们附在最近发生的哪个点击上. 对于已知的因果工作,使用可选的明确行动:

await interactions.runAction("transfer.confirm", async (context) => {
  await context.fetch("/api/transfer", { method: "POST" });
  await someOtherWork();
  await context.fetch("/api/verify");
});

runAction 设置上下文,只在调用时同步引用。 同步部分的普通接取/ XHR 呼叫继承动作 。 之后 await,计时器或另一个调用器,使用已提供的 context.fetch 保存已知的链接。 在等待和独立投票后,普通无限制取票仍无关联。 这避免了全球同步环境在重叠行动之间泄露. 商业回召值、抛出的错误和被拒绝的承诺保持不变。 现有 X-Trace-Id 保存; 原始标题从未被记录。 摄取和未配置的第三方来源从来就没有仪器或寄出关联头.

寿命周期和界限

flush() 尝试一个不可改变的批次,返回时不会出现运输错误。 可重试的故障保留了准确的批次/活动ID和有效载荷. 默认:1000个队列事件,100个事件/批次,6万字节/批次,每5个冲出,请求超时10个,3个有1s指数基数的回放,每回调50个突变-观察工作单位. 使用覆盖 maxQueueEvents, (中文(简体) ), maxBatchEvents, (中文(简体) ), maxBatchBytes, (中文(简体) ), flushIntervalMs, (中文(简体) ), requestTimeoutMs, (中文(简体) ), maxRetries, (中文(简体) ), retryBaseMs, (中文(简体) ), maxMutationRecords。 。 。 . maxMutationRecords 保留其现有名称,但是一个共享的召回预算(最多1,000个):记录、祖先隐私检查,以及每个被检查的树下节点——包括被排除或非元素节点——控制单位。 它永远不会被重置为另一个记录或子树。 被排除在外的后人被跳过,疲惫状态停止检查;对于这个被截断的回调,取消了一次诊断递增,而没有要求精确地计算未见节点或事件。 这些是局部的。 过度流出和累累累累累累的累累累累累累累累累累累累累累累累累累累累累的累累累累累累累累累累累累累累累累累累累的累累累累累累累累累累累累累累累累累累累的累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累累 重试计时器由冲出间隔驱动 . getDiagnostics() 暴露本地接受/失败/投放的计数和出错;它不声称端到端安装健康.

页面出口试图 一小批保存。 交付是最好的努力,并且可能失败,特别是在上传已经激活或浏览器终止的情况下. 不在 URL 中设置秘密 。 HTTP 401/403停止捕捉并清除待取出的证据;重新连接需要在确定录取后明确重新启动.

重复相同的初始化通过参考计算租赁共享一个记录器。 每个老板都打电话 shutdown() 在它的手柄上; 最后一个所有者停止计时器/观测器, 中止 SDK 上传, 清除队列, 并且只恢复 SDK 仍然拥有的补丁 。 后来的第三方补丁被保留. 不同的并发项目配置返回一个惰性手柄:在切换账户/org之前关闭旧项目,所以待决事件永远不会被重新标记. 反应"严格模式"在完全清理后可能会启动新的记录器,这是安全的.

未覆盖:闭合阴影根,帧内容(帧为一不透明盒),一般承诺/计时器传播,持续下线回放,输入录制,截图,抽样完整性推论,或全局交叉批量回扣. 浏览器遥测是不信任的证据. Service v1需要不可改变的批次重试;事件ID从未被重新分配到另一批.

结构反馈包括出现或消失的进展/状况指标, aria-busy 转换和禁用控制。 省去数值和状态文本; 没有语义标记的 CSS 唯一的自旋器可能仍然是未知的结构变化. 已签名的URL被排除在请求的仪器之外. 已存在的交互头 保存; 有效的UUID用于关联性,否则属性未知.

路由模板

事件和快照带有路由模板,从不包含URL. 默认情况下, 每个路径段都被替换为 :id这样 /u/jane-smith 财务报告和审定财务报表 /acme-corp/projects 均作为 /:id/:id: 小写 sattle可以是用户名,组织或标题,所以除非应用程序如此表示,否则就永远不会保存. 列出您在 routeSegments (单位:千美元)/acme-corp/projects 与 routeSegments: ["projects"] 变成 /:id/projects),或通过 routeTemplate 以返回您的路由器自己的模式。 查询和散列从未使用 .

屏幕快照

每个已安放的屏幕都作为元素框记录在柱形体中(计划, (中文(简体) ), 实例: 父母,标签,角色,安全测试ID, x编号 :y编号 :width编号 :height (查看端口 CSS 像素来自 getBoundingClientRect),z-index,CSS 位置,旗帜(可见,可交互,可剪接,可滚动,可覆盖,被忽略,指针事件无,不透明,可剪接内容,以阴影根,打开弹出,椭圆或行夹,断开图像, aria-hidden 和文本长度。 "入影根"指元素自有树为"入影根";分档光-DOM内容不标出. 取景口记录主指针是否粗糙(touch)和屏幕上的主题(light, (中文(简体) ), dark 或者说 unknown: theme() 选项,否则 prefers-color-scheme编辑 ui.snapshot 事件带有相同的 theme,因此屏幕可以按路由,取景口和主题进行分组,而无需阅读机构. 对于有直接文字的元素,它也记录了已变换文字的框本身(来自 Range,仅指几何),所以一个元素框可以重叠某个东西,而其文本则没有。 对于可见的互动元素,它探测 elementFromPoint 在中心点和四个陷入点 并存储多少土地 在别的东西上, 和哪个元素在上. elementFromPoint 从不要求其他要素。 没有记录文字,值,属性值(除了角色和安全测试ID),URL或HTML.

当路由结算(包括第一个屏幕),点击结算后,调整大小结算后,以及标签再次被显示时,即刻取出快照. handle.snapshot() 需要一分钱 每个正体被散列(SHA-256)准确的未压缩字节;本页会话中已经发送的散列不再发送. 与 endpoint,身体由上传 HEAD 那么,仅仅在404年,一个gzip PUT 改为 /v2/snapshots/{sha256}。服务必须允许 HEAD编号 :PUT 编辑 Authorization 财务报告和审定财务报表 Content-Encoding 来源于您的信头 .

走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走行走走行走行走走行走行走行走行走走走行走行走行走行走行走走走行走走行走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走走 maxSliceMs 已经过去了,所以一个切片 超支最多一个批8。 它停止在 maxElements 并标记尸体 truncated; 体型大于 maxSnapshotBytes 滴入后行为 truncated。如果DOM、滚动位置或取景口在切片之间发生变化,则标出天体 torn. 开口的阴影根被穿透(其槽下有分层内容);闭口根是一盒. 相机、相机、相机和相机 opaque。 。 。 . display: none 次树被跳过。 浏览器不渲染的内容( 已关闭的正文) <details>, (中文(简体) ), content-visibility: hidden)被记录时没有明显的旗帜. 子树匹配 ignoreSelector, (中文(简体) ), [data-layout-ignore] 或者说 [data-interactions-exclude] 记录为一个标记的框 ignored 所以支票可以跳过 跟踪剪切检测 overflow 财务报告和审定财务报表 contain: paint;它并不模拟每个案例(例如绝对定位后人逃离了非定位剪接祖先).

单击后续

每次点击一个控件都会启动后续窗口. 当页面保持安静时结束(没有DOM更改,没有在飞行中观察到请求) clickSettleMs,并报告为一个 ui.click.settled 事件: 第一次可见反馈的时间( DOM 更改、 路由更改、 对话框或焦点移动)、 结算时间、 突变数、 请求、 失败请求、 未发现错误和长的任务、 排版移位分数、 路由改变、 对话框打开或焦点移动、 屏幕散列前后。 自0.3.0起,它也表示点击是否落在了控制上(target_interactive),修改了字段的值(value_changed,例如复选框),将焦点放入文本字段(field_focused; 在已聚焦的字段中, 注意是效果, 或打开新标签或窗口时, 每次点击都再次为真( namenew_context) (中文(简体) ). 自1.0起,它说明是点击自己的按键,还是点击打开时的页面,修改了文本选择,还是移动了护栏(selection_changed; 位置比较,选定的文本永远不会被读取。 焦点和选择只计为答案 rage_click;它们不是反馈 first_feedback_ms, (中文(简体) ), dead_click 或者说 slow_feedback。后一指针或密钥输入造成的焦点或反馈不贷记到更早的打开点击中。 内容 interaction_id 是点击的 interaction.started 身份证及其归属总是 inferred;窗口中观察到的请求会在那里被计算,从不作为清晰的附加在点击上. 第一次和解前的第二次点击 overlapped 两者都不计算在内 点击后仍然打开 clickTimeoutMs,或当页面被隐藏或卸下时,报告 incomplete自0.3.0起点击 interaction.started 还携带 target_key,单击元素的每个会话编号不透明(仅平等意味着任何东西),单击一个 <label> 记录一次,作为单击其字段控制(例如 <button role="checkbox"> 带有 <label for>),而不是当浏览器转发到字段时再次. 一个字段的控制是它上方最近的控制,或者它通过 form 属性。 已禁用字段的标签和标签内的链接都是自己的点击.

用户界面检查

@codepress/interactions-browser/detect 将快照和事件转化为发现。 检查是纯函数而不是数据:否 document,没有 window,在浏览器、节点和测试跑取器中得出同样的结果(剧作家助手) (中文(简体) ). 默认情况下, SDK 在每次新快照之后的空闲时间运行它们, 在每次确定点击后, 在每次冲出时, 发送每个发现作为 ui.finding 每页会话每个指纹一次事件(findings: false 关掉这个). SDK通过谨慎记起多达2000个发送的指纹:一个再次发现的指纹算作是最近才发现的,没有被发现的最长指纹被遗忘了,因此只有在此后才再次发送. 在当前运行中发现的指纹永远不会忘记腾出空间,所以一个不断产生相同发现的屏幕永远不会重新发送;如果运行中发现有超过2000个新的指纹,剩下的就等待后一运行. 从第一个快照还没有取景口之前点击查找,所以它等待给它一个快照(并用它来表示正确的宽幅带和指纹);它只是当页面消失或者会话没有取景时才发送.

发现是指针,不是判断:它命名元素并携带 evidence,仅计量事实(数字、布尔斯或 null 页:1 是否是bug是给读它的人的;检查不会通过自信过滤.

未报告的重叠或溢出: 对话框、 菜单、 列表框、 工具提示和打开的弹出符与下方的弹出符( 它们是单独的层, 如固定的全屏背景); 内容跨越滚动器的边缘( 滚动); 内容被粘度或固定元素所滚动( 一旦页被滚动; 在页源中报告包含内容的固定或粘度元素); 子树 data-layout-ignore; 1×1 px 或更少的元素。 A 类 torn 快照没有基于位置的发现; 缺少行 truncated 一个不给。 点击检查只使用窗口 settled: 点击其页面已导航、超时或被另一点击所重叠的 dead_click。 。 。 .

排序将屏蔽控件放在首位( 任何 *_blocked_points > 0),然后被覆盖或剪接文本,再将其余的,再进行装饰或空洞的发现. 在其余部分中,首先要发现涉及控制:一个小自带目标、一个外屏控制、一个点击查找、一个要素是控制时的重叠或溢出(*_interactive),或一对外对,在主体内阻断控制(subject_blocked_controls > 0,例如: main × widget(三); involvesControl(finding) 说哪一个。 然后通过检查,顺序找到。 它永远不会放弃一个发现。 当一个要素是装饰层时,发现是装饰性的或空的(*_decorative:没有文本,没有控制,以及 pointer-events: none 或者说 aria-hidden),其任何要素都没有文本或控制(*_has_content: false,例如堆放或被裁剪的图像),或重叠内容没有覆盖主体的内容(subject_content_covered: false) (中文(简体) ). findingTier(finding) 给出等级,0到3。 早期的阶地取胜:一个用被覆盖的文本覆盖文本类型的装饰层. 重叠证据也有 subject_text_covered_ratio,该主题的文本区域中覆盖的部分.

衡量的行为值得了解

这些报告按衡量标准报告。 每个发现都包含着说出它是什么的证据,因此读者可以不猜测地决定.

• 旁边的固定部件 <main> 报告于 <main>。 。 。 . 一个聊天按钮,即 position: fixed 和一个兄弟 <main>被报告为 main × chat没有 save × chat被嵌入的元素所重复的碰撞会倒塌到最外侧的一对上,而一对上方的证据涵盖了其中的一切. 覆盖的按钮仍然出现 : subject_blocked_points 财务报告和审定财务报表 subject_blocked_controls 数一下它被封锁的命中点, 所以首先发现的种类, 主体的 index 点数 <main>"行",其中快照按住按钮.
• 一个固定的页眉上加的 <main> 报告为空. 在页面来源, a position: fixed 标题 <main style="padding-top: 64px"> 交叉 <main>框,所以报告为 main × header它的证据说里面什么都没有: subject_blocked_points: 0, (中文(简体) ), subject_text_covered: false 财务报告和审定财务报表 subject_content_covered: false里面有装饰性的和空洞的发现 如果你的布局是怎样的,请接受 ignoreFingerprints 测试或放置 data-layout-ignore 在头部。 页面已滚动后,固定标题下的内容会滚动而未报告.
• 点击浏览器不转发的标签, 而改变什么, 是一个死点击 . 点击标签内容时,浏览器不会转发到字段(一个嵌入式按钮,一个链接,一个正文) <details>,一个 <img usemap> 带有空映射),或者在隐藏或已禁用字段的标签上,是自己的点击. 当什么都没有发生,它给 dead_click 标签上的控件(例如表格) target_interactive: true 因为标签是控件。 一个禁用字段的标签给出了相同的标签 .
• 加入到另一个窗体的字段属于该窗体. 与 form 属性,以及任何标签,都记录在它加入的表格上,无论它坐落在DOM中在哪里:一个标签点击就是一个 interaction.started 在那张表格上.

指纹是SHA-256的32个十六进制字符 在检查、路由模板、取景口宽带和元素上 stable_id,从不坐标、滚动偏移或文本。 在另一个卷轴偏移时, 在另一个会话中, 或者在另一个机器上, 同样的错误也是相同的 . stable_id 是测试的ID,或者,当没有或曾经 过滤出,从最近的祖先取出的结构标记路径并带有测试ID(#cart/div/button; 证据 subject_structural_id 编号 : structural_id 这么说的 结构路径在标记完成后会改变,拥有相同标记的兄弟姐妹共享一个.

import { checkEvents, checkSnapshot, formatFinding } from "@codepress/interactions-browser/detect";

const findings = [...checkSnapshot(body, { sha256 }), ...checkEvents(batch.events)];
findings.map(formatFinding);

性能信号

布局班次、事件时间安排(40 ms和较慢)、长任务、图像加载错误和未发现错误/未处理的拒绝被计算和发送 perf.summary 事件。 每个 API 被特性检测:浏览器不支持的信号是 null 列入 unavailable,从未报告为零。 不读取错误消息、堆栈、文件名和图像 URL.

银色

sink: { sendBatch, sendSnapshot } 替换 endpoint· ; projectKey 则不需要。 每种方法都可返回(或解析) "accepted" (默认), "retry", (中文(简体) ), "rejected" 或者说 "denied" (停止捕捉并清除待取证据,如HTTP 401/403). 扔出、拒绝或永不解决的沉槽不会影响页面:电话被隔离,超时 requestTimeoutMs 并按常理重审. createMemorySink() 将一切保存在内, 用于测试 :

import { createMemorySink, initInteractions } from "@codepress/interactions-browser";

const sink = createMemorySink();
const handle = initInteractions({ sink });
await handle.snapshot();
await handle.flush();
sink.batches; // protocol v2 batches
sink.snapshots; // { sha256, serialized, body }

发送到网络上的水槽 context 作为其最后的论点: keepalive (页面正在卸下;保持小并使用) fetch是因为 keepalive, (中文(简体) ), signal (在超时或当捕获停止时堕胎)和 fetch,页面的 fetch 没有SDK的包装。 使用 context.fetch 所以水槽本身的上传不记录为应用程序的要求,这也会使每个冲浪引起另一个. 请求在第一个汇开始之前开始 await 选择 fetch 或者说 XMLHttpRequest 它们被使用; 后一种被记录, 除非它们被使用 context.fetch。 。 。 . examples/react-vite 拥有一个通过 Vite Dev 服务器写入文件的槽.

const sink: InteractionSink = {
  async sendBatch(_batch, serialized, { keepalive, signal, fetch }) {
    const response = await fetch("/my-collector/batches", { method: "POST", body: serialized, keepalive, signal });
    return response.ok ? "accepted" : response.status >= 500 ? "retry" : "rejected";
  },
  async sendSnapshot({ sha256, serialized }, { signal, fetch }) {
    await fetch(`/my-collector/snapshots/${sha256}`, { method: "PUT", body: serialized, signal });
  },
};

选项

以上运输选项(maxQueueEvents, (中文(简体) ), flushIntervalMs,.)保持他们的v1默认值.