# @capawesome/capacitor-age-signals 中文文档

规范地址：https://npmcn.com/package/%40capawesome/capacitor-age-signals/

版本：0\.5\.1
npm 元数据更新时间：2026-09-02T08:21:32.106Z
中文译文更新时间：2026-11-09T05:02:17.301Z
软件包许可：Apache-2\.0

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

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

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

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

## 中文简介

通过Android上的"Play Age Signals API"和iOS上的"已宣布年龄范围"框架为用户检索与年龄相关的信号的Capacitor插件.

## 安装

```sh
npm install @capawesome/capacitor-age-signals
```

也可以使用：`pnpm add @capawesome/capacitor-age-signals`、`yarn add @capawesome/capacitor-age-signals`、`bun add @capawesome/capacitor-age-signals`

## README

# 电容时代信号插件

使用该电容的插件 [播放时代信号 API](https://developer.android.com/google/play/age-signals/overview) (机器人)和 [已宣布为 年龄范围](https://developer.apple.com/documentation/declaredagerange/) (iOS)请求用户的年龄信号.

[![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 Age Signals插件是Capacitor App最完整的年龄保证解决方案之一. 以下是一些关键特征:

-   🖥️ **跨平台**: 支持Android和iOS.
-   🔍 **年龄核查**:使用Play Age Signals API(Android)和"宣布"(iOS)请求用户年龄信号.
-   👨‍👩‍👧‍👦 **家长控制**支持具有父母批准地位的受监督账户.
-   🧪 **测试支持**: 内建 `FakeAgeSignalsManager` 用于测试不同年龄验证情景的整合(Android).
-   🌍 **准备就绪**: 为美国国家年龄核查要求所建(2026年1月1日生效).
-   🤝 **兼容性**: 与 [App 完整性](https://capawesome.io/docs/sdks/capacitor/app-integrity/) 财务报告和审定财务报表 [根检测](https://capawesome.io/docs/sdks/capacitor/root-detection/) 插件 .
-   📦 **可可花和SPM**:支持CocoaPods和Swift软件包管理器用于iOS.
-   🔁 **最新数据**:总是支持最新的Capacitor版本.

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

## 使用大小写

Age Signals插件通常用于遵守年龄验证要求,并针对用户的年龄调整应用体验,例如:

-   **按年龄划分的内容**: 根据用户的验证状态和年龄范围,限制获取成熟或敏感内容.
-   **监管遵守情况**:通过从Google Play和苹果的"宣布年龄"API中请求年龄信号来达到美国州年龄验证要求.
-   **父母监督**: 检测有监督的账户,并对有待或被拒绝的家长批准作出反应.
-   **区域资格检查**: 使用 `getRegulatoryRequirements()` 在iOS上确定用户是否在一个区域有额外的与年龄有关的义务.
-   **自动化测试**: 使用内置的假管理器在您的安卓测试中模拟不同的年龄验证方案.

## 兼容性

| 插件版本 | 电容版本 | 状态 |
| --- | --- | --- |
| 0.3.x (单位:千美元) | \>=8.x.x | 积极支持 |
| 0.2.x (中文(简体) ) | 7.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-age-signals` plugin in my project.
```

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

```bash
npm install @capawesome/capacitor-age-signals
npx cap sync
```

### 机器人

#### 变量

如果需要, 您可以在您的应用程序中定义以下工程变量 `variables.gradle` 要更改依赖的默认版本的文件 :

-   `$androidPlayAgeSignalsVersion` 版本 `com.google.android.play:age-signals` (默认 : `0.0.4`(中文(简体) )

如果您在工程中遇到其它插件的依赖性冲突, 这会有所帮助 .

**说明**编号: `FakeAgeSignalsManager` 测试 API 包含在主 `age-signals` 因此测试不需要额外的依赖.

### iOS系统

#### 应享权利

要使用已宣布的年龄 API, 您必须启用 `com.apple.developer.declared-age-range` 在应用程序的应享权利文件中添加以下密钥:

```xml
<key>com.apple.developer.declared-age-range</key>
<true/>
```

看看这个 [苹果文档](https://developer.apple.com/documentation/bundleresources/entitlements/com.apple.developer.contacts.notes) 更多信息.

## 配置

此插件不需要配置 .

## 使用量

以下例子说明了如何要求用户的年龄范围以及如何对适用于用户的监管要求作出反应.

### 请求用户的年龄范围

打电话 `requestAgeRange(...)` 请用户分享他们的年龄范围。 状态说明年龄范围是否相同 `ageRange` 属性包含边框 :

```typescript
import { AgeRangeStatus, AgeSignals } from '@capawesome/capacitor-age-signals';

const requestAgeRange = async () => {
  const result = await AgeSignals.requestAgeRange();
  if (result.status !== AgeRangeStatus.Shared) {
    console.log('The user has not shared their age range:', result.status);
    return;
  }
  console.log('Lower Bound:', result.ageRange?.lowerBound);
  console.log('Upper Bound:', result.ageRange?.upperBound);
};
```

在Android上,状态为 `VERIFICATION_REQUIRED` 表示用户必须在Google Play Store中解决其状态后才能共享一个年龄范围.

### 在不提示的情况下读取年龄范围

打电话 `getAgeRange()` 在不显示提示的情况下再次读取年龄范围。 这对民意调查很有用 `significantChange` 从 `PENDING` 改为 `APPROVED`。仅在Android上提供:

```typescript
import { AgeSignals } from '@capawesome/capacitor-age-signals';

const getAgeRange = async () => {
  const result = await AgeSignals.getAgeRange();
  console.log('Significant Change:', result.significantChange?.status);
};
```

### 检查监管要求

检查用户是否处于需要年龄保证的区域和账户状态,以及您的应用程序必须支持哪些监管功能. 仅在iOS上可用 :

```typescript
import {
  AgeSignals,
  RegulatoryFeature,
} from '@capawesome/capacitor-age-signals';

const getRegulatoryRequirements = async () => {
  const result = await AgeSignals.getRegulatoryRequirements();
  if (
    result.regulatoryFeatures.includes(
      RegulatoryFeature.SignificantAppChangeRequiresAdultNotification,
    )
  ) {
    await AgeSignals.showSignificantUpdateAcknowledgment({
      updateDescription: 'This app now supports direct messages between users.',
    });
  }
};
```

## API 密码

-   [`getAgeRange()`](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-getagerange)
-   [`getRegulatoryRequirements()`](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-getregulatoryrequirements)
-   [`isAvailable()`](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-isavailable)
-   [`requestAgeRange(...)`](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-requestagerange)
-   [`setNextAgeSignalsAccessResult(...)`](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-setnextagesignalsaccessresult)
-   [`setNextAgeSignalsException(...)`](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-setnextagesignalsexception)
-   [`setNextAgeSignalsResult(...)`](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-setnextagesignalsresult)
-   [`setNextRequestAgeSignalsAccessException(...)`](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-setnextrequestagesignalsaccessexception)
-   [`setUseFakeManager(...)`](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-setusefakemanager)
-   [`showSignificantUpdateAcknowledgment(...)`](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-showsignificantupdateacknowledgment)
-   [接口](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-interfaces)
-   [数字](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-enums)

### 获取年龄范围 ()

```typescript
getAgeRange() => Promise<GetAgeRangeResult>
```

获取用户已经与应用程序共享的年龄范围 .

这种方法从未显示系统提示 。 打电话 `requestAgeRange(...)` 第一个 如果返回状态为 `SHARED`。 。 。 .

使用这种方法对变化进行投票(例如: `significantChange` 从 `PENDING` 改为 `APPROVED`)而不提示用户 再来一次.

只能从Android上找到.

**回返情况:** `Promise<[GetAgeRangeResult](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-getagerangeresult)>`

**自:** 0.5.0 (单位:千美元)

* * *

### 获取监管要求( )

```typescript
getRegulatoryRequirements() => Promise<GetRegulatoryRequirementsResult>
```

获取适用于当前用户的监管要求.

在开始任何年龄保证流程前拨打此方法以查找 用户是否处于一个地区和账户状态,其年龄保障 完全适用.

仅在iOS上提供(26.2+).

**回返情况:** `Promise<[GetRegulatoryRequirementsResult](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-getregulatoryrequirementsresult)>`

**自:** 0.5.0 (单位:千美元)

* * *

### 易读 ()

```typescript
isAvailable() => Promise<IsAvailableResult>
```

检查此设备是否有年龄信号 .

打开 **机器人**,此检查是否安装了 Google Play Store . 打开 **iOS系统**,此选项检查该设备是运行iOS 26.0还是运行后.

结果是 `true` 并不保证可以检索一个年龄范围. 总是处理其他方法的错误.

**回返情况:** `Promise<[IsAvailableResult](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-isavailableresult)>`

**自:** 0.5.0 (单位:千美元)

* * *

### 请求AgeRange(...)

```typescript
requestAgeRange(options?: RequestAgeRangeOptions | undefined) => Promise<RequestAgeRangeResult>
```

请用户与应用程序共享他们的年龄范围 .

这种方法可能显示系统提示 。 系统缓存 用户,所以后续的调用可能无需任何用户交互即可解决.

打开 **机器人**,该提示只显示给未受监督的用户 选择在共享前被询问。 年龄地区没有显示 核查是强制性的。 在这种情况下,情况是: `VERIFICATION_REQUIRED` 用户必须解决其在 谷歌游戏商店. Google Play 还压制了用户之后的提示 曾几次驳回或拒绝. 打开 **iOS系统**,在年龄保障的区域没有显示提示 强制。 在这种情况下,年龄范围在没有用户互动的情况下共享.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[RequestAgeRangeOptions](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-requestagerangeoptions)` |

**回返情况:** `Promise<[RequestAgeRangeResult](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-requestagerangeresult)>`

**自:** 0.5.0 (单位:千美元)

* * *

### 设置NextAgeSignals AccessResult(...)

```typescript
setNextAgeSignalsAccessResult(options: SetNextAgeSignalsAccessResultOptions) => Promise<void>
```

设定由假管理器返回的下一个访问结果 .

只能从Android上找到.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[SetNextAgeSignalsAccessResultOptions](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-setnextagesignalsaccessresultoptions)` |

**自:** 0.5.0 (单位:千美元)

* * *

### 设置近代符号例外(...)

```typescript
setNextAgeSignalsException(options: SetNextAgeSignalsExceptionOptions) => Promise<void>
```

当年龄范围是时, 设置由假管理器丢出的下一个错误 读取.

只能从Android上找到.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[SetNextAgeSignalsExceptionOptions](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-setnextagesignalsexceptionoptions)` |

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

* * *

### 设置 NextAgeSignals Result (...)

```typescript
setNextAgeSignalsResult(options: SetNextAgeSignalsResultOptions) => Promise<void>
```

设定由假管理器返回的下一个年龄范围结果 .

只能从Android上找到.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[SetNextAgeSignalsResultOptions](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-setnextagesignalsresultoptions)` |

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

* * *

### 设置下一个请求年龄符号访问例外(...)

```typescript
setNextRequestAgeSignalsAccessException(options: SetNextRequestAgeSignalsAccessExceptionOptions) => Promise<void>
```

设定访问年龄时由假管理器丢出下一个错误 区域请求.

只能从Android上找到.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[SetNextRequestAgeSignalsAccessExceptionOptions](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-setnextrequestagesignalsaccessexceptionoptions)` |

**自:** 0.5.0 (单位:千美元)

* * *

### 设置使用假管理器(...)

```typescript
setUseFakeManager(options: SetUseFakeManagerOptions) => Promise<void>
```

启用或禁用假管理器进行测试 .

假管理器只在可调试的架构中可用 。 在发行中建造 此方法拒绝使用 `FAKE_MANAGER_NOT_ALLOWED`因为它会 否则可以让年龄信号从网络层被伪造出来.

只能从Android上找到.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[SetUseFakeManagerOptions](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-setusefakemanageroptions)` |

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

* * *

### 显示显著的更新日期

```typescript
showSignificantUpdateAcknowledgment(options: ShowSignificantUpdateAcknowledgmentOptions) => Promise<void>
```

显示系统接口, 让用户识别一个显著 更改为应用程序 .

仅在下列情况下调用此方法: `getRegulatoryRequirements()` 已返回 `SIGNIFICANT_APP_CHANGE_REQUIRES_ADULT_NOTIFICATION`。 。 。 .

仅在iOS上提供(26.4+).

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[ShowSignificantUpdateAcknowledgmentOptions](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-showsignificantupdateacknowledgmentoptions)` |

**自:** 0.5.0 (单位:千美元)

* * *

### 接口

#### 获取年龄分布结果

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`ageRange`** | `[AgeRange](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-agerange)` | 用户与应用程序共享的年龄范围. `undefined` 如果用户没有分享他们的年龄范围. | 0.5.0 (单位:千美元) |
| **`installId`** | `string` | 由Google Play指定给受监督用户安装的ID,用于通知您被撤销的应用批准. 只能从Android上找到. | 0.5.0 (单位:千美元) |
| **`significantChange`** | `[SignificantChange](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-significantchange)` | 该应用的重大变更的家长批准状态. 在Google Play Console中宣布了重大变化. Google Play随后要求被监管用户的家长或监护人批准. `undefined` 如果用户没有受到监督,如果尚未宣布有重大变化,或者在用户的管辖范围内没有适用重大变化。 只能从Android上找到. | 0.5.0 (单位:千美元) |

#### 年龄范围

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`activeParentalControls`** | `ParentalControl[]` | 对用户有效的父控件 。 仅在iOS上可用. | 0.5.0 (单位:千美元) |
| **`ageRangeDeclaration`** | `[AgeRangeDeclaration](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-agerangedeclaration)` | 年龄范围是如何申报的。 颗粒值越多,只在一些地区才会返回. `undefined` 如果系统不提供这种信息。 仅在iOS上可用. | 0.5.0 (单位:千美元) |
| **`ageRangeSource`** | `[AgeRangeSource](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-agerangesource)` | 年龄范围是如何确定的. `undefined` 如果系统不提供这种信息。 只能从Android上找到. | 0.5.0 (单位:千美元) |
| **`lowerBound`** | `number` | 年龄范围(包括)下限. `undefined` 如果用户低于请求的最低年龄门. | 0.5.0 (单位:千美元) |
| **`upperBound`** | `number` | 年龄范围(包括)的上限. `undefined` 如果用户满足或超过要求的最高年龄门. | 0.5.0 (单位:千美元) |

#### 重大变化

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`approvalDate`** | `string` | 最近批准的ISO 8601格式的重大变化的生效日期。 所有重大变更,如生效日期较早,也都得到核准. `undefined` 如果尚未核准重大改动. | 0.5.0 (单位:千美元) |
| **`status`** | `[SignificantChangeStatus](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-significantchangestatus)` | 父母对最近重大变化的认可情况. | 0.5.0 (单位:千美元) |

#### 获取监管要求

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`ageAssuranceRequired`** | `boolean` | 用户是否因为适用于其区域和账户的法律或条例而必须分享其年龄范围. | 0.5.0 (单位:千美元) |
| **`regulatoryFeatures`** | `RegulatoryFeature[]` | 应用程序必须支持这个用户的监管特征. 26.4以下的iOS版本空出. | 0.5.0 (单位:千美元) |

#### 易伤性结果

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`available`** | `boolean` | 此设备是否有年龄信号 . | 0.5.0 (单位:千美元) |

#### 请求年龄范围

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`ageRange`** | `[AgeRange](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-agerange)` | 用户与应用程序共享的年龄范围. `undefined` 如果状态不是 `SHARED`。 。 。 . | 0.5.0 (单位:千美元) |
| **`installId`** | `string` | 由Google Play指定给受监督用户安装的ID,用于通知您被撤销的应用批准. 只能从Android上找到. | 0.5.0 (单位:千美元) |
| **`significantChange`** | `[SignificantChange](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-significantchange)` | 该应用的重大变更的家长批准状态. 在Google Play Console中宣布了重大变化. Google Play随后要求被监管用户的家长或监护人批准. `undefined` 如果用户没有受到监督,如果尚未宣布有重大变化,或者在用户的管辖范围内没有适用重大变化。 只能从Android上找到. | 0.5.0 (单位:千美元) |
| **`status`** | `[AgeRangeStatus](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-agerangestatus)` | 用户是否与应用程序共享其年龄范围 . | 0.5.0 (单位:千美元) |

#### 请求年龄范围选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`ageGates`** | `number[]` | 与应用相关的年龄阈值. 提供的阵列必须包含至少1个和最多3个年龄. 年龄必须按照递增顺序排序,必须相隔至少两年. 如果法律或条例要求,该系统可能忽略这些阈值,返回不同的年龄范围。 仅在iOS上可用. | `[13, 15, 18]` | 0.5.0 (单位:千美元) |

#### 设置最近年龄符号访问结果选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`status`** | `[AgeRangeStatus](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-agerangestatus)` | 假经理要返回的状态 . | 0.5.0 (单位:千美元) |

#### 设定最近的年龄符号例外选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`errorCode`** | `[ErrorCode](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-errorcode)` | 假管理器要抛出的错误代码 。 只支持Android上可用的错误代码. | 0.3.1 (中文(简体) ) |

#### 设置最近的年龄符号结果选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`ageLower`** | `number` | 年龄范围(包括)下限. | 0.3.1 (中文(简体) ) |
| **`ageRangeSource`** | `[AgeRangeSource](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-agerangesource)` | 年龄范围是如何确定的. | 0.5.0 (单位:千美元) |
| **`ageUpper`** | `number` | 年龄范围(包括)的上限. | 0.3.1 (中文(简体) ) |
| **`installId`** | `string` | 由Google Play指定给受监督用户安装的ID. | 0.3.1 (中文(简体) ) |
| **`significantChangeApprovalDate`** | `string` | 最近批准的ISO 8601格式的重大变化的生效日期. | 0.5.0 (单位:千美元) |
| **`significantChangeStatus`** | `[SignificantChangeStatus](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-significantchangestatus)` | 父母对最近重大变化的认可情况. | 0.5.0 (单位:千美元) |

#### 设定下一个请求年龄符号访问例外选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`errorCode`** | `[ErrorCode](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-errorcode)` | 假管理器要抛出的错误代码 。 只支持Android上可用的错误代码. | 0.5.0 (单位:千美元) |

#### 设置使用假管理选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`useFake`** | `boolean` | 是否使用假管理器进行测试 . | `false` | 0.3.1 (中文(简体) ) |

#### 显示显著更新日期

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`updateDescription`** | `string` | 简单描述应用程序中的变化以及用户为何必须承认. | 0.5.0 (单位:千美元) |

### 数字

#### 家长控制

| 成员 | 数值 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`CommunicationLimits`** | `'COMMUNICATION_LIMITS'` | 该系统限制了用户的通信功能. | 0.5.0 (单位:千美元) |

#### 年龄范围宣言

| 成员 | 数值 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`CheckedByOtherMethod`** | `'CHECKED_BY_OTHER_METHOD'` | 用户使用未说明的方法设定自己的年龄范围. 仅在iOS上提供(26.2+). | 0.5.0 (单位:千美元) |
| **`Confirmed`** | `'CONFIRMED'` | 年龄范围是采用严格审查的方法确定的,如信用卡或政府身份证。 仅提供于iOS (26.5+). | 0.4.0 (中文(简体) ) |
| **`GovernmentIdChecked`** | `'GOVERNMENT_ID_CHECKED'` | 用户使用政府身份证设定自己的年龄范围. 仅在iOS上提供(26.2+). | 0.5.0 (单位:千美元) |
| **`GuardianCheckedByOtherMethod`** | `'GUARDIAN_CHECKED_BY_OTHER_METHOD'` | 父母或监护人使用未说明的方法确定年龄范围。 仅在iOS上提供(26.2+). | 0.5.0 (单位:千美元) |
| **`GuardianDeclared`** | `'GUARDIAN_DECLARED'` | 父母或监护人在没有外部核实的情况下宣布年龄范围. | 0.4.0 (中文(简体) ) |
| **`GuardianGovernmentIdChecked`** | `'GUARDIAN_GOVERNMENT_ID_CHECKED'` | 父母或监护人使用政府身份证确定年龄范围。 仅在iOS上提供(26.2+). | 0.5.0 (单位:千美元) |
| **`GuardianPaymentChecked`** | `'GUARDIAN_PAYMENT_CHECKED'` | 父母或监护人使用支付方法确定年龄范围,如信用卡。 仅在iOS上提供(26.2+). | 0.5.0 (单位:千美元) |
| **`PaymentChecked`** | `'PAYMENT_CHECKED'` | 用户使用支付方式设定自己的年龄范围,如信用卡. 仅在iOS上提供(26.2+). | 0.5.0 (单位:千美元) |
| **`SelfDeclared`** | `'SELF_DECLARED'` | 用户在没有外部核实的情况下宣布了自己的年龄范围. | 0.4.0 (中文(简体) ) |

#### 年龄距离来源

| 成员 | 数值 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`TierA`** | `'TIER_A'` | 使用者自相宣说其年. | 0.5.0 (单位:千美元) |
| **`TierB`** | `'TIER_B'` | 用户的年龄由父母或监护人管理. | 0.5.0 (单位:千美元) |
| **`TierC`** | `'TIER_C'` | 使用信用卡、电子邮件地址、自评、政府身份证或税务身份证评估用户年龄. | 0.5.0 (单位:千美元) |
| **`TierD`** | `'TIER_D'` | 使用政府身份证和自评相结合,或使用数字身份证检查用户的年龄. | 0.5.0 (单位:千美元) |

#### 重大变化状况

| 成员 | 数值 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`Approved`** | `'APPROVED'` | 父母或监护人已经批准了最近的重大变更和所有先前的重大变更. | 0.5.0 (单位:千美元) |
| **`Declined`** | `'DECLINED'` | 父母或监护人拒绝了一个或多个重大变化. | 0.5.0 (单位:千美元) |
| **`Pending`** | `'PENDING'` | 父母或监护人尚未批准一项或多项重大修改. | 0.5.0 (单位:千美元) |

#### 规范特性

| 成员 | 数值 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`DeclaredAgeRangeRequired`** | `'DECLARED_AGE_RANGE_REQUIRED'` | 用户必须与应用程序共享他们的年龄范围. | 0.5.0 (单位:千美元) |
| **`SignificantAppChangeRequiresAdultNotification`** | `'SIGNIFICANT_APP_CHANGE_REQUIRES_ADULT_NOTIFICATION'` | 成人用户必须承认应用程序发生了重大变化。 使用 `showSignificantUpdateAcknowledgment(...)` 以显示系统接口,用于确认. | 0.5.0 (单位:千美元) |
| **`SignificantAppChangeRequiresParentalConsent`** | `'SIGNIFICANT_APP_CHANGE_REQUIRES_PARENTAL_CONSENT'` | 父母或监护人必须同意该应用程序的重大变更。 此插件不执行同意流 。 使用 Apple 权限Kit 框架请求同意 . | 0.5.0 (单位:千美元) |

#### 年龄范围状况

| 成员 | 数值 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`NotShared`** | `'NOT_SHARED'` | 用户尚未与应用程序共享他们的年龄范围. | 0.5.0 (单位:千美元) |
| **`Shared`** | `'SHARED'` | 用户与应用程序共享他们的年龄范围. | 0.5.0 (单位:千美元) |
| **`Unspecified`** | `'UNSPECIFIED'` | 该系统没有具体说明用户是否共享其年龄范围。 处理此值如 `NOT_SHARED`。Google Play 返回时不记录。 只能从Android上找到. | 0.5.0 (单位:千美元) |
| **`VerificationRequired`** | `'VERIFICATION_REQUIRED'` | 用户必须在Google Play Store中验证其年龄,然后才能共享年龄范围. 只能从Android上找到. | 0.5.0 (单位:千美元) |

#### 错误代码

| 成员 | 数值 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`ApiNotAvailable`** | `'API_NOT_AVAILABLE'` | 年龄信号 API 不可用 。 打开 **机器人**,安装在设备上的 Play Store app版本可能已经过时了. 打开 **iOS系统**,系统无法共享年龄范围. | 0.0.1 资源 |
| **`AppNotOwned`** | `'APP_NOT_OWNED'` | 该应用程序不是由Google Play安装的. 只能从Android上找到. | 0.0.1 资源 |
| **`CannotBindToService`** | `'CANNOT_BIND_TO_SERVICE'` | 装入 Play Store 的服务失败 。 这可能是因为设备上安装了旧的Play Store版本,或者设备内存超载. 只能从Android上找到. | 0.0.1 资源 |
| **`ClientTransientError`** | `'CLIENT_TRANSIENT_ERROR'` | 客户端设备发生瞬间出错. 只能从Android上找到. | 0.0.1 资源 |
| **`FakeManagerNotAllowed`** | `'FAKE_MANAGER_NOT_ALLOWED'` | 假管理器不可用,因为应用程序无法调试. 只能从Android上找到. | 0.5.0 (单位:千美元) |
| **`FakeManagerNotEnabled`** | `'FAKE_MANAGER_NOT_ENABLED'` | 假管理器未启用 。 只能从Android上找到. | 0.5.0 (单位:千美元) |
| **`InternalError`** | `'INTERNAL_ERROR'` | 未知的内部错误 。 只能从Android上找到. | 0.0.1 资源 |
| **`InvalidRequest`** | `'INVALID_REQUEST'` | 请求包含无效参数 。 打开 **iOS系统**,如果请求的时代门被系统拒绝,此选项也将返回. | 0.5.0 (单位:千美元) |
| **`NetworkError`** | `'NETWORK_ERROR'` | 找不到可用的网络 。 只能从Android上找到. | 0.0.1 资源 |
| **`NotSupported`** | `'NOT_SUPPORTED'` | 此设备不支持年龄信号 . | 0.5.0 (单位:千美元) |
| **`PlayServicesNotFound`** | `'PLAY_SERVICES_NOT_FOUND'` | Play Services不可用或版本太老. 只能从Android上找到. | 0.0.1 资源 |
| **`PlayServicesVersionOutdated`** | `'PLAY_SERVICES_VERSION_OUTDATED'` | 游戏服务需要更新. 只能从Android上找到. | 0.0.1 资源 |
| **`PlayStoreNotFound`** | `'PLAY_STORE_NOT_FOUND'` | 在设备上找不到 Play Store 应用程序 。 只能从Android上找到. | 0.0.1 资源 |
| **`PlayStoreVersionOutdated`** | `'PLAY_STORE_VERSION_OUTDATED'` | Play Store 应用程序需要更新 。 只能从Android上找到. | 0.0.1 资源 |
| **`PresentationContextUnavailable`** | `'PRESENTATION_CONTEXT_UNAVAILABLE'` | 没有找到显示系统接口的视图控制器 。 仅在iOS上可用. | 0.5.0 (单位:千美元) |
| **`SdkVersionOutdated`** | `'SDK_VERSION_OUTDATED'` | "时代信号"SDK版本已过时. 只能从Android上找到. | 0.4.0 (中文(简体) ) |

## 测试

插件包括支持 `FakeAgeSignalsManager` 在Android上的API,它允许您在测试中模拟不同的年龄信号情景,而不需要Google Play的现场响应.

### Android 测试

**重要**: 假管理器只有在您的应用程序可以调试时才可用 。 释放过程中, `setUseFakeManager(...)` 拒绝方式 `FAKE_MANAGER_NOT_ALLOWED`因为它会让年龄信号从网络层被铸造出来.

**重要**: 由于时代信号API的0.0.1和0.0.2版本中已知的一出,您可能会遇到一个 `java.lang.VerifyError` 当调用构建方法时 `AgeSignalsResult` 在单位测试。 作为一个工作,运行你的测试 作为Android仪器测试 `androidTest` 源设置.

#### 示例:测试自声明的成人用户

```typescript
import {
  AgeRangeSource,
  AgeRangeStatus,
  AgeSignals,
} from '@capawesome/capacitor-age-signals';

// Enable the fake manager
await AgeSignals.setUseFakeManager({ useFake: true });

// The user agrees to share their age range
await AgeSignals.setNextAgeSignalsAccessResult({
  status: AgeRangeStatus.Shared,
});

// Set up an adult user
await AgeSignals.setNextAgeSignalsResult({
  ageLower: 18,
  ageRangeSource: AgeRangeSource.TierA,
});

const result = await AgeSignals.requestAgeRange();
console.log(result.status); // 'SHARED'
console.log(result.ageRange?.lowerBound); // 18
```

#### 示例:测试一个监督用户(13至17岁)

```typescript
import {
  AgeRangeSource,
  AgeRangeStatus,
  AgeSignals,
} from '@capawesome/capacitor-age-signals';

await AgeSignals.setUseFakeManager({ useFake: true });

await AgeSignals.setNextAgeSignalsAccessResult({
  status: AgeRangeStatus.Shared,
});

await AgeSignals.setNextAgeSignalsResult({
  ageLower: 13,
  ageUpper: 17,
  ageRangeSource: AgeRangeSource.TierB,
  installId: 'fake_install_id',
});

const result = await AgeSignals.requestAgeRange();
console.log(result.ageRange?.lowerBound); // 13
console.log(result.ageRange?.upperBound); // 17
console.log(result.installId); // 'fake_install_id'
```

#### 示例:测试父母批准方案

```typescript
import {
  AgeRangeSource,
  AgeRangeStatus,
  AgeSignals,
  SignificantChangeStatus,
} from '@capawesome/capacitor-age-signals';

await AgeSignals.setUseFakeManager({ useFake: true });

await AgeSignals.setNextAgeSignalsAccessResult({
  status: AgeRangeStatus.Shared,
});

// Test pending approval
await AgeSignals.setNextAgeSignalsResult({
  ageLower: 13,
  ageUpper: 17,
  ageRangeSource: AgeRangeSource.TierB,
  significantChangeApprovalDate: '2026-02-01T00:00:00.000Z',
  significantChangeStatus: SignificantChangeStatus.Pending,
});

const result = await AgeSignals.requestAgeRange();
console.log(result.significantChange?.status); // 'PENDING'
console.log(result.significantChange?.approvalDate); // '2026-02-01T00:00:00.000Z'
```

#### 示例:测试必须验证其年龄的用户

```typescript
import { AgeRangeStatus, AgeSignals } from '@capawesome/capacitor-age-signals';

await AgeSignals.setUseFakeManager({ useFake: true });

await AgeSignals.setNextAgeSignalsAccessResult({
  status: AgeRangeStatus.VerificationRequired,
});

const result = await AgeSignals.requestAgeRange();
console.log(result.status); // 'VERIFICATION_REQUIRED'
console.log(result.ageRange); // undefined
```

#### 示例:测试出错情景

```typescript
import { AgeSignals, ErrorCode } from '@capawesome/capacitor-age-signals';

await AgeSignals.setUseFakeManager({ useFake: true });

// Simulate a network error while access is requested
await AgeSignals.setNextRequestAgeSignalsAccessException({
  errorCode: ErrorCode.NetworkError,
});

try {
  await AgeSignals.requestAgeRange();
} catch (error) {
  console.log('Caught network error:', error);
}

// Simulate a network error while the age range is read
await AgeSignals.setNextAgeSignalsException({
  errorCode: ErrorCode.NetworkError,
});

try {
  await AgeSignals.getAgeRange();
} catch (error) {
  console.log('Caught network error:', error);
}
```

#### 禁用假管理器

```typescript
import { AgeSignals } from '@capawesome/capacitor-age-signals';

// Switch back to the production manager
await AgeSignals.setUseFakeManager({ useFake: false });

// This will now use the real Age Signals API
const result = await AgeSignals.requestAgeRange();
```

## 财务问题

### 此插件使用哪个年龄验证 API ?

在Android上,插件使用 [播放时代信号 API](https://developer.android.com/google/play/age-signals/overview) 从 Google Play 请求年龄信号。 在iOS上,它使用苹果公司的 [已宣布为 年龄范围](https://developer.apple.com/documentation/declaredagerange/) 框架,其中要求 `com.apple.developer.declared-age-range` 应享权利(见 [安装](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-installation)) (中文(简体) ).

### 不同的状态是什么意思?

这个 `status` 属性告诉用户是否共享他们的年龄范围. `SHARED` 表示有年龄范围, `NOT_SHARED` 表示用户拒绝或不在一个适用区域,以及 `VERIFICATION_REQUIRED` (Android只)指用户必须先解决其在Google Play Store的地位.

### Android年龄范围来源如何映射到iOS年龄范围声明??

Android)报告一个年龄被确定为分级,而iOS则报告一种宣布方法. 它们不绘制一到一的映射图,因此两个值都作为单独的属性被曝光. 下表列出最接近的等同物:

| 机器人 | iOS系统 |
| --- | --- |
| `TIER_A` | `SELF_DECLARED` |
| `TIER_B` | `GUARDIAN_DECLARED` |
| `TIER_C` | `PAYMENT_CHECKED`, (中文(简体) ), `CHECKED_BY_OTHER_METHOD`, (中文(简体) ), `GUARDIAN_PAYMENT_CHECKED`, (中文(简体) ), `GUARDIAN_CHECKED_BY_OTHER_METHOD` |
| `TIER_D` | `GOVERNMENT_ID_CHECKED`, (中文(简体) ), `GUARDIAN_GOVERNMENT_ID_CHECKED` |

在iOS 26.5 及以后,颗粒性较强的申报可能被替换为: `CONFIRMED`,涵盖两个 `TIER_C` 财务报告和审定财务报表 `TIER_D`。 。 。 .

### 我如何测试不同年龄的核实情况?

在Android上,插件集成了 `FakeAgeSignalsManager` API,它让你模拟年龄信号,而不用Google Play的活回音. 启用它 `setUseFakeManager(...)` 并设定下一个结果或例外 `setNextAgeSignalsAccessResult(...)`, (中文(简体) ), `setNextAgeSignalsResult(...)`, (中文(简体) ), `setNextRequestAgeSignalsAccessException(...)` 财务报告和审定财务报表 `setNextAgeSignalsException(...)`。假管理器只有在您的应用程序可以调试时才可用 。 见 [测试](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-testing) 一节,用于完整示例.

### 为什么我在Android单位的测试中 得到验证错误?

由于"时代信号API"0.0.1和0.0.2版本中已知的一出,称为"构建者"方法 `AgeSignalsResult` 单位测试中可投出 `java.lang.VerifyError`作为工作,将你的测试作为Android仪器测试 `androidTest` 源设置.

### 为什么插件以 API NOT AVAILALED 或 APP NOT OWNED 等错误拒绝 ?

Play Age Signals API 需要设备上最新的 Play Store 应用程序和 Play 服务,所以错误如 `API_NOT_AVAILABLE`, (中文(简体) ), `PLAY_STORE_VERSION_OUTDATED`,或 `PLAY_SERVICES_NOT_FOUND` 通常表示已过时或缺失的Google Play组件. 这个 `APP_NOT_OWNED` 错误指该应用程序不是由Google Play安装的. 检查 `ErrorCode` 语句 [API 密码](https://npmcn.com/package/%40capawesome/capacitor-age-signals/#readme-api) 一节,用于完整错误代码列表.

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

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

## 相关插件

-   [App 完整性](https://capawesome.io/docs/sdks/capacitor/app-integrity/): 使用 Play Guide API 和 App Attest 验证应用及设备完整性.
-   [App 跟踪透明度](https://capawesome.io/docs/sdks/capacitor/app-tracking-transparency/):通过Apple的App跟踪透明框架请求用户授权.
-   [根检测](https://capawesome.io/docs/sdks/capacitor/root-detection/): 检测出有根有根和断裂的装置.

## 通讯

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

## 更改日志

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

## 许可证

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

## 常见问题

### @capawesome/capacitor-age-signals 是什么？

通过Android上的"Play Age Signals API"和iOS上的"已宣布年龄范围"框架为用户检索与年龄相关的信号的Capacitor插件\.

### 如何安装 @capawesome/capacitor-age-signals？

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

### @capawesome/capacitor-age-signals 支持 TypeScript 吗？

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

### @capawesome/capacitor-age-signals 支持 ESM 还是 CommonJS？

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

### @capawesome/capacitor-age-signals 可以商用吗？

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

### @capawesome/capacitor-age-signals 的下载量有多少？

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

### @capawesome/capacitor-age-signals 还在维护吗？

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