# @atlaskit/analytics-cross-product 中文文档

规范地址：https://npmcn.com/package/%40atlaskit/analytics-cross-product/

版本：2\.3\.1
npm 元数据更新时间：2026-10-22T03:50:24.387Z
中文译文更新时间：2026-11-07T03:05:00.921Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：186 kB，91 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：react ^18\.2\.0
- 首次发布：2026-05-11T09:02:48.273Z
- 最新版本发布：2026-10-22T03:50:24.187Z
- 近 30 天下载量：21770（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

能够进行跨产品互动会话跟踪的公用事业

## 安装

```sh
npm install @atlaskit/analytics-cross-product
```

也可以使用：`pnpm add @atlaskit/analytics-cross-product`、`yarn add @atlaskit/analytics-cross-product`、`bun add @atlaskit/analytics-cross-product`

## README

# 分析 交叉

能够进行跨产品互动会话跟踪的公用事业

这个寄存器是公众面对的版本 `@atlassiansox/analytics-cross-product-interaction-client`. 功能从 要启用的私有软件包 `@atlaskit` ,最终目标是 在现有软件包中去掉这些函数以避免代码重复.

该图书馆的功能旨在配合 `analytics-web-client` 财务报告和审定财务报表 `analytics-cross-product-interaction-client` ,并使用这些功能 他们自己不会回来的.

## 概览

Analytics Web客户端生成交互会话数据并存储在会话存储中. 这个 数据形状如下:

```Json
"interactionSession": {
    "id": "123456789",
    "prevId": "912345678",
    "bridge": "atlassianSwitcher",
    "source": "jira"
}
```

此套件曝光 : `useCrossProductUrlWrapper`,用于取回 交互会话数据并将其作为 URL 参数附加到交叉产品导航 URL

## 3份观察合同

该套件还暴露了用于观测交叉产品的独立运输构件 不添加或更改 XPIS 的导航 :

-   `xpcDestinationResolver` 提供可控产品、子产品、路由家庭和匹配值 加上四个结果的目的地分辨率: `same`, (中文(简体) ), `cross`, (中文(简体) ), `unknown` 财务报告和审定财务报表 `excluded`。 。 。 .
-   `xpcNavigationObservation` 检查 XPIS 的存在,建立新的、保护隐私的离开 和到达观察.
-   `xpcActivationCoordinator` 确保本地和拥有的最终沉积观察者完成一个用户 最多一次启动.
-   `xpcNativeDepartureCapture` 授权安装 `click` 财务报告和审定财务报表 `auxclick` 在产品所有者手中捕获 生成到被截获的渲染器下沉.
-   `xpcFinalSinkDepartureCapture` 带有可控捕获的 权威渲染器 和导航装置。 计划保留了以后的必由性和路由器值, 独立入门整合.
-   `xpcArrivalCapture` 检查本地到达的 URL, 只报告包含 XPIS 的目的地 证据; URL从不输入观察.
-   `xpcNavigationProvider` 制作一个产品源头的本地观察者,初始到达捕获,共享 活化协调与渲染器从产品所控制的配置中取出最终沉入钩.
-   `xpcAwcNavigationReporter` 是产品已有的Analytics Web客户端的候选边界. 它故意省略了互动段ID,直到其生产隐私处理 核准.

产品提供自己的受控登记册条目、来源身份、推出门和记者. 共享包不注册 GASv3 事件 。 产品适配器可使用特性标注 需要验证的候选人Analytics Web 客户端报告员, 但必须在事件之前一直禁用 计划、频道、隐私控制和所有权均获得批准。 候选人代码不能证明 活动注册或生产.

## Atlassian桥内的用途

一个桥是一个组件,提供连接/导航到不同的Atlassian页面,例如:

```TypeScript
return <Link href="https://hello.atlassian.net/wiki"> Confluence </Link>
```

要将交互会话属性作为 UTM 参数嵌入到链接中, 请调用我们的钩子 `useCrossProductUrlWrapper` 生成一个将链接围起来的函数.

然后用钩子所包裹的 URL 替换任何 URL 实例

```TypeScript
import { useCrossProductUrlWrapper }  from '@atlaskit/analytics-cross-product';

const withInteractionSession = useCrossProductUrlWrapper({
    bridge: 'Bridge Name', // The name of your bridge component e.g. atlassianSwitcher
    product: 'Product Name', // The product you are hosted on e.g. jira
    subProduct: 'SubProduct Name', // Optional - include if required
});

return (
    <Link href={withInteractionSession("https://hello.atlassian.net/wiki")}> Confluence </Link>
)
```

这个 `useCrossProductUrlWrapper` 钩子包含类型选项 `CrossProductUrlOptions` 这可能是 必要时从我们的图书馆导入

返回的包装器功能( E)`withInteractionSession` 以 URL 作为 字符串,并返回一个字符串。 上述呼吁的回报价值如下:

```
https://hello.atlassian.net/wiki?xpis=e2JyaWRnZToiQnJpZGdlIE5hbWUiLGlkOiIxMjM0NTY3ODkiLHNvdXJjZToiUHJvZHVjdCBOYW1lLVN1YlByb2R1Y3QgTmFtZSJ9
```

中编码的交互式会话数据 `?xpis` 查询参数(跨产品交互) 届会)

看我们的 [实例](https://npmcn.com/package/%40atlaskit/analytics-cross-product/examples/basic.tsx)。要在当地运行示例:

```bash
yarn start @atlaskit/analytics-cross-product
```

### 参数生成和再生成

交互会话数据只有在 URL 已经生成时才会被附加到 URL 分析网络客户端,存在于会话存储中. 如果找不到交互式会话数据,则 钩子不会修改 URL 。 钩子被订阅为 DOM 事件, 如果 生成新的 Interaciton 会话,并将动态更新 URL 以包含正确的 参数

### 相对 URL

包装器支持相对的URL,例如:

```TypeScript
withInteractionSession("/wiki")
```

将返回

```TypeScript
"/wiki?xpis=e2Jya..."
```

我们使用 `URL` 进行操作。 说明:

-   URL 不得有后端斜线( 即使用) `/wiki` 改为 `/wiki/`(中文(简体) )
-   返回输出中将增加一先行斜线(即:. `wiki` 将变成 `/wiki?xpis=...`(中文(简体) )
-   将保留现有的查询参数(`/wiki?a=b` 变成 `/wiki?a=b&xpis=e2Jya...`(中文(简体) )

### 使用身份证明

当链接被身份包裹时(通过为 `continue` 重新定向中的参数,身份 使用 % 编码(即. `&key=value` 变成 `%26key%3Dvalue`) (中文(简体) ).

确保我们的包装被调用到 `href` _在此之前_ 成为身份。 这将确保我们 查询参数也被正确编码为 %, 并在身份重定向后持续

## 常见问题

### @atlaskit/analytics-cross-product 是什么？

能够进行跨产品互动会话跟踪的公用事业

### 如何安装 @atlaskit/analytics-cross-product？

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

### @atlaskit/analytics-cross-product 支持 TypeScript 吗？

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

### @atlaskit/analytics-cross-product 支持 ESM 还是 CommonJS？

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

### @atlaskit/analytics-cross-product 可以商用吗？

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

### @atlaskit/analytics-cross-product 的下载量有多少？

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

### @atlaskit/analytics-cross-product 还在维护吗？

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