# @capgo/capacitor-device-integrity 中文文档

规范地址：https://npmcn.com/package/%40capgo/capacitor-device-integrity/

版本：8\.0\.15
npm 元数据更新时间：2026-10-15T05:00:14.724Z
中文译文更新时间：2026-11-09T03:58:47.172Z
软件包许可：MPL-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40capgo/capacitor-device-integrity
原文对照：https://npmcn.com/package/%40capgo/capacitor-device-integrity/?lang=original
项目主页：https://capgo.app/docs/plugins/device-integrity/
源码仓库：https://github.com/Cap-go/capacitor-device-integrity

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

- 包体积（解压后）：113 kB，27 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2026-06-04T09:02:56.456Z
- 最新版本发布：2026-10-15T05:00:14.407Z
- 近 30 天下载量：41026（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

使用Android Widevine,Play Guide,iOS App Attest,以及设备检查的Capacitor设备完整性和欺诈信号.

## 安装

```sh
npm install @capgo/capacitor-device-integrity
```

也可以使用：`pnpm add @capgo/capacitor-device-integrity`、`yarn add @capgo/capacitor-device-integrity`、`bun add @capgo/capacitor-device-integrity`

## README

# @ capgo/ 电容- device- 整齐

在您的 Capacitor app 中收集设备完整性和欺诈信号: 在 Android , App Attest 和 iOS 上的设备检查上播放完整性和威德文指纹. 您的后端可以验证证明和设备检查符并使用威德文指纹作为风险信号.

