跳过主要内容
Capgo logo
教程

设置Capacitor

学习如何将Capgo与Capacitor集成

文章致谢

马丁·多纳迪尤

作者

瓦莱里亚

审阅者

乔丹

编辑器

使用Capacitor与Supabase设置社交登录

在移动应用中设置身份验证可能会很复杂，但结合 Supabase 与 Capgo社交登录插件 可以使其变得简单。这篇教程将指导您在Capacitor应用中集成社交身份验证（Google、Apple、Facebook）和Supabase。

为什么要使用Supabase与社交登录?

Supabase 提供了一个强大的后端服务，内置身份验证，而 @capgo/capacitor-social-login 插件则提供了原生社交身份验证，适用于iOS、Android和web平台。为了实现更紧密的Supabase集成, @capgo/capacitor-supabase 提供原生认证辅助函数和 JWT 访问。它们共同提供:

  • 无缝的社交认证
  • 安全令牌管理
  • 跨平台兼容性
  • 实时数据库集成
  • 内置用户管理

前提条件

开始之前，请确保您有:

  • 一个 Capacitor 项目已设置
  • 一个 Supabase 帐户和项目
  • 您选择的社交提供商（Google、Apple、Facebook）的开发者帐户

第一步：安装和配置社交登录插件

首先，安装Capgo社交登录插件：

npm install @capgo/capacitor-social-login
npx cap sync

查看 社交登录 和 Supabase 插件页面

第二步：设置Supabase项目

创建和配置您的Supabase项目

  1. 创建一个Supabase项目:

    • 前往 supabase.com 并注册/登录
    • 点击 “新项目”
    • 选择您的组织
    • 输入一个 项目名称 (例如，“MyApp Auth”)
    • 设置一个 数据库密码 (安全保存)
    • 选择您的 区域 （选择最接近您的用户）
    • 点击 “创建新项目”

  2. 获取您的项目凭证:

    • 创建后，前往 设置 > API
    • 复制您的 项目 URL (例如， https://your-project-ref.supabase.co)
    • 复制您的 匿名公共 API 密钥
    • 保存这些用于后续在应用中使用

配置身份验证设置

  1. 设置通用身份验证设置:

    • 前往 身份验证 > 设置
    • 在 通用设置:
      • 设置 站点URL 到您的应用的URL（例如， https://yourdomain.com 或 http://localhost:3000 用于开发
      • 添加额外的 重定向 URL 如果需要: 
        http://localhost:3000
https://yourdomain.com
capacitor://localhost (for mobile apps)

  2. 配置电子邮件设置 (可选但建议):

    • 在 SMTP 设置,配置您的电子邮件提供商
    • 这使电子邮件确认和密码重置可用
    • 对于开发，您可以使用内置的电子邮件服务

启用社交身份验证提供商

  1. 访问提供商部分:
    • 前往 身份验证 > 提供者 您的 Supabase 控制台中
    • 您将看到可用的社交提供者的列表
    • 每个提供者都有一个 启用 开关和配置选项

现在，让我们详细配置每个社交提供者:

步骤 3：在 Supabase 中配置社交提供者

在 Supabase 中设置 Google 认证

首先，获取您的 Google OAuth 凭证：

遵循我们的全面 Google 设置指南： Google认证设置

本指南涵盖:

  • 创建Google Cloud项目
  • 为Web、iOS和Android设置OAuth 2.0凭据
  • 配置-consent屏幕
  • 获取所需的客户端ID和密钥

完成Google设置后，在Supabase中配置:

  1. 在Supabase中启用Google提供者:
    • 在您的Supabase控制台中，转到 身份验证>提供者
    • 找到 Google 并且切换它 开启
    • 填写配置:
      • 客户端 ID:您的 Google OAuth Web 客户端 ID（来自 Google Cloud 控制台）
      • 客户端密钥:您的 Google OAuth Web 客户端密钥
      • 重定向 URL: https://your-project-ref.supabase.co/auth/v1/callback （自动填充）
    • 点击 “保存”

重要提示使用 Web Client ID 和 Web Client Secret 在 Supabase 中，即使您正在构建移动应用程序，也需要使用 Web Client ID。移动客户端 ID 在插件配置中单独使用。

设置 Apple 认证在 Supabase 中

获取 Apple 凭证：

遵循我们的详细 Apple 设置指南： Apple Authentication Setup

本指南涵盖:

  • 设置您的Apple开发者账户
  • 创建App ID和Service ID
  • 配置Apple登录能力
  • 生成所需的私钥
  • 针对iOS、Android和Web的平台特定设置

完成Apple设置后，在Supabase中配置:

  1. 在Supabase中启用Apple提供者:
    • 前往 身份验证 > 提供者 并切换 Apple ON
    • 填写配置:
      • Client ID:您的服务 ID 标识符（例如， com.yourapp.signin)
      • Client Secret:使用您的 Apple 私钥生成此 JWT（参见 Apple Supabase 文档 为 JWT 格式)
      • Redirect URL: https://your-project-ref.supabase.co/auth/v1/callback (自动填充)
    • 点击 “保存”

