快速入门

安装

你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo skills 添加到你的 AI 工具中：

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

然后使用以下 prompt：

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

如果你更倾向于手动设置，请运行以下命令安装插件，并参考下文针对各平台的具体说明：

1. 安装软件包

   bun add @capgo/capacitor-device-integrity

2. 同步原生项目

   bunx cap sync

3. 配置平台要求

   • Android：设置 plugins.DeviceIntegrity.cloudProjectNumber 使用 attestation API 时，为 Play Integrity 进行设置。
   • iOS：在 Xcode 中为 attestation API 启用 App Attest 功能。

快速入门

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

const result = await DeviceIntegrity.getCapabilities();
console.log(result);

示例：getWidevineFingerprint

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

const capabilities = await DeviceIntegrity.getCapabilities();
if (capabilities.widevine.fingerprintAvailable) {
  const result = await DeviceIntegrity.getWidevineFingerprint();
  console.log(result);
}

示例：prepareAttestation

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

const capabilities = await DeviceIntegrity.getCapabilities();
const attestationSupported =
  capabilities.appAttest.supported || capabilities.playIntegrity.supported;

if (attestationSupported) {
  const result = await DeviceIntegrity.prepareAttestation();
  console.log(result);
}

常见坑点

• 原生同步: 运行 npx cap sync 在插件升级后。
• 单一事实来源: 信任 src/definitions.ts 在 GitHub 仓库中。

为什么使用此插件

使用一个 API 在注册、登录或高风险操作期间收集完整性信号：

• 在调用 native APIs 前探测支持情况 (getCapabilities)
• 使用 Widevine 对 Android 设备进行指纹识别 (getWidevineFingerprint)
• 使用 App Attest 或 Play Integrity 进行注册与断言 (prepareAttestation, createAttestation, createAssertion)
• 请求 iOS DeviceCheck tokens (getDeviceCheckToken)

在您的后端验证 tokens 并执行重放保护之前，客户端传回的值是不可信的。

用量

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

const capabilities = await DeviceIntegrity.getCapabilities();
console.log(capabilities.platform, capabilities.playIntegrity.supported);

if (capabilities.widevine.fingerprintAvailable) {
  const widevine = await DeviceIntegrity.getWidevineFingerprint();
  console.log(widevine.fingerprint, widevine.securityLevel);
}

const attestationSupported =
  capabilities.appAttest.supported || capabilities.playIntegrity.supported;

if (attestationSupported) {
  try {
    const prepared = await DeviceIntegrity.prepareAttestation();

    const challengeResponse = await fetch(
      'https://api.example.com/integrity/registration-challenge',
    );
    if (!challengeResponse.ok) {
      throw new Error(`Challenge request failed with ${challengeResponse.status}`);
    }
    const challengeBody = await challengeResponse.json();
    if (typeof challengeBody.challenge !== 'string' || challengeBody.challenge.length === 0) {
      throw new Error('Backend response missing challenge');
    }
    const challenge = challengeBody.challenge;

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

    const payloadResponse = await fetch(
      'https://api.example.com/integrity/assertion-payload',
    );
    if (!payloadResponse.ok) {
      throw new Error(`Payload request failed with ${payloadResponse.status}`);
    }
    const payloadBody = await payloadResponse.json();
    if (typeof payloadBody.payload !== 'string' || payloadBody.payload.length === 0) {
      throw new Error('Backend response missing payload');
    }
    const payload = payloadBody.payload;

    const assertion = await DeviceIntegrity.createAssertion({
      keyId: prepared.keyId,
      payload,
    });

    console.log(registration.format, registration.token);
    console.log(assertion.format, assertion.token);
  } catch (error) {
    console.error('Attestation flow failed', error);
  }
}

if (capabilities.deviceCheck.supported) {
  const deviceCheck = await DeviceIntegrity.getDeviceCheckToken();
  console.log(deviceCheck.token);
}

Widevine 选项

getWidevineFingerprint() 接受以下可选字段：

字段	类型	描述
includeRawId	boolean	若为 true，则包含 base64 格式的 Widevine 设备原始 ID（敏感信息）。
hashSalt	string	用于 —— 的 Salt fingerprint。若省略，Android 将使用应用包名。

后端要求

• 在您的服务器上验证 App Attest 和 Play Integrity token。
• 请将 Widevine 标识符视为敏感信息，并在隐私政策中披露使用情况。
• 请勿将 Widevine 值用于广告或跨应用追踪。

继续阅读入门指南

如果你正在使用 快速入门 以规划安全与合规，并将其与 使用 @capgo/capacitor-device-integrity 用于“使用 @capgo/capacitor-device-integrity”中的原生能力， @capgo/capacitor-app-attest 用于聚焦 App Attest 和 Play Integrity 的流程， 加密 以了解 Encryption 中的实现细节， 合规性 了解 Compliance 中的实现细节，以及 Capgo 安全性 了解 Capgo Security 中的产品工作流。