快速入门

安装

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

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

1. 安装软件包

   bun add @capgo/capacitor-passkey

2. 同步原生项目

   bunx cap sync

3. 添加插件配置

   import type { CapacitorConfig } from '@capacitor/cli';
   
   const config: CapacitorConfig = {
     appId: 'app.capgo.passkey.example',
     appName: 'My App',
     webDir: 'dist',
     plugins: {
       CapacitorPasskey: {
         origin: 'https://signin.example.com',
         autoShim: true,
         domains: ['signin.example.com'],
       },
     },
   };
   
   export default config;

4. 在启动阶段安装 shim

   import { CapacitorPasskey } from '@capgo/capacitor-passkey';
   
   await CapacitorPasskey.autoShimWebAuthn();

5. 保留原有的 WebAuthn 流程

   const registration = await navigator.credentials.create({
     publicKey: registrationOptions,
   });
   
   const authentication = await navigator.credentials.get({
     publicKey: requestOptions,
   });

插件配置的作用

配置读取自 plugins.CapacitorPasskey 中的 capacitor.config.*.

• origin：shim 和直接 API 使用的主要 HTTPS relying-party origin
• domains：在同步期间补丁到原生配置中的额外 relying-party 主机名
• autoShim：默认为 true 并控制原生 cap sync 自动配置 hook

同步补丁能为你做什么

当你运行 bunx cap sync时，插件会更新生成的 native host 项目：

• iOS：关联域名权限以及根据需要配置 Xcode entitlements
• Android： asset_statements metadata 以及 manifest 使用的生成资源

该 hook 不会自动发布你的网站信任文件。你仍需托管：

• https://your-domain/.well-known/apple-app-site-association
• https://your-domain/.well-known/assetlinks.json

示例：直接使用 JSON API（无需 shim）

如果你的后端已经返回 WebAuthn JSON，请直接调用插件方法。

import { CapacitorPasskey } from '@capgo/capacitor-passkey';

const registration = await CapacitorPasskey.createCredential({
  publicKey: registrationOptionsFromServer,
});

const assertion = await CapacitorPasskey.getCredential({
  publicKey: requestOptionsFromServer,
});

使用 isSupported() 在旧设备上显示 passkey UI 之前。

平台指南

iOS 配置

Associated Domains 以及 apple-app-site-association.

Android 配置

Digital Asset Links 以及 assetlinks.json.

后端注意事项

Origin validation 和 Android 注意事项。

从入门指南继续

如果你正在使用 快速入门 用来规划身份验证和账户流程，并将它与 使用 @capgo/capacitor-passkey 在“使用 @capgo/capacitor-passkey”中了解原生能力， @capgo/capacitor-social-login 在 @capgo/capacitor-social-login 中查看实现细节， @capgo/capacitor-passkey 有关 @capgo/capacitor-passkey 的实现细节， @capgo/capacitor-native-biometric 以及 @capgo/capacitor-native-biometric 中的实现细节， 双因素认证 有关双重身份验证的实现细节。