快速入门

安装

你可以使用我们的 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-app-attest` plugin in my project.

如果你更想手动设置，请运行以下命令安装插件，并按照下方各平台的说明操作：

1. 安装软件包

   bun add @capgo/capacitor-app-attest

2. 同步原生项目

   bunx cap sync

3. 配置平台要求

   • 完成 iOS 配置 以实现 App Attest 功能及后端验证流程。
   • 完成 Android 配置 以实现 Play Integrity Standard 及后端验证流程。

快速入门

import { AppAttest } from '@capgo/capacitor-app-attest';

const support = await AppAttest.isSupported();
if (!support.isSupported) throw new Error('Attestation unavailable');

const prepared = await AppAttest.prepare();
const attestation = await AppAttest.createAttestation({
  keyId: prepared.keyId,
  challenge: serverNonce,
});
await sendAttestationToBackend(attestation);

示例：断言请求已认证

const assertion = await AppAttest.createAssertion({
  keyId: storedKeyId,
  payload: requestHash,
});

常见坑点

• 需要后端验证：切勿只信任设备上的 attestation blob，必须在你的服务器上验证。
• Play Integrity 项目编号：Android Standard API 需要 README 中的 Google Cloud 项目编号。
• 密钥存储：使用 storeKeyId() 并在退出登录时清除，避免残留过期密钥。

为什么使用此插件

此插件提供统一的跨平台 API，同时保留原生平台的安全性：

• iOS：Apple App Attest (DeviceCheck)
• Android：Google Play Integrity Standard API
• 无需自定义客户端加密方案
• 标准化输出，便于后端校验

使用情况

import { AppAttest } from '@capgo/capacitor-app-attest';

const support = await AppAttest.isSupported();
if (!support.isSupported) {
  throw new Error(`Attestation not supported on ${support.platform}`);
}

const prepared = await AppAttest.prepare();

const registration = await AppAttest.createAttestation({
  keyId: prepared.keyId,
  challenge: 'backend-one-time-registration-challenge',
});

const assertion = await AppAttest.createAssertion({
  keyId: prepared.keyId,
  payload: 'backend-one-time-request-payload',
});

console.log(registration.platform, registration.format, registration.token);
console.log(assertion.platform, assertion.format, assertion.token);

统一的响应结构

createAttestation() 以及 createAssertion() 在 iOS 和 Android 上返回相同的 key 字段：

字段	类型	描述
platform	'ios' | 'android' | 'web'	生成 token 的原生平台
format	AttestationFormat	apple-app-attest 或 google-play-integrity-standard
keyId	string	用于 attestation 的 key/provider 句柄
token	string	需在后端验证的 token

后端要求

Attestation 只有在服务端验证后才有意义。

• 切勿仅信任客户端的成功状态。
• 要求后端提供一次性 challenge/payload 值。
• 验证 token、应用身份验证以及后端逻辑中的重放保护。

使用特定平台的后端指南：

• iOS 设置与后端验证
• Android 设置与后端验证

从入门指南继续

如果你正在使用 快速入门 来规划安全与合规，请结合 使用 @capgo/capacitor-app-attest 用于“使用 @capgo/capacitor-app-attest”中的原生能力， 加密 了解 Encryption 的实现细节， 合规性 了解合规部分的实现细节， Capgo 安全扫描器 用于 Capgo Security Scanner 中的产品工作流，以及 Capgo 安全 用于 Capgo Security 中的产品工作流。