注意: Apple认证设置是最复杂的，因为Apple要求Service ID、私钥和JWT生成。请仔细阅读每个平台的文档。

在Supabase中设置Facebook认证

获取Facebook凭证:

请遵循我们的完整Facebook设置指南: Facebook认证设置

本指南涵盖:

  • 创建Facebook开发者帐户和应用
  • 添加Facebook登录产品
  • 配置OAuth重定向URI
  • 获取您的App ID、App Secret和Client Token
  • iOS 和 Android 的平台特定配置

完成 Facebook 设置后，在 Supabase 中配置它:

  1. 在 Supabase 中启用 Facebook 提供者:
    • 前往 身份验证 > 提供者 并切换 Facebook 开启
    • 填写配置:
      • 客户端 ID: 你的 Facebook App ID
      • 客户端密钥: Your Facebook App Secret
      • 重定向 URL: https://your-project-ref.supabase.co/auth/v1/callback (自动填充)
    • 点击 “保存”

重要: 确保将 Supabase 回调 URL (https://your-project-ref.supabase.co/auth/v1/callback) 添加到您的 Facebook 应用程序的 有效 OAuth 重定向 URI 在 Facebook 登录设置中。

重要的 Supabase 配置说明

行级安全性 (RLS):

  • 完成身份验证设置后，启用表格的 RLS
  • 前往 数据库 > 表格 并切换 启用 RLS 为每个表格
  • 创建策略来控制基于已验证用户的数据访问

用户管理：

  • 查看已验证用户在 身份验证 > 用户
  • 监控身份验证事件在 身份验证 > 日志
  • 设置电子邮件模板在 身份验证 > 电子邮件模板

测试配置:

  • 使用 Supabase 内置的身份验证测试工具
  • 前往 身份验证 > 用户 并点击 “邀请用户” 测试电子邮件流程
  • 检查 日志 区域：Capgo Builder / 原生云构建产品页面。角色：短 UI 标签或导航项。见于：页面 native-build.astro。消息键 `native_build_v2_trust_logs_lbl` (原生构建 V2 信任日志 Lbl)。

第 4 步：配置社交登录插件

现在已配置 Supabase，需要使用相应凭证设置社交登录插件。 重要: 社交登录插件需要从原提供商那里获取 OAuth 凭证（而不是从 Supabase），而 Supabase 负责服务器端身份验证。 身份验证流程 在配置之前，了解流程：

插件使用社交提供商（Google/Apple/Facebook）进行原生身份验证

插件从提供商那里接收令牌

  1. （访问令牌、ID 令牌） __CAPGO_KEEP_0__
  2. __CAPGO_KEEP_0__ __CAPGO_KEEP_0__
  3. 您的应用程序发送这些令牌 使用 signInWithIdToken()
  4. Supabase 验证 令牌与提供商并创建用户会话
  5. Supabase 返回 自己的 JWT 令牌用于您的应用程序的已验证请求

Google 插件配置

插件需要您的 Web 客户端 ID 所有平台和可选地 iOS 客户端 ID 用于 iOS 特定功能： __CAPGO_KEEP_0__

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

await SocialLogin.initialize({
  google: {
    // Use the same Web Client ID you configured in Supabase
    webClientId: 'YOUR_WEB_CLIENT_ID.apps.googleusercontent.com',
    
    // Optional: iOS Client ID for iOS-specific features
    iOSClientId: 'YOUR_IOS_CLIENT_ID.apps.googleusercontent.com',
    
    // Optional: Request offline access for refresh tokens
    mode: 'offline'
  }
});

Google 的关键点:

  • 使用 Web Client ID (而不是 Android/iOS 客户端 ID) 的 webClientId 字段
  • 仅需 Web Client ID 即可在所有平台上使用该插件
  • 是可选的，仅用于 iOS 特有的 Google 功能 iOSClientId Apple Plugin Configuration

Apple 配置在 iOS 和 Android 之间有所不同:

对于 iOS

(原生 Apple Sign-In): __CAPGO_KEEP_0__

await SocialLogin.initialize({
  apple: {
    // No additional configuration needed for iOS
    // The plugin uses the native Apple Sign-In capability
  }
});

Android/Web (需要 Service ID):

await SocialLogin.initialize({
  apple: {
    clientId: 'YOUR_SERVICE_ID', // The Service ID from Apple Developer Portal
    redirectUrl: 'https://your-project-ref.supabase.co/auth/v1/callback'
  }
});

Apple 的关键点:

  • iOS 使用原生 Sign in with Apple (无需额外配置)
  • Android/Web 需要您在 Apple Developer Portal 中创建的 Service ID
  • 应与您在 Apple Developer Portal 和 Supabase 中配置的内容一致 redirectUrl Facebook 插件配置

Facebook 需要您的 App ID 和 Client Token:

Facebook 的关键点:

await SocialLogin.initialize({
  facebook: {
    appId: 'YOUR_FACEBOOK_APP_ID',        // From Facebook Developer Dashboard
    clientToken: 'YOUR_FACEBOOK_CLIENT_TOKEN', // From Facebook Developer Dashboard
    
    // Optional: Use Facebook Limited Login (for enhanced privacy)
    limitedLogin: false // See our Facebook setup guide for important Limited Login details
  }
});

使用您在 Supabase 中配置的相同 App ID

  • Client Token 可在您的 Facebook App 的基本设置中找到
  • Facebook Plugin Configuration
  • limitedLogin: true 支持 Facebook 的隐私聚焦的有限登录功能（仅限 iOS）
  • 重要: 查看我们的 Facebook 设置指南 获取详细的有限登录信息，包括 ATT 考虑

完成插件初始化

注意事项：

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

export async function initializeSocialLogin() {
  await SocialLogin.initialize({
    google: {
      webClientId: 'YOUR_WEB_CLIENT_ID.apps.googleusercontent.com',
      mode: 'offline'
    },
    facebook: {
      appId: 'YOUR_FACEBOOK_APP_ID',
      clientToken: 'YOUR_FACEBOOK_CLIENT_TOKEN',
    },
    apple: {
      // iOS: no config needed
      // Android/Web: uncomment the lines below
      // clientId: 'YOUR_SERVICE_ID',
      // redirectUrl: 'https://your-project-ref.supabase.co/auth/v1/callback'
    }
  });
}

调用

  • 一次 initialize() 当您的应用启动时，而不是在每次登录之前 您只需配置您打算使用的提供者
  • __CAPGO_KEEP_0__
  • 这里的凭据来自于 原始提供者,而不是来自 Supabase
  • 确保提供者凭据与您在 Supabase 中配置的凭据匹配

步骤 5: 配置 Supabase 客户端

安装 Supabase 客户端：

npm install @supabase/supabase-js

创建一个 Supabase 服务：

// services/supabase.ts
import { createClient } from '@supabase/supabase-js';

const supabaseUrl = 'https://your-project-ref.supabase.co';
const supabaseKey = 'your-anon-public-key';

export const supabase = createClient(supabaseUrl, supabaseKey, {
  auth: {
    autoRefreshToken: true,
    persistSession: true,
    detectSessionInUrl: false,
  },
});

步骤 6: 实现身份验证流程

创建一个结合了两者的身份验证服务：

// services/auth.ts
import { SocialLogin } from '@capgo/capacitor-social-login';
import { supabase } from './supabase';

export class AuthService {
  
  async initializeSocialLogin() {
    await SocialLogin.initialize({
      google: {
        webClientId: 'YOUR_WEB_CLIENT_ID.apps.googleusercontent.com',
      },
      facebook: {
        appId: 'YOUR_FACEBOOK_APP_ID',
        clientToken: 'YOUR_FACEBOOK_CLIENT_TOKEN',
      },
      apple: {} // iOS configuration
    });
  }

  async signInWithGoogle() {
    try {
      const result = await SocialLogin.login({
        provider: 'google',
        options: {
          scopes: ['email', 'profile']
        }
      });

      const googleResult = result.result;
      if (!googleResult) {
        throw new Error('Google login failed');
      }

      // GoogleLoginResponse is a union type - check responseType to determine flow
      if (googleResult.responseType === 'online') {
        // Online mode: use idToken directly with Supabase
        const { data, error } = await supabase.auth.signInWithIdToken({
          provider: 'google',
          token: googleResult.idToken!,
        });
        if (error) throw error;
        return data;
      } else {
        // Offline mode: exchange serverAuthCode on your backend
        // Your backend should exchange the code for tokens and create a Supabase session
        const response = await fetch('/api/auth/google', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ serverAuthCode: googleResult.serverAuthCode })
        });
        return response.json();
      }
    } catch (error) {
      console.error('Google sign-in error:', error);
      throw error;
    }
  }

  async signInWithApple() {
    try {
      const result = await SocialLogin.login({
        provider: 'apple',
        options: {
          scopes: ['email', 'name']
        }
      });

      const { data, error } = await supabase.auth.signInWithIdToken({
        provider: 'apple',
        token: result.result?.identityToken!,
      });

      if (error) throw error;
      return data;
    } catch (error) {
      console.error('Apple sign-in error:', error);
      throw error;
    }
  }

  async signInWithFacebook() {
    try {
      const result = await SocialLogin.login({
        provider: 'facebook',
        options: {
          permissions: ['email', 'public_profile']
        }
      });

      const fbResult = result.result;
      if (!fbResult?.accessToken?.token) {
        throw new Error('Facebook login failed - no access token received');
      }

      // Facebook uses accessToken for Supabase authentication
      const { data, error } = await supabase.auth.signInWithIdToken({
        provider: 'facebook',
        token: fbResult.accessToken.token,
      });

      if (error) throw error;
      return data;
    } catch (error) {
      console.error('Facebook sign-in error:', error);
      throw error;
    }
  }

  async signOut() {
    // Sign out from Supabase
    await supabase.auth.signOut();
    
    // Optionally sign out from social providers
    await SocialLogin.logout({
      provider: 'google' // or 'apple', 'facebook'
    });
  }

  getCurrentUser() {
    return supabase.auth.getUser();
  }

  onAuthStateChange(callback: (event: string, session: any) => void) {
    return supabase.auth.onAuthStateChange(callback);
  }
}

