Prise en main

Installer

Vous pouvez utiliser notre configuration assistée par IA pour installer le plugin. Ajoutez les skills Capgo à votre outil d'IA avec la commande suivante :

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

Utilisez ensuite le prompt suivant :

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

Si vous préférez une installation manuelle, installez le plugin en exécutant les commandes suivantes et suivez les instructions spécifiques à chaque plateforme ci-dessous :

bun add @capgo/capacitor-neon
bunx cap sync

Neon Setup

1. Activer Neon Auth sur votre branche (Console > Auth, ou neon neon-auth enable).
2. Activer le Données API sur la même branche si vous voulez les helpers de base de données (Console > Data API, avec Neon Auth comme fournisseur).
3. Copiez le Auth URL et URL de Data API depuis la Console.

Neon Auth n’accepte que les requêtes provenant d’origines de confiance. Localhost est approuvé par défaut, et le plugin envoie Origin: https://localhost, pour qu’une nouvelle branche fonctionne sans modification. Si vous désactivez localhost, ajoutez l’un de vos domaines en tant que domaine de confiance et passez-l’en paramètre origin vers initialize().

Configuration iOS

Aucune configuration supplémentaire n'est requise pour l'authentification par e-mail et OTP. Le plugin utilise URLSession et le Keychain, sans aucune dépendance tierce.

Pour OAuth, configurez redirectTo à un partenaire de confiance https Universal Link de confiance qui ouvre votre application. Neon Auth rejette les URL schemes personnalisés comme redirectTo. Si vous utilisez un scheme personnalisé dans l'application, hébergez une page de callback HTTPS de confiance qui transmet le neon_auth_session_verifier paramètre de requête à ce scheme.

Configuration Android

Aucune configuration supplémentaire n'est requise pour l'authentification par e-mail et OTP. Le plugin fonctionne avec le Capacitor 8 et la SDK minimale par défaut de 24 (Android 7.0).

Pour OAuth, configurez redirectTo à un partenaire de confiance https App Link qui ouvre votre app. Neon Auth rejette les URL schemes personnalisés comme redirectTo. Si vous utilisez un scheme personnalisé dans l'application, hébergez une page de callback HTTPS de confiance qui transmet le neon_auth_session_verifier paramètre de requête à ce scheme.

Erreurs courantes

• Écouteurs: supprimez les handles lors du démontage des écrans.
• Initialiser une seule fois: exécutez le setup lors du bootstrap de l'app.
• redirections OAuth : Neon Auth n'accepte que les https URLs pour redirectTo (en clair http uniquement pour les tests locaux sur un localhost de confiance). Les schémas d’URL personnalisés sont rejetés. Utilisez un Universal Link ou un App Link, ou une page HTTPS de confiance qui transmet le neon_auth_session_verifier paramètre de requête au schéma d’URL de votre application.
• Source de vérité : fiez-vous src/definitions.ts au repo GitHub.

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

Se connecter et accéder au 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));

S'inscrire

Si Vérifier l’e-mail lors de l’inscription est activé pour votre branche, signUp() returns no session until the user confirms the emailed 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',
  });
}

Écouter les changements d'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.

Associer l'auth native à neon-js

Installez le client JavaScript lorsque vous utilisez ce modèle :

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

Helpers de base de données 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);
}

Lorsqu’aucun utilisateur n’est connecté, les helpers de base de données utilisent un token Data API anonyme, de sorte que les politiques de sécurité au niveau des lignes pour anonymous rôle s’appliquent.

Usage recommandé

• Utilisez ce plugin pour l'authentification et la gestion de session.
• Gardez les requêtes avancées dans @neondatabase/neon-js.
• Conservez Stockage d'objets et Passerelle IA les appels dans une fonction Neon ou votre propre API. Les deux utilisent des identifiants de branche qui doivent rester hors du bundle de l’application. Authentifiez les requêtes vers les fonctions Neon avant d’accéder à ces services ; leurs URL sont publiques.
• Transmettez le JWT natif au client JavaScript, aux fonctions Neon ou à votre propre API chaque fois que nécessaire.

Continuer depuis Getting Started

Si vous utilisez Prise en main pour planifier le travail sur les plugins natifs, connectez-l’à Capgo Répertoire des plugins pour le workflow produit dans Capgo Plugin Directory, Plugins Capacitor par Capgo pour les détails d'implémentation dans Plugins Capacitor par Capgo, Ajouter ou mettre à jour des plugins pour les détails d'implémentation dans Adding or Updating Plugins, Alternatives aux plugins Ionic Enterprise pour le workflow produit dans les alternatives aux plugins Ionic Enterprise, et Capgo Native Build pour le workflow produit dans Capgo Native Builds.