# @atlaskit/insm 中文文档

规范地址：https://npmcn.com/package/%40atlaskit/insm/

版本：3\.0\.98
npm 元数据更新时间：2026-11-07T01:22:37.751Z
中文译文更新时间：2026-11-07T02:53:43.423Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40atlaskit/insm
原文对照：https://npmcn.com/package/%40atlaskit/insm/?lang=original
项目主页：https://bitbucket.org/atlassian/atlassian-frontend-monorepo#readme
源码仓库：https://bitbucket.org/atlassian/atlassian-frontend-monorepo

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：183 kB，38 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- peer 依赖：react ^18\.2\.0 \|\| ^19\.2\.0
- 首次发布：2025-08-13T08:55:14.204Z
- 最新版本发布：2026-11-07T01:22:37.575Z
- 近 30 天下载量：29653（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：258（近 12 个月 250 个）

## 中文简介

INSM 工具化措施

## 安装

```sh
npm install @atlaskit/insm
```

也可以使用：`pnpm add @atlaskit/insm`、`yarn add @atlaskit/insm`、`bun add @atlaskit/insm`

## README

# insm——互动会话测量

一个轻量级,基于会话的方法,用来衡量你的经验对用户的交互感受. 内 总结用户花在页面或特定视图上的交互质量,并发出 当会话结束时,单个分析事件.

## 何为内涵措施

-   会议期间用户活动期间的互动质量
-   活动时间(当用户互动时)和整个会话时间
-   排除明确标记的繁重/预期工作
-   单一会话补全活动,包含汇总统计和可选自定义属性

## 常见的内相测量任务

### 装入"重活"

已知造成相互作用回归的繁重任务可明确选择退出 通过明确标出重活期进行互动测量.

谨慎使用——最好是减少繁重工作的费用,而不是选择不进行计量。 作为将军 根据规则,只有初始化和非核心行动才应标出重度.

"重活"时期的例子有:

-   页面初始化
    -   当第一次加载一页时——经常会触发大量的工作来收集、安排和 向用户显示页面内容
-   粘贴处理
    -   用于编辑页面粘贴处理器 — 粘贴处理器目前已知在计算中 昂贵(对于大型剪贴板项目,可以锁定UI数秒). 鉴于这是非 核心经验——将这一点排除在互动性监测之外,确保我们掌握关于 核心经验.

```ts
insm.session.startHeavyTask('paste-handler');
// ... perform paste work ...
insm.session.endHeavyTask('paste-handler');
```

注意: 用于跟踪页面初始化 - 如果您使用特殊 `PageLoad` 键,持续时间为 跟踪了由此产生的会议活动.

### 向会议提供补充资料

额外会话信息可通过 `setProperty` 或 `addProperties` api. (英语).

#### 财产

```ts
insm.session.setProperty(key: string, value: string | number | boolean): void
```

这个 api 是添加Properties 的选项, 用于您有热路径的情景 整个会议都会不断开火.

将使用给定密钥的最后一个值,如果从添加Properties中找到匹配的密钥,则 添加属性值.

#### 添加属性

```ts
type ValidProperty = string | number | boolean;
insm.session.addProperties(
  propsOrFactory: Record<string, ValidProperty> | (() => Record<string, ValidProperty>)
): void
```

此 api 需要静态的单级密钥值对象, 或者调回返回相同和 将在会场结束时进行评估.

结束会话时,通过此 api 接收的所有属性将被合并, 顺序为由此生成的 insm 事件属性; 最后写入获胜 .

在会话结束时评价回调值 .

举例来说

```ts
insm.session.addProperties({ one: 1, two: 2 });
insm.session.addProperties(() => ({ one: 'one' }));
insm.session.addProperties({ three: 3 });
```

由此产生的新增属性为

```ts
{ one: 'one', two: 2, three: 3 }
```

### 获取当前 insm 会话细节

```ts
insm.session.details;
```

这可以用来根据个人经验进行闸门改变.

没错.

```ts
if (insm.session.details.experienceKey === 'cc.edit-page' && gateCheck()) {
    insm.session.addProperties(() => ({
        /*potentially large or computationally large property bag */
    }));
}
```

### 使用特性时标记