export const authService = new AuthService();

步骤 7: 在您的应用中实现

初始化服务并处理身份验证：

// main.ts or app component
import { authService } from './services/auth';

async function initializeApp() {
  await authService.initializeSocialLogin();
  
  // Listen to auth state changes
  authService.onAuthStateChange((event, session) => {
    if (event === 'SIGNED_IN') {
      console.log('User signed in:', session.user);
      // Redirect to authenticated area
    } else if (event === 'SIGNED_OUT') {
      console.log('User signed out');
      // Redirect to login
    }
  });
}

initializeApp();

在您的 UI 中创建登录按钮：

// Login component
async function handleGoogleLogin() {
  try {
    const user = await authService.signInWithGoogle();
    console.log('Signed in with Google:', user);
  } catch (error) {
    console.error('Login failed:', error);
  }
}

async function handleAppleLogin() {
  try {
    const user = await authService.signInWithApple();
    console.log('Signed in with Apple:', user);
  } catch (error) {
    console.error('Login failed:', error);
  }
}

async function handleFacebookLogin() {
  try {
    const user = await authService.signInWithFacebook();
    console.log('Signed in with Facebook:', user);
  } catch (error) {
    console.error('Login failed:', error);
  }
}

async function handleLogout() {
  try {
    await authService.signOut();
    console.log('Signed out successfully');
  } catch (error) {
    console.error('Logout failed:', error);
  }
}

