시작하기

설치

AI-Assisted Setup으로 플러그인을 설치할 수 있습니다. 다음 명령어로 AI 도구에 Capgo 스킬을 추가하세요:

bunx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

그런 다음 아래 프롬프트를 사용하세요:

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

수동 설정을 선호한다면, 다음 명령어를 실행하여 플러그인을 설치하고 아래의 플랫폼별 지침을 따르세요:

bun add @capgo/capacitor-neon
bunx cap sync

Neon 설정

1. 활성화 Neon Auth 브랜치에서 (Console > Auth 또는 neon neon-auth enable).
2. 활성화: API 데이터 데이터베이스 헬퍼가 필요한 경우 동일한 브랜치에서 설정하세요 (Console > Data API, Neon Auth를 프로바이더로 선택).
3. 다음을 복사하세요 인증 URL 및 API 데이터 URL Console에서 가져옵니다.

Neon Auth는 신뢰할 수 있는 origin의 요청만 허용합니다. Localhost는 기본적으로 신뢰되며, 플러그인이 Origin: https://localhost를 전송하므로 새 브랜치에서도 변경 없이 작동합니다. Localhost를 비활성화한 경우, 도메인을 신뢰할 수 있는 도메인으로 추가하고 이를 origin 대상 initialize().

iOS 설정

이메일 및 OTP 로그인에는 별도의 설정이 필요하지 않습니다. 이 플러그인은 외부 의존성 없이 URLSession과 Keychain을 사용합니다.

OAuth의 경우, 다음을 설정하세요: redirectTo 신뢰할 수 있는 https 앱을 여는 Universal Link를 설정해야 합니다. Neon Auth는 보안상의 이유로 커스텀 URL scheme을 허용하지 않습니다. redirectTo. 앱에서 커스텀 scheme을 사용하는 경우, 신뢰할 수 있는 HTTPS 콜백 페이지를 호스팅하세요. 이 페이지가 neon_auth_session_verifier query parameter를 해당 scheme으로 전달합니다.

Android 설정

이메일 및 OTP 로그인에는 별도의 설정이 필요하지 않습니다. 이 플러그인은 Capacitor 8 이상의 최소 SDK 24(Android 7.0) 환경에서 작동합니다.

OAuth의 경우, 다음을 설정하세요: redirectTo 신뢰할 수 있는 https 앱을 여는 App Link로. Neon Auth는 커스텀 URL scheme을 redirectTo. 앱에서 커스텀 scheme을 사용하는 경우, 신뢰할 수 있는 HTTPS 콜백 페이지를 호스팅하세요. 이 페이지가 neon_auth_session_verifier query parameter를 해당 scheme으로 전달합니다.

자주 하는 실수

• 리스너: 화면이 언마운트될 때 핸들을 제거합니다.
• 한 번만 초기화: 앱 부트스트랩 시 setup을 실행하세요.
• OAuth 리다이렉트로 거부합니다: Neon Auth는 신뢰할 수 있는 것만 허용합니다 https URL: redirectTo (일반 http only for local testing on trusted localhost). Custom URL schemes are rejected. Use a Universal Link or App Link, or a trusted HTTPS page that forwards the neon_auth_session_verifier 를 앱의 URL scheme으로 전달해야 합니다.
• 신뢰할 수 있는 소스: 신뢰 src/definitions.ts GitHub 레포지토리에서.

클라이언트 초기화

import { CapacitorNeon } from '@capgo/capacitor-neon';

await CapacitorNeon.initialize({
  authUrl: 'https://ep-xxx.neonauth.us-east-2.aws.neon.tech/neondb/auth',
  dataApiUrl: 'https://ep-xxx.apirest.us-east-2.aws.neon.tech/neondb/rest/v1',
});

로그인 및 JWT 액세스

const { session, user } = await CapacitorNeon.signInWithPassword({
  email: 'user@example.com',
  password: 'password123',
});

console.log('User', user?.id);
console.log('JWT available', Boolean(session?.accessToken));

회원가입

만약 가입 시 이메일 인증 브랜치에 활성화되어 있으며, signUp() 사용자가 이메일로 발송된 code을(를) 확인하기 전까지는 세션을 반환하지 않습니다.

import { CapacitorNeon } from '@capgo/capacitor-neon';

const { session } = await CapacitorNeon.signUp({
  email: 'newuser@example.com',
  password: 'password123',
  name: 'John Doe',
});

if (!session) {
  await CapacitorNeon.verifyOtp({
    email: 'newuser@example.com',
    token: '123456',
    type: 'signup',
  });
}

인증 변경 사항 수신

const listener = await CapacitorNeon.addListener('authStateChange', ({ event, session }) => {
  console.log('Auth event', event);
  console.log('Current JWT available', Boolean(session?.accessToken));
});

// Call listener.remove() when the screen unmounts.

Native Auth와 neon-js 연동

이 패턴을 사용할 때는 JavaScript 클라이언트를 설치하세요:

bun add @neondatabase/neon-js

import { CapacitorNeon } from '@capgo/capacitor-neon';
import { createClient } from '@neondatabase/neon-js';

const neon = createClient({
  dataApi: {
    url: 'https://ep-xxx.apirest.us-east-2.aws.neon.tech/neondb/rest/v1',
    getToken: async () => (await CapacitorNeon.getSession()).session?.accessToken ?? null,
  },
});

const { data } = await neon.from('table').select('*');
console.log('Row count', data?.length ?? 0);

Native 데이터베이스 헬퍼

const { data, error } = await CapacitorNeon.select({
  table: 'users',
  columns: 'id, name, email',
  filter: { active: true },
  limit: 10,
  orderBy: 'created_at',
  ascending: false,
});

if (error) {
  console.error('Select failed', error);
} else {
  console.log('Rows returned', data?.length ?? 0);
}

로그인된 사용자가 없는 경우, 데이터베이스 헬퍼는 익명 Data API 토큰을 사용하므로 해당 anonymous 역할 적용.

권장 사용법

• 인증 및 세션 관리에 이 플러그인을 사용하세요.
• 고급 쿼리는 다음에서 유지하세요 @neondatabase/neon-js.
• 유지하세요 Object Storage 및 AI Gateway 호출은 Neon Function 또는 자체 API에서 하세요. 둘 다 앱 번들에 포함되면 안 되는 브랜치 자격 증명을 사용합니다. 해당 서비스의 URL은 공개되어 있으므로, 접근하기 전에 Neon Functions에 대한 요청을 인증하세요.
• 필요할 때마다 네이티브 JWT를 JavaScript 클라이언트, Neon Functions 또는 자체 API로 전달하세요.

시작하기 다음 단계

사용 중이라면 시작하기 네이티브 플러그인 작업을 계획하려면, 이를 다음 항목과 연결하세요: Capgo 플러그인 디렉토리 Capgo Plugin Directory의 제품 워크플로우에 맞춰, Capgo의 Capacitor 플러그인 Capgo의 Capacitor 플러그인 구현 상세 내용에 대해서는, 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트의 구현 세부 사항은, Ionic Enterprise 플러그인 대안 Ionic Enterprise 플러그인 대안의 제품 워크플로우와, Capgo Native Build Capgo Native Builds의 제품 워크플로우를 위해.