# @esri/telemetry 中文文档

规范地址：https://npmcn.com/package/%40esri/telemetry/

版本：9\.1\.2
npm 元数据更新时间：2026-10-22T16:20:31.202Z
中文译文更新时间：2026-11-13T22:47:39.144Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40esri/telemetry
原文对照：https://npmcn.com/package/%40esri/telemetry/?lang=original

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

- 包体积（解压后）：272 kB，52 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2017-04-27T20:28:26.633Z
- 最新版本发布：2026-10-22T16:20:30.945Z
- 近 30 天下载量：13279（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：91（近 12 个月 1 个）

## 中文简介

AJavaScript 执行 ArcGIS 遥测规格

## 安装

```sh
npm install @esri/telemetry
```

也可以使用：`pnpm add @esri/telemetry`、`yarn add @esri/telemetry`、`bun add @esri/telemetry`

## README

# `@esri/telemetry`

> 这是ArcGIS-Teleometry.js的"核心"包. 有必要向谷歌,Adobe,AWS等分析平台发送数据.

## 目录

-   [`@esri/telemetry`](https://npmcn.com/package/%40esri/telemetry/#readme-esritelemetry)
    -   [目录](https://npmcn.com/package/%40esri/telemetry/#readme-table-of-contents)
    -   [安装](https://npmcn.com/package/%40esri/telemetry/#readme-installation)
    -   [使用量](https://npmcn.com/package/%40esri/telemetry/#readme-usage)
    -   [问题](https://npmcn.com/package/%40esri/telemetry/#readme-issues)
    -   [捐款](https://npmcn.com/package/%40esri/telemetry/#readme-contributing)
    -   [许可证](https://npmcn.com/package/%40esri/telemetry/#readme-license)

## 安装

```sh
npm install @esri/telemetry
```

## 使用量

## 术语

-   `Telemetry`:用于使用信号的供应商不可知收集和路由接口.
-   `Plugin`: 文档和表格中使用的外向整合术语 `plugins` 配置阵列 .
-   `Tracker`:核心运行时间所使用的内部代码级演员/界面.
-   `Analytics`:下游目的地/报告系统(如AWS,Google,Adobe,Siteimprove等).

## 隐私追踪

从7.x版本开始, `telemetry.js` 支持隐私追踪同意。 主机应用程序可以决定允许此行为通过 `.requireConsent` 以及可选选项 `IPrivacySettings` 对象。 下面的例子表明了这一结构.

用户可以同意以下类型的"跟踪": 1

-   性能: 只允许发送和存储应用程序性能信息
-   功能: 允许存储功能信息, 如透视、 过去搜索等
-   目标:允许用户发送目标信息

何时 `requireConsent` 被通过,没有 `userPrivacySettings` 发送, `telemetry.js` 操作时似乎用户选择了退出所有跟踪。 根据GDPR,这是预期的行为.

何时 `userPrivacySettings.performance: true`,并配置了 Amazon 插件,将初始化.

对于Hub Sites(和一些其他的平台应用),客户可以配置额外的第3方跟踪系统(Google Analytics,Adobe,SiteImprove). 为使这些跟踪器启用,最终用户必须选择使用 `performance`, (中文(简体) ), `functional` 财务报告和审定财务报表 `targeting`因为我们不知道 或控制 3 党跟踪者在做什么, 所以我们必须假设 他们 跟踪所有 三个.

### 在浏览器中

```js
import { Telemetry } from '@esri/telemetry';

// create options object
const opts = {
  requireConsent: true, // if your app requires privacy consent, set this to true
  plugins: [list of vendor plugins goes in here]
};
// Host app should load user privacy settings from localStorage or cookies
const storedSettings = window.localStorage.getItem('esri_privacy_settings');
if (storedSettings) {
  opts.userPrivacySettings = JSON.parse(storedSettings);
} else {
  // this is optional, as telemetry.js will construct the same thing
  // if requiteConsent: true and not settings are passed in
  opts.userPrivacySettings = {
    id: '3ef...', // create some unique id
    timestamp: Date.now(),
    accepted: false, // user has not actually set these, so this is false
    performance: false, // all set to false by default
    functional: false,
    targeting: false,
  }
}
// create the telemetry instance
const telemetry = new Telemetry(opts);

await telemetry.init();
// now it is ready to go
```

### 在服务器中

由于这是在服务器上完成的,因此无法考虑用户隐私设置. 因此,在服务器上注入脚本标记是劝阻的,因为跟踪很可能在主机应用程序实际靴子之前开始,并且可以应用用户隐私设置.

```js
import { Telemetry } from '@esri/telemetry';

// create options object
const opts = {
  plugins: [list of vendor plugins goes in here]
};
// create the telemetry instance
const telemetry = new Telemetry(opts);
// in server
const scriptTags = telemetry.getScriptTags();
// now inject script tags into html page before sending it down

```

## 问题

如果有什么不起作用,请看一看 [以往问题](https://devtopia.esri.com/WebGIS/arcgis-telemetry.js/issues) 先说 你找到新窃听器了吗? 创建问题 [这里](https://devtopia.esri.com/WebGIS/arcgis-telemetry.js/issues/new)。 。 。 .

## 捐款

Esri欢迎所有人的贡献。 请看我们的 [提交文件的准则](https://npmcn.com/package/CONTRIBUTING.md)。 。 。 .

## 许可证

版权: 2022 Esri

根据Apache许可证第2.0版("License"); 您不得使用此文件,除非符合许可证. 您可在下列地点获得许可证副本:

> [http://www.apache.org/licenses/LICENSE-2.0 (中文(简体) )](http://www.apache.org/licenses/LICENSE-2.0)

除非适用的法律要求或书面同意,否则软件 根据许可证发放的是在“AS IS”BASIS上发放的, 没有任何明示或暗示的警告或条件. 有关许可的特定语言的许可证 许可证的限制.

许可证副本可到存放处索取 [自由主义](https://npmcn.com/package/LICENSE) 文档.

## 常见问题

### @esri/telemetry 是什么？

AJavaScript 执行 ArcGIS 遥测规格

### 如何安装 @esri/telemetry？

在项目目录运行 npm install @esri/telemetry，或使用 pnpm add / yarn add / bun add。

### @esri/telemetry 支持 TypeScript 吗？

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

### @esri/telemetry 支持 ESM 还是 CommonJS？

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

### @esri/telemetry 可以商用吗？

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

### @esri/telemetry 的下载量有多少？

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

### @esri/telemetry 还在维护吗？

最新版本 9\.1\.2 发布于 2026/10/23（22 天前）；至今共发布 91 个版本，其中过去 12 个月发布了 1 个；首次发布于 2017/04/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。