第 8 步：平台特定配置

iOS 配置

详细的 iOS 配置指南请参见我们的平台特定指南：

快速摘要 - 添加到 ios/App/App/Info.plist:

<!-- Google Sign-In URL scheme -->
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>YOUR_REVERSED_CLIENT_ID</string>
    </array>
  </dict>
</array>

<!-- Apple Sign-In capability -->
<key>com.apple.developer.applesignin</key>
<array>
  <string>Default</string>
</array>

按照链接指南完成 iOS 设备的设置，包括 Xcode 项目配置。

Android 配置

要了解详细的 Android 设备设置，请参阅我们的平台特定指南：

Android 设备的基本设置:

1. 获取 SHA-1 指纹 （必需的，用于 Google）：

# For debug builds (development)
cd android
./gradlew signingReport

# Look for the SHA1 fingerprint under "Variant: debug"
# Add this SHA1 to your Google Cloud Console Android OAuth client

2. 配置 AndroidManifest.xml - 添加到 android/app/src/main/AndroidManifest.xml:

<!-- Internet permission -->
<uses-permission android:name="android.permission.INTERNET" />

<!-- Facebook configuration -->
<meta-data 
  android:name="com.facebook.sdk.ApplicationId" 
  android:value="@string/facebook_app_id"/>
