快速入门

复制包含安装步骤和该插件完整 Markdown 指南的配置 prompt。

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-social-login`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/social-login/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.

安装

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

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

然后使用以下 prompt：

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

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

安装软件包
终端窗口
```
bun add @capgo/capacitor-social-login
```
与原生项目同步
终端窗口
```
bunx cap sync
```

在应用启动时初始化

import { SocialLogin } from '@capgo/capacitor-social-login';

await SocialLogin.initialize({
  google: {
    webClientId: 'your-google-web-client-id',
    iOSClientId: 'your-google-ios-client-id',
    iOSServerClientId: 'your-google-web-client-id',
    mode: 'online',
  },
  apple: {
    clientId: 'your-apple-service-id',
    useProperTokenExchange: true,
    useBroadcastChannel: true,
  },
  facebook: {
    appId: 'your-facebook-app-id',
  },
  twitter: {
    clientId: 'your-twitter-client-id',
    redirectUrl: 'myapp://oauth/twitter',
  },
  oauth2: {
    github: {
      appId: 'your-github-client-id',
      authorizationBaseUrl: 'https://github.com/login/oauth/authorize',
      accessTokenEndpoint: 'https://github.com/login/oauth/access_token',
      redirectUrl: 'myapp://oauth/github',
      scope: 'read:user user:email',
      pkceEnabled: true,
    },
  },
});

团队何时选择此插件

一个包即可支持 Google、Apple、Facebook、Twitter/X 以及自定义 OAuth2 或 OIDC 提供商。
通过 Credential Manager 实现 Android Google Sign-In，而非使用已弃用的社区插件。
通过文档中说明的兼容层支持 Ionic Auth Connect 风格的提供商。
需要在移动端和 Web 构建之间共享登录 code 的应用。

核心流程示例

await SocialLogin.login({
  provider: 'google',
  options: { scopes: ['profile', 'email'] },
});

await SocialLogin.login({
  provider: 'oauth2',
  options: {
    providerId: 'github',
    scope: 'read:user user:email',
  },
});

会话检查

const status = await SocialLogin.isLoggedIn({ provider: 'google' });
await SocialLogin.logout({ provider: 'google' });

授权码与刷新

// For providers that support this mode
const authCodeResult = await SocialLogin.getAuthorizationCode({ provider: 'google' });
await SocialLogin.refresh({ provider: 'google', options: {} as never });

高级辅助函数

const jwt = await SocialLogin.decodeIdToken({
  idToken: 'eyJhbGciOi...',
});

const { date } = await SocialLogin.getAccessTokenExpirationDate({
  accessTokenExpirationDate: Date.now() + 3600 * 1000,
});

const expired = await SocialLogin.isAccessTokenExpired({
  accessTokenExpirationDate: Date.now() + 1000,
});

const active = await SocialLogin.isRefreshTokenAvailable({ refreshToken: 'a-token' });

各 Provider 注意事项

Google 离线模式

google.mode: 'offline' 返回 serverAuthCode 从登录返回。在此模式下，logout、isLoggedIn、getAuthorizationCode 和 refresh 均不可用。

使用 serverAuthCode 仅作为后端 token 交换的输入。如果你需要调用 SocialLogin.refresh() 在应用内，请使用 google.mode: 'online' 请改用这种方式。

Apple

设置 useProperTokenExchange: true 用于严格的 Token 处理以及 useBroadcastChannel: true 用于 Android 的简化配置。

OAuth2 Web 重定向流程

使用 OAuth2LoginOptions.flow: 'redirect' 适用于会跳转出当前页面的 Web 流程。

动态 Provider 依赖

你可以配置要包含哪些 provider 以减小原生 App 的体积。当你的 App 仅需要特定的 provider 时，这非常有用。

将 provider 配置添加到 capacitor.config.ts:

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'MyApp',
  webDir: 'dist',
  plugins: {
    SocialLogin: {
      providers: {
        google: true,
        facebook: true,
        apple: true,
        twitter: false,
      },
      logLevel: 1,
    },
  },
};

export default config;

Provider 取值含义：

true：已启用该 provider，且其原生依赖已打包。
false：已禁用该 provider，且其原生依赖未打包。

重要详情：

运行 bunx cap sync 修改 provider 配置后。
若未提供 provider 配置，所有 provider 默认设为 true 以保持向后兼容性。
禁用 provider 会 false 使其在运行时不可用，即使该 provider 仅使用系统 API。
此配置仅影响 iOS 和 Android；不影响 Web 端。
Android 上的 Apple Sign-In 使用 OAuth，无需外部 SDK 依赖。
Twitter/X 使用标准 OAuth 2.0，无需外部 SDK 依赖。

若仅需集成 Google Sign-In 和 Apple Sign-In：

plugins: {
  SocialLogin: {
    providers: {
      google: true,
      facebook: false,
      apple: true,
      twitter: false,
    },
  },
}

从入门指南继续

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