Panduan Memulai

Instal

Anda bisa menggunakan AI-Assisted Setup kami untuk menginstal plugin ini. Tambahkan skill Capgo ke tool AI Anda dengan command berikut:

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

Lalu gunakan prompt berikut:

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

Jika Anda lebih memilih Manual Setup, instal plugin dengan menjalankan perintah berikut dan ikuti petunjuk khusus platform di bawah ini:

bun add @capgo/capacitor-neon
bunx cap sync

Setup Neon

1. Aktifkan Neon Auth di branch Anda (Console > Auth, atau neon neon-auth enable).
2. Aktifkan Data API di branch yang sama jika Anda ingin helper database (Console > Data API, dengan Neon Auth sebagai provider).
3. Salin URL Autentikasi dan URL API Data dari Console.

Neon Auth hanya menerima permintaan dari origin yang tepercaya. Localhost tepercaya secara default, dan plugin mengirim Origin: https://localhost, sehingga branch baru berfungsi tanpa perubahan. Jika Anda mematikan localhost, tambahkan salah satu domain Anda sebagai domain tepercaya dan lewati sebagai origin ke initialize().

Setup iOS

Tidak diperlukan pengaturan tambahan untuk sign-in email dan OTP. Plugin ini menggunakan URLSession dan Keychain, tanpa dependensi pihak ketiga.

Untuk OAuth, atur redirectTo ke sebuah https Universal Link tepercaya yang membuka aplikasi Anda. Neon Auth menolak skema URL kustom sebagai redirectTo. Jika Anda menggunakan skema kustom di aplikasi, host halaman callback HTTPS yang tepercaya yang meneruskan neon_auth_session_verifier parameter query ke skema tersebut.

Setup Android

Tidak diperlukan pengaturan tambahan untuk sign-in email dan OTP. Plugin ini bekerja dengan Capacitor 8, minimum default SDK 24 (Android 7.0).

Untuk OAuth, atur redirectTo ke sebuah https App Link yang membuka aplikasi Anda. Neon Auth menolak skema URL kustom sebagai redirectTo. Jika Anda menggunakan skema kustom di aplikasi, host halaman callback HTTPS yang tepercaya yang meneruskan neon_auth_session_verifier parameter query ke skema tersebut.

Kesalahan umum

• Listener: hapus handle saat screen unmount.
• Inisialisasi sekali saja: jalankan setup saat app bootstrap.
• Redirect OAuth: Neon Auth hanya menerima yang trusted https URL untuk redirectTo (plain http hanya untuk pengujian lokal di localhost terpercaya). Custom URL scheme ditolak. Gunakan Universal Link atau App Link, atau halaman HTTPS terpercaya yang meneruskan neon_auth_session_verifier parameter query ke URL scheme aplikasi Anda.
• Sumber kebenaran tunggal: percayai src/definitions.ts di repo GitHub.

Inisialisasi Client

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',
});

Login dan Akses 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));

Daftar

Jika Verifikasi email saat daftar diaktifkan untuk branch Anda, signUp() tidak mengembalikan sesi sampai pengguna mengonfirmasi code yang dikirimkan via email.

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',
  });
}

Pantau Perubahan Auth

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.

Pasangkan Native Auth dengan neon-js

Instal klien JavaScript saat Anda menggunakan pola ini:

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);

Helper Database 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);
}

Saat tidak ada yang masuk, helper database menggunakan token Data API anonim, sehingga kebijakan keamanan tingkat baris untuk anonymous role diterapkan.

Rekomendasi Penggunaan

• Gunakan plugin ini untuk autentikasi dan manajemen sesi.
• Simpan query lanjutan di @neondatabase/neon-js.
• Pertahankan Penyimpanan Objek dan AI Gateway panggilan di Neon Function atau API Anda sendiri. Keduanya menggunakan kredensial branch yang harus dijauhkan dari app bundle. Autentikasi permintaan ke Neon Functions sebelum mengakses layanan ini; URL-nya bersifat publik.
• Lewatkan JWT native ke klien JavaScript, Neon Functions, atau API Anda sendiri setiap kali diperlukan.

Lanjutkan dari Getting Started

Jika Anda menggunakan Panduan Memulai untuk merencanakan pekerjaan plugin native, hubungkan dengan Direktori Plugin Capgo untuk alur kerja produk di Direktori Plugin Capgo, Plugin Capacitor oleh Capgo untuk detail implementasi pada Capacitor Plugins oleh Capgo Menambahkan atau Memperbarui Plugin untuk detail implementasi pada Menambahkan atau Memperbarui Plugin, Alternatif Plugin Ionic Enterprise untuk alur kerja produk di alternatif plugin Ionic Enterprise, dan Capgo Native Build untuk alur kerja produk di Capgo Native Builds.