```ts
insm.session.startFeature(featureName: string): void
insm.session.endFeature(featureName: string): void
```

```ts
useEffect(() => {
    insm.session.startFeature('comment notification');
    return () => {
        insm.session.endFeature('comment notification');
    };
}, []);
```

导致的内幕事件;

-   长相动画框上会发现任何活性特征
-   最慢的会话将具有当前会话中使用的任何特性 他们

## 如何测量仪器内光度

### 先决条件

您的产品必须安装 Insm 库 —— insm 具有与 UFO 工具相同的先决条件 [https://developer.atlassian.com/plateform/ufo/react-ufo/react-ufo/getting-started/#prequisites 互联网档案馆的存檔,存档日期2014-12-21](https://developer.atlassian.com/platform/ufo/react-ufo/react-ufo/getting-started/#prerequisites)。 。 。 .

### 安装

```sh
yarn add @atlaskit/insm
```

### 初始化

要启动仪表, 可通过引用功能和通过配置对象进行隐藏 根据仪器要求确定.

```ts
import { init } from '@atlaskit/insm';

export function initialiseINSM(config) {
    /* logic to get/initialise your app's analytics client */
    init(config);
}
```

在应用程序中尽早挂载时间表(理想情况下,在应用程序挂载之前), 通过 Evolution 函数将 Insm 客户端关闭.

**重要**: 隐含将只追踪明确允许的交互活动——这些经验 必须在 `config` 通过了.

```ts
{
    getAnalyticsWebClient,
    experiences: {
        ['experience key']: {enabled: true}
    }
}
```

如果缺少或未启用一个经验密钥, 将不会发布会话事件 .

### 开始页面会话

在路由更改/ 启动时, 请调用 insm start api .

```ts
insm.start(experienceKey, {
    contentId,
    initial,
});
```

注:称此将结束任何现有经验(除非经验关键和属性) 匹配 - 在这种情况下不会发生会话变化.

#### 启动后更新页面会话体验Key

在一些情景中,您可能需要更新运行的会话体验键,在它开始后, 在这种情况下,你可以使用 `overrideExperienceKey`。 。 。 .

如果有运行经验,它将更新运行经验名.

如果没有运行经验(即如果原始体验Key没有被白列),它 将使用上次开始的经验开始新的体验 Properties.

```ts
insm.overrideExperienceKey('new-key');
```

#### 命名指导

选择一个 `experienceKey` 反映您想要分析的产品和内容类型.

实例: `cc.view-page`, (中文(简体) ), `cc.edit-page`, (中文(简体) ), `cc.live-doc`

### 停止页面会话的互动跟踪

结束一个页面会话交互跟踪由其中之一完成;

-   开始一个新的会话.
-   或当标签会话结束时(如关闭标签,刷新页面)

在一些假想中(即当一个页面错误边界被击中时),您会想要提前退出。 这是 实现方式如下.

```ts
insm.stopEarly(reasonKey: string, description: string);
```

提前关闭的会话可按其结束细节识别 `"endDetails": { stoppedBy: "early-stop", reasonKey, description }`。 。 。 .

**说明**: 一旦停止,会话即告结束 `addProperties` 处理者会 此时此刻.

### 跟踪大门进入

在会话中评价或更改一个门时拨打闸机.

```ts
insm.gateAccess('gate key', 'gate rule');
```

这应该连接到任何您产品使用的大门访问库/工具.

## 常见问题

### @atlaskit/insm 是什么？

INSM 工具化措施

### 如何安装 @atlaskit/insm？

在项目目录运行 npm install @atlaskit/insm，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.2\.0 \|\| ^19\.2\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @atlaskit/insm 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @atlaskit/insm 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @atlaskit/insm 可以商用吗？

@atlaskit/insm 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @atlaskit/insm 的下载量有多少？

根据 npm 官方下载统计，@atlaskit/insm 在 2026/10/07 – 2026/11/05 这 30 天内被下载 29,653 次，日均约 988 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @atlaskit/insm 还在维护吗？

最新版本 3\.0\.98 发布于 2026/11/07（今天）；至今共发布 258 个版本，其中过去 12 个月发布了 250 个；首次发布于 2025/08/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。