[![Capgo - Build Capacitor apps with AI, ship updates instantly](https://capgo.app/readme-banner.svg?repo=Cap-go/capacitor-device-integrity)](https://capgo.app/?ref=plugin_device_integrity)

**队长**:在几分钟内将修正推给您的 Capacitor 用户,在没有Mac的情况下构建已签名的iOS和Android apps,并在一击中回滚.

## [\*免费开始\*](https://capgo.app/register/?ref=plugin_device_integrity)

14天无限自由审判. 不需要信用卡

> 🤖 **建筑与AI编码代理?** 安装 [Capgo 技能](https://capgo.app/skills/?ref=plugin_device_integrity) 所以克劳德代码,代码,光标,副驾驶,或双子座CLI知道如何安装和使用 `@capgo/capacitor-device-integrity` 在您的电容应用程序中: `npx skills add Cap-go/capgo-skills`。然后问你的经纪人: _加入@capgo/capor-device-integrity 到我的Capacitor app,并把它接上。"_ [代理设置指南](https://capgo.app/agents/?ref=plugin_device_integrity) • 妇女 [主机磁共振](https://capgo.app/docs/ai/mcp/?ref=plugin_device_integrity)

![@capgo/capacitor-device-integrity for Capacitor apps](https://raw.githubusercontent.com/Cap-go/capacitor-device-integrity/main/assets/github-social-preview.png)

## 主要特点

-   **证明**数字 : `prepareAttestation()` 准备土生土长的证明,然后 `createAttestation()` 从您的后端创建一个与挑战相关的符号 .
-   **要求的断言**数字 : `createAssertion()` 签署服务器侧检查请求的有效载荷.
-   **宽度指纹**数字 : `getWidevineFingerprint()` 返回稳定的Android DRM衍生的ID.
-   **设备检查**数字 : `getDeviceCheckToken()` 为欺诈状态检查创建 iOS 令牌 .
-   **能力**数字 : `getCapabilities()` 报告当前平台所支持的内容.
-   **平台**: iOS和Android. 互联网档案馆的存檔,存档日期2013-12-21. 在网上不可用.

Capacitor 的设备完整性和欺诈信号 :

-   Android: Widevine DRM指纹和Play完整性标准API验证.
-   iOS: App App Attest and Device Check. (原始内容存档于2018-09-29).
-   Web: 不支持的后退报告没有本地能力.

## 安保模式

这个插件是为了发现欺诈和滥用行为而设计的. 它本身并不使客户端的价值观值得信赖.

-   在您的后端验证 App Attest 并播放完整性标志 .
-   将 Widevine 值视为敏感的标识符 .
-   在您的隐私政策中披露标识符的使用 .
-   不使用Android Widevine值进行广告或交叉应用跟踪.
-   不要尝试iOS指纹. 苹果公司不为这个使用案例提供公共审查安全的稳定设备ID.

## 兼容性

| 插件版本 | 电容兼容性 | 维护 |
| --- | --- | --- |
| v八._。 。 。 ._ | v八._。 。 。 ._ | 对 |
| v._。 。 。 ._ | v._。 。 。 ._ | 应要求 |
| v6 (英语)._。 。 。 ._ | v6 (英语)._。 。 。 ._ | 应要求 |

## 安装

您可以使用我们的 AI 辅助设置安装插件 。 使用以下命令将 Capgo 技能添加到您的 AI 工具 :

```bash
npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins
```

然后使用下列提示:

```text
Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-device-integrity` plugin in my project.
```

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

```bash
npm install @capgo/capacitor-device-integrity
npx cap sync
```

## 平台设置

### 机器人

宽宽指纹不需要额外权限.

Play Google Play 需要 Google Play 服务和一个 Cloud 项目编号:

```ts
// capacitor.config.ts
plugins: {
  DeviceIntegrity: {
    cloudProjectNumber: '123456789012'
  }
}
```

也可以通过 `cloudProjectNumber` 直接到证明方法.

### iOS系统

启用 Xcode 中的 App Attest 能力 :

1.  打开你的应用目标.
2.  转到签名能力( C) .
3.  添加 App Attest 选项 .
4.  验证真实的 App Attest 和 Device 行为时对物理设备进行测试 .

## 使用量

```ts
import { DeviceIntegrity } from '@capgo/capacitor-device-integrity';

const capabilities = await DeviceIntegrity.getCapabilities();

if (capabilities.platform === 'android' && capabilities.widevine.fingerprintAvailable) {
  const widevine = await DeviceIntegrity.getWidevineFingerprint();
  await api.saveDeviceSignal({
    widevineIdSha256: widevine.widevineIdSha256,
    fingerprint: widevine.fingerprint,
    securityLevel: widevine.securityLevel,
  });
}

if (capabilities.appAttest.supported || capabilities.playIntegrity.supported) {
  const prepared = await DeviceIntegrity.prepareAttestation();
  const challenge = await api.createDeviceChallenge();

  const attestation = await DeviceIntegrity.createAttestation({
    keyId: prepared.keyId,
    challenge,
  });

  await api.verifyDeviceAttestation(attestation);
}

if (capabilities.deviceCheck.supported) {
  const deviceCheck = await DeviceIntegrity.getDeviceCheckToken();
  await api.verifyDeviceCheckToken(deviceCheck.token);
}
```

## 后端处理

仅在服务器侧面检查后将平台特定证据存储到用户记录中 :

-   Android Widevine: 存储器 `widevineIdSha256` 生的,可以随意选择 `widevineIdBase64` 只有在你明确需要的时候.
-   Android Play Guide:用Google的服务器API来解码返回的令牌并验证请求散列,包名,证书摘要,以及设备/应用完整性判断.
-   iOS App Attest:对照苹果的App Attest规则,应用身份,非ce,公用密钥,和计数器验证验证验证对象/批发.
-   iOS 设备检查: 向 Apple 的设备检查服务器 API 发送令牌, 并在您的后端维护欺诈位.

## API 密码

-   [`getCapabilities()`](https://npmcn.com/package/%40capgo/capacitor-device-integrity/#readme-getcapabilities)
-   [`getWidevineFingerprint(...)`](https://npmcn.com/package/%40capgo/capacitor-device-integrity/#readme-getwidevinefingerprint)
-   [`prepareAttestation(...)`](https://npmcn.com/package/%40capgo/capacitor-device-integrity/#readme-prepareattestation)
-   [`createAttestation(...)`](https://npmcn.com/package/%40capgo/capacitor-device-integrity/#readme-createattestation)
-   [`createAssertion(...)`](https://npmcn.com/package/%40capgo/capacitor-device-integrity/#readme-createassertion)
-   [`getDeviceCheckToken()`](https://npmcn.com/package/%40capgo/capacitor-device-integrity/#readme-getdevicechecktoken)
-   [接口](https://npmcn.com/package/%40capgo/capacitor-device-integrity/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capgo/capacitor-device-integrity/#readme-type-aliases)

### 获取能力( )

```typescript
getCapabilities() => Promise<DeviceIntegrityCapabilities>
```

返回当前平台上可用的本土完整性能力.

**回返情况:** `Promise<[DeviceIntegrityCapabilities](https://npmcn.com/package/%40capgo/capacitor-device-integrity/#readme-deviceintegritycapabilities)>`

* * *

### 获取Widevine Fingerprint (...)

```typescript
getWidevineFingerprint(options?: WidevineFingerprintOptions | undefined) => Promise<WidevineFingerprintResult>
```

返回一个来自Android Widevine的指纹.

默认 `fingerprint` 是SHA -256 在威德文设备上 独一无二的ID和盐. 若为 `hashSalt` 未提供,Android使用应用程序包名作为盐.

原始的 Widevine ID 敏感,只有在 `includeRawId` 这是真的.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[WidevineFingerprintOptions](https://npmcn.com/package/%40capgo/capacitor-device-integrity/#readme-widevinefingerprintoptions)` |

**回返情况:** `Promise<[WidevineFingerprintResult](https://npmcn.com/package/%40capgo/capacitor-device-integrity/#readme-widevinefingerprintresult)>`

* * *

### 准备 Attestation (...)

```typescript
prepareAttestation(options?: PrepareAttestationOptions | undefined) => Promise<PrepareAttestationResult>
```

准备本地验证状态并返回密钥/ 提供者控件 .

iOS:创建 App Attest 密钥. Android:准备一个Play完整性标准代号提供者.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[PrepareAttestationOptions](https://npmcn.com/package/%40capgo/capacitor-device-integrity/#readme-prepareattestationoptions)` |

**回返情况:** `Promise<[PrepareAttestationResult](https://npmcn.com/package/%40capgo/capacitor-device-integrity/#readme-prepareattestationresult)>`

* * *

### 创建 Atterstation (...)

```typescript
createAttestation(options: CreateAttestationOptions) => Promise<AttestationTokenResult>
```

创建绑定在后端所发挑战的注册验证符 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[CreateAttestationOptions](https://npmcn.com/package/%40capgo/capacitor-device-integrity/#readme-createattestationoptions)` |

**回返情况:** `Promise<[AttestationTokenResult](https://npmcn.com/package/%40capgo/capacitor-device-integrity/#readme-attestationtokenresult)>`

* * *

### 创建 Assertion (...)

```typescript
createAssertion(options: CreateAssertionOptions) => Promise<AttestationTokenResult>
```

创建与请求的有效载荷相绑定的请求断言符号.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[CreateAssertionOptions](https://npmcn.com/package/%40capgo/capacitor-device-integrity/#readme-createassertionoptions)` |

**回返情况:** `Promise<[AttestationTokenResult](https://npmcn.com/package/%40capgo/capacitor-device-integrity/#readme-attestationtokenresult)>`

* * *

### 获取Device检查托肯 ()

```typescript
getDeviceCheckToken() => Promise<DeviceCheckTokenResult>
```

为服务器侧欺诈状态检查创建 iOS 设备检查符 .

**回返情况:** `Promise<[DeviceCheckTokenResult](https://npmcn.com/package/%40capgo/capacitor-device-integrity/#readme-devicechecktokenresult)>`

* * *

### 接口

#### 设备集成能力

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`platform`** | `[DeviceIntegrityPlatform](https://npmcn.com/package/%40capgo/capacitor-device-integrity/#readme-deviceintegrityplatform)` | 平台目前正在执行插件 . |
| **`widevine`** | `[WidevineCapabilities](https://npmcn.com/package/%40capgo/capacitor-device-integrity/#readme-widevinecapabilities)` | Android Widevine DRM支持(英语:Android Widevine DRM). |
| **`appAttest`** | `[SupportStatus](https://npmcn.com/package/%40capgo/capacitor-device-integrity/#readme-supportstatus)` | iOS App Attest 支持 (英语). |
| **`deviceCheck`** | `[SupportStatus](https://npmcn.com/package/%40capgo/capacitor-device-integrity/#readme-supportstatus)` | iOS 设备检查支持 . |
| **`playIntegrity`** | `[SupportStatus](https://npmcn.com/package/%40capgo/capacitor-device-integrity/#readme-supportstatus)` | Android Play 诚信支持. |

#### 宽宽能力

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`supported`** | `boolean` | Widevine DRM方案是否由设备支持. |
| **`fingerprintAvailable`** | `boolean` | Widevine 设备独有的ID是否可以读取 . |
| **`securityLevelScanSupported`** | `boolean` | Widevine 安全级别属性是否可以读取 . |

#### 支助现状

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`supported`** | `boolean` | 在当前设备上是否具备此能力 . |

#### 宽宽指纹

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`platform`** | `'android'` | 永远 `android`。 。 。 . |
| **`source`** | `'widevine'` | 永远 `widevine`。 。 。 . |
| **`fingerprint`** | `string` | 将SHA-256指纹与用户记录并存. |
| **`widevineIdSha256`** | `string` | Widevine设备独有的ID的无盐SHA-256散列. |
| **`widevineIdBase64`** | `string` | Raw Widevine设备独有的ID被编码为base64. 只在 `includeRawId` 这是真的. |
| **`securityLevel`** | `string` | 可用时宽度安全级别, 例如 `L1` 或者说 `L3`。 。 。 . |
| **`vendor`** | `string` | 可用的DRM供应商 . |
| **`version`** | `string` | DRM 插件版本可用时 . |
| **`description`** | `string` | 可用时 DRM 插件描述 . |

#### 宽宽字体打印选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`includeRawId`** | `boolean` | 返回原始的Widevine设备独有的ID作为基座64. 默认为 `false`。 。 。 . |
| **`hashSalt`** | `string` | 用来制取的可选盐 `fingerprint`. Android 省略时使用应用程序包名. |

#### 准备Attestation再现

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`keyId`** | `string` | iOS App Attest 密钥ID或Android Play Guide服务商处理ID. |
| **`format`** | `[AttestationFormat](https://npmcn.com/package/%40capgo/capacitor-device-integrity/#readme-attestationformat)` | 当前平台使用的原生证明格式 . |

#### 准备自动站选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`cloudProjectNumber`** | `string` | 仅限Android. Google Cloud project number for Play Guide. Google Cloud 互联网档案馆的存檔,存档日期2013-12-22. 谷歌Cloud project No. 可以通过 `plugins.DeviceIntegrity.cloudProjectNumber`。 。 。 . |

#### 证明 托肯结果

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`token`** | `string` | 必须验证服务器侧的托肯/ 塞子 . |
| **`keyId`** | `string` | 用于创建令牌的密钥/ 提供者手柄 . |
| **`format`** | `[AttestationFormat](https://npmcn.com/package/%40capgo/capacitor-device-integrity/#readme-attestationformat)` | 当前平台使用的原生证明格式 . |

#### 创建 Attestation 选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`keyId`** | `string` | 返回密钥/ 提供者手柄 `prepareAttestation()`。 。 。 . |
| **`challenge`** | `string` | 后端发布一次性挑战. |
| **`cloudProjectNumber`** | `string` | 仅限Android. Google Cloud project number for Play Guide. Google Cloud 互联网档案馆的存檔,存档日期2013-12-22. 谷歌Cloud project No. |

#### 创建代理选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`keyId`** | `string` | 返回密钥/ 提供者手柄 `prepareAttestation()`。 。 。 . |
| **`payload`** | `string` | 后端发布一次性请求有效载荷或非ce. |
| **`cloudProjectNumber`** | `string` | 仅限Android. Google Cloud project number for Play Guide. Google Cloud 互联网档案馆的存檔,存档日期2013-12-22. 谷歌Cloud project No. |

#### 设备检查托肯结果

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`token`** | `string` | iOS 设备检查令牌被编码为 Base64. |

### 类型异名

#### 设备集成格式

`'android' | 'ios' | 'web'`

#### 证明格式

`'apple-app-attest' | 'google-play-integrity-standard'`

## 常见问题

### @capgo/capacitor-device-integrity 是什么？

使用Android Widevine,Play Guide,iOS App Attest,以及设备检查的Capacitor设备完整性和欺诈信号\.

### 如何安装 @capgo/capacitor-device-integrity？

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

### @capgo/capacitor-device-integrity 支持 TypeScript 吗？

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

### @capgo/capacitor-device-integrity 支持 ESM 还是 CommonJS？

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

### @capgo/capacitor-device-integrity 可以商用吗？

@capgo/capacitor-device-integrity 使用 MPL-2\.0 许可。弱 Copyleft：可以商用，也可以和闭源代码一起使用；但如果分发时修改了 MPL 授权的文件，这些文件的修改需以 MPL 开源。以上为概括，不构成法律意见，请以许可原文为准。

### @capgo/capacitor-device-integrity 的下载量有多少？

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

### @capgo/capacitor-device-integrity 还在维护吗？

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