<meta-data 
  android:name="com.facebook.sdk.ClientToken" 
  android:value="@string/facebook_client_token"/>

3. 添加 Facebook 资源 到 android/app/src/main/res/values/strings.xml:

<string name="facebook_app_id">YOUR_FACEBOOK_APP_ID</string>
<string name="facebook_client_token">YOUR_FACEBOOK_CLIENT_TOKEN</string>

context

页面/区域：实时更新产品页面。角色：短 UI 标签或导航项。消息键 `live_update_dynamic_label_to` (实时更新动态标签到)。

遵循链接的平台指南，完成 Android 配置，包括 Google Play 服务设置和包名配置。

// Example: Fetch user profile
async function getUserProfile() {
  const { data: user } = await supabase.auth.getUser();
  
  if (user) {
    const { data, error } = await supabase
      .from('profiles')
      .select('*')
      .eq('id', user.user.id)
      .single();
    
    return data;
  }
}

// Example: Update user profile
async function updateUserProfile(updates: any) {
  const { data: user } = await supabase.auth.getUser();
  
  if (user) {
    const { data, error } = await supabase
      .from('profiles')
      .update(updates)
      .eq('id', user.user.id);
    
    return data;
  }
}

步骤 9：使用 Supabase 数据库与已验证用户

  1. 一旦用户验证成功，您就可以使用 Supabase 的数据库，带有行级安全性 (RLS)： in your client code
  2. 绝不暴露敏感密钥 为配置
  3. 启用行级安全性 在 Supabase 中
  4. 验证令牌 在需要时在您的后端验证令牌
  5. 自动刷新令牌 解决常见问题

令牌匹配错误

确保您的社交登录插件和 Supabase 之间的 OAuth 提供商配置匹配

  • 检查重定向 URL 是否正确配置
  • 平台特定问题

__CAPGO_KEEP_0__

  • iOS: 确认您的 bundle ID 与 Apple Developer 配置匹配
  • Android: 确保 SHA1 指纹正确添加到 Google Console

Authentication Flow 中断

  • 网络问题时实现适当的错误处理
  • 在身份验证期间添加加载状态

结论

您现在已经拥有一个结合了 Supabase 强大的后端和本机社交登录功能的完整身份验证系统。该设置提供:

  • 安全的本机社交身份验证
  • 无缝令牌管理
  • 实时数据库集成
  • 跨平台兼容性

Supabase 和 Capgo 社交登录插件的结合提供了一个强大的、可扩展的身份验证解决方案，适用于您的 Capacitor 应用

为了获得更高级的功能，如 多因素认证 或 查看Capacitor的自定义声明 ，查看 Supabase文档 和.

Keep going from Setup Supabase Authentication with Capacitor Social Login Plugin

继续Setup Supabase Authentication with __CAPGO_KEEP_0__ Social Login Plugin Setup Supabase Authentication with Capacitor Social Login Plugin Setup Supabase Authentication with __CAPGO_KEEP_0__ Social Login Plugin @capgo/capacitor-social-login 为 @capgo/capacitor-social-login 的实现细节 @capgo/capacitor-passkey 为 @capgo/capacitor-passkey 的实现细节 @capgo/capacitor-native-biometric 为 @capgo/capacitor-native-biometric 的实现细节 双因素认证 双因素认证的实现细节， SSO (企业) SSO (企业) 的实现细节。

Capacitor 应用的实时更新

当一个 web-layer 错误活跃时，通过 Capgo 直接将修复推送给用户，而不是等待几天的 app store 审核。用户在后台接收更新，而原生变化仍在正常的审查路径中。

来自 Martin 的人性化支持

立即开始

最新博客

Capgo 给您创建真正专业的移动应用所需的最佳见解。

Capacitor 应用的双向通信
开发 移动 +1
2025年4月26日

双向通信在Capacitor应用中

避免的5种OTA更新常见错误
开发 安全性 +1
页面/区域: 企业产品/定价页面。角色: UI标签。见于: 企业.astro页面。消息键 `enterprise_hero_security_label` (企业英雄安全标签)。

2025年4月13日

移动应用实时更新的5种安全最佳实践
移动应用实时更新的5种安全最佳实践 开发 +1
2025年1月14日

5条关于移动应用程序实时更新的安全最佳实践

查看我们博客的所有内容