# @capawesome/capacitor-app-tracking-transparency 中文文档

规范地址：https://npmcn.com/package/%40capawesome/capacitor-app-tracking-transparency/

版本：0\.1\.2
npm 元数据更新时间：2026-09-02T08:21:50.093Z
中文译文更新时间：2026-11-09T06:05:26.223Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40capawesome/capacitor-app-tracking-transparency
原文对照：https://npmcn.com/package/%40capawesome/capacitor-app-tracking-transparency/?lang=original
项目主页：https://capawesome.io/docs/sdks/capacitor/app-tracking-transparency/
源码仓库：https://github.com/capawesome-team/capacitor-plugins

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

- 包体积（解压后）：46.9 kB，31 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2026-07-07T06:20:25.767Z
- 最新版本发布：2026-09-02T08:21:49.750Z
- 近 30 天下载量：5151（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

IOS上的App跟踪透明框架的电容插件.

## 安装

```sh
npm install @capawesome/capacitor-app-tracking-transparency
```

也可以使用：`pnpm add @capawesome/capacitor-app-tracking-transparency`、`yarn add @capawesome/capacitor-app-tracking-transparency`、`bun add @capawesome/capacitor-app-tracking-transparency`

## README

# CAP 跟踪透明插件

电容插件 [App 跟踪透明度](https://developer.apple.com/documentation/apptrackingtransparency) 框架.

[![Deliver Live Updates to your Capacitor app with Capawesome Cloud](https://cloud.capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.png?t=1)](https://cloud.capawesome.io/)

## 特征

Capacitor App跟踪透明插件是Capacitor App最完整的跟踪授权解决方案之一. 以下是一些关键特征:

-   🔒 **授权状态**: 读取当前跟踪授权状态.
-   🙋 **许可请求**: 呈现系统跟踪授权的快取.
-   🆔 **广告标识符**: 授权时读取广告标识符(IDFA).
-   🤝 **兼容性**: 与 [权限](https://capawesome.io/docs/sdks/capacitor/permissions/) 插件 .
-   📦 **可可花和SPM**:支持CocoaPods和Swift软件包管理器用于iOS.
-   🔁 **最新数据**:总是支持最新的Capacitor版本.

缺少一个功能? 刚刚 [打开一个问题](https://github.com/capawesome-team/capacitor-plugins/issues) 我们看看!

## 使用大小写

App跟踪透明插件通常在iOS应用程序为跟踪目的收集数据时使用,例如:

-   **个性化广告**:在向用户提供个性化广告前请求跟踪许可.
-   **指定归属**: 读取广告标识符(IDFA),在用户授权跟踪后,将应用安装归为广告活动.
-   **有条件跟踪**:检查当前跟踪授权状态,仅在状态时启用跟踪相关功能 `authorized`。 。 。 .
-   **App 审查遵守情况**:按照苹果公司对任何跟踪用户的应用程序的要求,呈现系统跟踪授权的提示.

## 兼容性

| 插件版本 | 电容版本 | 状态 |
| --- | --- | --- |
| 0.x.x (中文(简体) ) | \>=8.x.x | 积极支持 |

## 安装

你可以用我们的 **AI 辅助设置** 以安装插件. 添加数据 [超级技能](https://github.com/capawesome-team/skills) 至您的 AI 工具,使用以下命令:

```bash
npx skills add capawesome-team/skills --skill capacitor-plugins
```

然后使用下列提示:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-app-tracking-transparency` plugin in my project.
```

如果你喜欢 **手动设置**,通过运行以下命令来安装插件,并遵循下面的平台特定指令:

```bash
npm install @capawesome/capacitor-app-tracking-transparency
npx cap sync
```

此插件仅可用于 **iOS系统**。在Android和Web上,所有方法都否认未执行.

### iOS系统

#### 隐私描述

这个 `NSUserTrackingUsageDescription` 键必须添加到 `Info.plist` 您的应用程序文件 。 否则 `requestPermission(...)` 方法会以错误拒绝.

```xml
<key>NSUserTrackingUsageDescription</key>
<string>Your data will be used to deliver personalized ads to you.</string>
```

目的字符串必须明确解释您的应用程序为什么请求权限来跟踪用户 。 见 [苹果文档](https://developer.apple.com/documentation/bundleresources/information-property-list/nsusertrackingusagedescription) 更多信息.

## 配置

此插件不需要配置 .

## 使用量

以下例子显示如何检查跟踪授权状态,请求跟踪许可,并读取广告标识符.

### 检查跟踪授权状态

读取当前跟踪授权状态,例如决定是否应该启用跟踪相关功能. 仅在iOS上可用 :

```typescript
import { AppTrackingTransparency } from '@capawesome/capacitor-app-tracking-transparency';

const getStatus = async () => {
  const { status } = await AppTrackingTransparency.getStatus();
  return status;
};
```

### 请求跟踪权限

立即提出系统跟踪授权 提示仅在每次安装时显示, 而状态是 `notDetermined`;之后,该方法与现有状态相适应。 仅在iOS上可用 :

```typescript
import { AppTrackingTransparency } from '@capawesome/capacitor-app-tracking-transparency';

const requestPermission = async () => {
  const { status } = await AppTrackingTransparency.requestPermission();
  return status;
};
```

### 读取广告标识符

读取设备的广告标识符(IDFA). 只有当跟踪授权状态是 `authorized`否则, `null` 已返回。 仅在iOS上可用 :

```typescript
import { AppTrackingTransparency } from '@capawesome/capacitor-app-tracking-transparency';

const getAdvertisingIdentifier = async () => {
  const { advertisingIdentifier } =
    await AppTrackingTransparency.getAdvertisingIdentifier();
  return advertisingIdentifier;
};
```

## API 密码

-   [`getAdvertisingIdentifier()`](https://npmcn.com/package/%40capawesome/capacitor-app-tracking-transparency/#readme-getadvertisingidentifier)
-   [`getStatus()`](https://npmcn.com/package/%40capawesome/capacitor-app-tracking-transparency/#readme-getstatus)
-   [`requestPermission()`](https://npmcn.com/package/%40capawesome/capacitor-app-tracking-transparency/#readme-requestpermission)
-   [接口](https://npmcn.com/package/%40capawesome/capacitor-app-tracking-transparency/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capawesome/capacitor-app-tracking-transparency/#readme-type-aliases)

### 获取广告标识符( )

```typescript
getAdvertisingIdentifier() => Promise<GetAdvertisingIdentifierResult>
```

获取设备的广告标识符(IDFA).

广告标识符只有在跟踪授权时才可用 状态为 `authorized`否则, `null` 已返回.

**说明**: iOS 模拟器总是返回 `null`,即使跟踪 授权状态是 `authorized`。使用真正的设备测试这种方法.

仅在iOS上可用.

**回返情况:** `Promise<[GetAdvertisingIdentifierResult](https://npmcn.com/package/%40capawesome/capacitor-app-tracking-transparency/#readme-getadvertisingidentifierresult)>`

**自:** 0.1.0 (中文(简体) )

* * *

### 获取状态( C)

```typescript
getStatus() => Promise<GetStatusResult>
```

获取当前跟踪授权状态 .

仅在iOS上可用.

**回返情况:** `Promise<[GetStatusResult](https://npmcn.com/package/%40capawesome/capacitor-app-tracking-transparency/#readme-getstatusresult)>`

**自:** 0.1.0 (中文(简体) )

* * *

### 请求( )

```typescript
requestPermission() => Promise<RequestPermissionResult>
```

请求权限以跟踪用户 .

这将显示系统跟踪授权如果状态 尚未确定。 提示只显示每个安装一次 .

这个 `NSUserTrackingUsageDescription` 键必须添加到 `Info.plist` 您的应用程序文件 .

仅在iOS上可用.

**回返情况:** `Promise<[RequestPermissionResult](https://npmcn.com/package/%40capawesome/capacitor-app-tracking-transparency/#readme-requestpermissionresult)>`

**自:** 0.1.0 (中文(简体) )

* * *

### 接口

#### 获取广告 标识符

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`advertisingIdentifier`** | `string | null` | 设备的广告标识符(IDFA). 回返 `null` 如果跟踪授权状态不是 `authorized` 或者如果没有广告标识符,iOS模拟器上总是这样. | 0.1.0 (中文(简体) ) |

#### 获取状态

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`status`** | `[TrackingStatus](https://npmcn.com/package/%40capawesome/capacitor-app-tracking-transparency/#readme-trackingstatus)` | 目前追踪授权状态. | 0.1.0 (中文(简体) ) |

#### 请求豁免

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`status`** | `[TrackingStatus](https://npmcn.com/package/%40capawesome/capacitor-app-tracking-transparency/#readme-trackingstatus)` | 请求后的追踪授权状态. | 0.1.0 (中文(简体) ) |

### 类型异名

#### 跟踪现状

追踪授权状态.

-   `authorized`:用户授权访问应用相关数据进行跟踪.
-   `denied`:用户拒绝访问应用相关数据进行跟踪.
-   `notDetermined`:用户尚未收到跟踪授权请求.
-   `restricted`:跟踪授权受到限制,用户不能更改.

`'authorized' | 'denied' | 'notDetermined' | 'restricted'`

## 应用审查指南

苹果公司要求任何跟踪用户通过App跟踪透明框架请求许可的应用程序. 注意以下准则以避免App审查拒绝:

-   **及时**: 调用 `requestPermission(...)` 只有在用户处于跟踪有道理的背景中。 系统提示仅在每次安装时显示一次, 而状态是 `notDetermined`。然后再次调用该方法解决了现有状况,但没有显示及时性.
-   **目的字符串**编号: `NSUserTrackingUsageDescription` 目的字符串必须准确描述所收集的数据是如何使用的。 含糊或误导性的说法是拒绝的常见理由.
-   **广告标识符**: 广告标识符(IDFA)仅在状态时可用 `authorized`在所有其他情况下, `getAdvertisingIdentifier(...)` 返回时 `null`。 。 。 .
-   **模拟器**:iOS模拟器从未提供广告标识符,所以 `getAdvertisingIdentifier(...)` 总是返回 `null` 那里,即使状态是 `authorized`。使用真实的设备测试广告标识符.

## 财务问题

### 此插件与其他类似插件有何不同?

它将Apple的App跟踪透明框架包成一个小而完全打入的API:读取当前授权状态,呈现系统即时,并在用户授权跟踪后读取广告标识符(IDFA). 它还将App Review指南的焦点放在了即时计时,目的字符串,和模拟行为上——这些细节最常决定一个可追踪的应用是否被批准. 它支持CocoaPods和Swift软件包管理器,并被积极维持在最新的Capacitor版本上.

### 这个插件在Android或Web上工作吗?

不,App跟踪透明框架是一个只使用iOS的概念. 该插件只在iOS上可用;在Android和Web上,所有方法都拒绝作为未执行.

### 为什么请求允许方法会错误地拒绝?

最常见的原因是失踪了 `NSUserTrackingUsageDescription` 应用程序中的密钥 `Info.plist` 文档。 这个密钥是系统跟踪授权即时需要的,其目的字符串必须明确解释为什么您的应用程序请求权限来跟踪用户. 见 [安装](https://npmcn.com/package/%40capawesome/capacitor-app-tracking-transparency/#readme-installation) 详细情况.

### 为什么没有显示追踪授权?

系统提示只在每次安装时显示, 而跟踪授权状态为 `notDetermined`。如果用户已经回复了提示,请拨打 `requestPermission()` 重新解决当前状况,而不显示提示。 为了再次测试提示,重新安装应用程序.

### 为什么让“广告识别器”返回无效?

广告标识符(IDFA)只有在跟踪授权状态下才能使用 `authorized`在所有其他情况下, `null` 已返回。 此外,iOS模拟器从未提供广告标识符,即使状态是 `authorized`,因此使用一个真正的设备来测试这种方法.

### 我能用这个插件吗? 有Ionic、React、Vue或Angular?

是的,插件是框架不可知的。 它在任意网络框架的Capacitor app中工作,包括有Angular,React,或Vue的Ionic,以及平版JavaScript等项目.

## 相关插件

-   [权限](https://capawesome.io/docs/sdks/capacitor/permissions/):以统一的API检查并请求设备权限.
-   [隐私屏幕](https://capawesome.io/docs/sdks/capacitor/privacy-screen/):在应用切换器中隐藏敏感的应用内容并屏蔽截图.

## 通讯

随时更新有关卡帕韦索姆、Capacitor和Ionic生态系统的最新消息和最新消息,因为我们 [《卡帕索克通讯》](https://cloud.capawesome.io/newsletter/)。 。 。 .

## 更改日志

见 [变动情况](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/app-tracking-transparency/CHANGELOG.md)。 。 。 .

## 许可证

见 [自由主义](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/app-tracking-transparency/LICENSE)。 。 。 .

## 常见问题

### @capawesome/capacitor-app-tracking-transparency 是什么？

IOS上的App跟踪透明框架的电容插件\.

### 如何安装 @capawesome/capacitor-app-tracking-transparency？

在项目目录运行 npm install @capawesome/capacitor-app-tracking-transparency，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@capacitor/core（\>=8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @capawesome/capacitor-app-tracking-transparency 支持 TypeScript 吗？

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

### @capawesome/capacitor-app-tracking-transparency 支持 ESM 还是 CommonJS？

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

### @capawesome/capacitor-app-tracking-transparency 可以商用吗？

@capawesome/capacitor-app-tracking-transparency 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @capawesome/capacitor-app-tracking-transparency 的下载量有多少？

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

### @capawesome/capacitor-app-tracking-transparency 还在维护吗？

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