Skip to main content

Base Account와 CDP 임베디드 지갑 통합

기존 Base Account 사용자와 CDP 임베디드 지갑을 통한 신규 사용자 모두를 원활하게 지원하는 온체인 앱을 구축하는 방법을 알아보세요. 통합 인증과 지갑 관리를 제공합니다.

개요

이 통합을 통해 앱은 두 가지 유형의 사용자를 지원할 수 있습니다:
  • 기존 Base 사용자: 친숙한 경험을 위해 Base Account로 연결
  • 신규 온체인 사용자: 이메일, 모바일, 또는 소셜 인증을 통해 CDP 임베디드 지갑 생성
두 유형의 사용자 모두 선호하는 지갑 유형을 사용하면서 동일한 앱 기능을 이용할 수 있습니다.

구축할 내용

  • 통합 인증 플로우: 두 가지 지갑 유형을 모두 지원하는 단일 로그인
  • 자동 지갑 감지: 사용자의 기존 지갑 상태에 따른 스마트 라우팅
  • 일관된 사용자 경험: 두 지갑 유형 모두 동일한 앱 기능에 접근

사전 요구 사항

  • Node.js 18+ 설치
  • React 애플리케이션 (Next.js 권장)
  • Project ID가 있는 CDP Portal 계정
  • Wagmi 및 React hooks 기본 지식

설치

CDP 임베디드 지갑과 Base Account 지원에 필요한 패키지를 설치합니다:

단계별 구현

네이티브 CDP + Base Account 통합이 개발 중이므로, 이 가이드는 두 지갑 유형을 별도의 조율된 커넥터를 통해 지원하는 이중 커넥터 방식을 사용합니다. Base Account Wagmi 커넥터와 CDP의 React 프로바이더 시스템을 함께 사용하면 두 지갑 유형의 지갑 지속성을 올바르게 처리하는 통합 경험을 만들 수 있습니다.

1단계: 환경 변수 설정

CDP 프로젝트의 환경 변수를 생성합니다:
CDP Project ID는 CDP Portal에서 가져옵니다. ⚠️ 중요: 유효한 NEXT_PUBLIC_CDP_PROJECT_ID가 없으면 앱이 “Project ID is required” 오류와 함께 로드되지 않습니다. 또한 CORS를 위해 CDP Portal → Wallets → Embedded Wallet 설정에서 도메인을 설정해야 합니다.

2단계: Base Account 지원을 위한 Wagmi 설정

Base Account 커넥터로 Wagmi를 설정합니다 (임베디드 지갑은 CDP React 프로바이더를 통해 별도로 처리됩니다):

3단계: 애플리케이션 프로바이더 설정

필요한 프로바이더로 애플리케이션을 래핑합니다. 중요: 임베디드 지갑 인증 상태를 올바르게 관리하려면 CDPHooksProvider를 사용하세요:

4단계: 통합 인증 훅 생성

두 지갑 유형을 모두 관리하는 커스텀 훅을 구축합니다. CDPHooksProvider를 사용하면 사용자가 다시 로그인할 때 매번 새로운 지갑을 생성하는 대신 기존 임베디드 지갑을 가져올 수 있습니다.

5단계: 인증 컴포넌트 구축

두 가지 인증 옵션을 제공하는 컴포넌트를 생성합니다:

6단계: 각 지갑 유형별 트랜잭션 처리

각 지갑 유형에 맞게 동작하는 트랜잭션 컴포넌트를 생성합니다:

7단계: 앱 완성

메인 애플리케이션에 모든 것을 조합합니다:

문제 해결

일반적인 문제

Base Account 커넥터가 표시되지 않음
  • Base Account SDK(@base-org/account)가 설치되고 최신 상태인지 확인
  • wagmi 설정에 Base Account 커넥터가 포함되어 있는지 확인
  • 앱이 Base 또는 Base Sepolia 네트워크에서 실행 중인지 확인
CDP 임베디드 지갑 인증 실패
  • 환경 변수에 CDP Project ID가 올바른지 확인
  • 중요: CDP Portal → Wallets → Embedded Wallet 설정 → Allowed domains에 도메인(예: http://localhost:3000, http://localhost:3001)을 추가해야 합니다
  • 필요한 CDP 패키지(위 참조)가 모두 설치되어 있는지 확인
로그인할 때마다 새 지갑이 생성됨
  • 레이아웃에 올바른 설정으로 CDPHooksProvider를 사용하고 있는지 확인
  • CDP Project ID가 올바르게 설정되어 있는지 확인
  • 훅이 @coinbase/cdp-hooks에서 일관되게 임포트되고 있는지 확인
사용자가 지갑 유형 간 전환 불가
  • 다른 유형의 지갑을 연결하기 전에 올바른 연결 해제 플로우 구현
  • 전환 시 캐시된 인증 상태 초기화
  • 지갑 유형 선택을 위한 명확한 UI 안내 제공

향상된 통합 예정

Base Account와 CDP 임베디드 지갑의 네이티브 통합을 적극 개발 중이며, 다음 기능이 지원될 예정입니다:
  • 통합 커넥터: 두 지갑 유형을 원활하게 처리하는 단일 CDP 커넥터
  • 스펜드 퍼미션: 서브 어카운트가 상위 Base Account 잔액을 한도 내에서 접근 가능
  • 서브 어카운트 생성: Base Account 사용자가 앱별 서브 어카운트 생성 가능

리소스

향상된 임베디드 지갑 Base Account 통합 기능 업데이트를 위해 CDP 문서를 주기적으로 확인하세요.