Vai al contenuto principale

​
Panoramica

Il boilerplate Astro minimale fornisce un punto di partenza pronto all’uso per integrare Dodo Payments con la tua applicazione Astro. Questo template include sessioni di checkout, gestione dei webhook, portale clienti e componenti UI moderni per aiutarti ad accettare pagamenti rapidamente.
Questo boilerplate utilizza Astro 5 con TypeScript, Tailwind CSS 4 e l’adapter @dodopayments/astro.

​
Caratteristiche

  • Impostazione Rapida - Inizia in meno di 5 minuti
  • Integrazione dei Pagamenti - Flusso di checkout preconfigurato utilizzando @dodopayments/astro
  • UI Moderna - Pagina di pricing pulita e a tema scuro con Tailwind CSS
  • Gestore Webhook - Endpoint webhook pronto all’uso per eventi di pagamento
  • Portale Clienti - Gestione degli abbonamenti con un clic
  • TypeScript - Completamente tipizzato con tipi minimi e focalizzati
  • Checkout Precompilato - Dimostra come passare i dati del cliente per migliorare l’esperienza utente

​
Requisiti

Prima di iniziare, assicurati di avere:
  • Versione LTS di Node.js (richiesta per Astro 5)
  • Account Dodo Payments (per accedere alle chiavi API e Webhook dal dashboard)

​
Avvio Rapido

1

Clona il Repository

git clone https://github.com/dodopayments/dodo-astro-minimal-boilerplate.git
cd dodo-astro-minimal-boilerplate
2

Installa le Dipendenze

npm install
3

Ottieni le Credenziali API

Registrati su Dodo Payments e ottieni le tue credenziali dal dashboard:
Assicurati di essere in Modalità Test mentre sviluppi!
4

Configura le Variabili d'Ambiente

Crea un file .env nella directory principale:
cp .env.example .env
Aggiorna i valori con le tue credenziali Dodo Payments:
DODO_PAYMENTS_API_KEY=your_api_key_here
DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_signing_key_here
DODO_PAYMENTS_RETURN_URL=http://localhost:4321/
DODO_PAYMENTS_ENVIRONMENT=test_mode
Non impegnare mai il tuo file .env nel controllo di versione. È già incluso in .gitignore.
5

Aggiungi i Tuoi Prodotti

Aggiorna src/lib/products.ts con i tuoi ID prodotto reali da Dodo Payments:
export const products: Product[] = [
  {
    product_id: "pdt_001", // Replace with your product ID
    name: "Basic Plan",
    description: "Get access to basic features and support",
    price: 9999, // in cents
    features: [
      "Access to basic features",
      "Email support",
      "1 Team member",
      "Basic analytics",
    ],
  },
  // ... add more products
];
6

Esegui il Server di Sviluppo

npm run dev
Apri http://localhost:4321 per vedere la tua pagina di pricing!

​
Struttura del Progetto

src/
├── components/
│   ├── Footer.astro           # Reusable footer
│   ├── Header.astro           # Navigation header
│   └── ProductCard.astro      # Product pricing card
├── layouts/
│   └── Layout.astro           # Root layout
├── lib/
│   └── products.ts            # Product definitions
├── pages/
│   ├── index.astro            # Pricing page (home)
│   └── api/
│       ├── checkout.ts        # Checkout session handler
│       ├── customer-portal.ts # Customer portal redirect
│       └── webhook.ts         # Webhook event handler
└── styles/
    └── global.css             # Global styles with Tailwind

​
Personalizzazione

​
Aggiorna le Informazioni sul Prodotto

Modifica src/lib/products.ts per modificare:
  • ID prodotto (dal tuo dashboard Dodo)
  • Prezzi
  • Caratteristiche
  • Descrizioni

​
Pre-compila i Dati del Cliente

In src/components/ProductCard.astro, sostituisci i valori hardcoded con i tuoi dati utente reali: 
customer: {
  name: "John Doe",
  email: "[email protected]",
},

​
Aggiorna il Portale Clienti

In src/components/Header.astro, sostituisci l’ID cliente hardcoded con l’ID cliente reale dal tuo sistema di autenticazione o database: 
const CUSTOMER_ID = "cus_001"; // Replace with actual customer ID
Puoi completare un acquisto di prova per ottenere l’ID cliente per il testing.

​
Eventi Webhook

Il boilerplate dimostra la gestione degli eventi webhook in src/pages/api/webhook.ts:
  • onSubscriptionActive - Attivato quando un abbonamento diventa attivo
  • onSubscriptionCancelled - Attivato quando un abbonamento viene annullato
Aggiungi la tua logica aziendale all’interno di questi gestori: 
onSubscriptionActive: async (payload) => {
  // Grant access to your product
  // Update user database
  // Send welcome email
},
Aggiungi ulteriori eventi webhook se necessario. Per lo sviluppo locale, puoi utilizzare strumenti come ngrok per creare un tunnel sicuro al tuo server locale e usarlo come URL del tuo webhook.

​
Distribuzione

Questo boilerplate utilizza output statico con rendering on-demand per le rotte API. Dovrai installare un adapter per la tua piattaforma di distribuzione:
PiattaformaGuida
VercelDistribuisci su Vercel
NetlifyDistribuisci su Netlify
CloudflareDistribuisci su Cloudflare
Consulta le guide alla distribuzione di Astro per tutte le piattaforme.

​
Aggiorna l’URL del Webhook

Dopo la distribuzione, aggiorna il tuo URL del webhook nel Dashboard di Dodo Payments: 
https://your-domain.com/api/webhook
Ricorda anche di aggiornare la variabile d’ambiente DODO_PAYMENTS_WEBHOOK_KEY nel tuo ambiente di produzione per corrispondere alla chiave di firma del webhook per il tuo dominio distribuito.

​
Risoluzione dei Problemi

Elimina node_modules e reinstalla le dipendenze:
rm -rf node_modules package-lock.json
npm install
Cause comuni:
  • ID prodotto non valido - verifica che esista nel tuo dashboard Dodo
  • Chiave API errata o impostazione dell’ambiente in .env
  • Controlla la console del browser e il terminale per errori
Per il testing locale, utilizza ngrok per esporre il tuo server:
ngrok http 4321
Aggiorna l’URL del webhook nel tuo dashboard Dodo all’URL di ngrok. Ricorda di aggiornare il tuo file .env con la chiave di verifica del webhook corretta.
Questo boilerplate utilizza output statico con rotte API on-demand. Devi installare un adapter per la distribuzione:Consulta le guide alla distribuzione di Astro per dettagli.

​
Scopri di Più

​
Supporto

Hai bisogno di aiuto con il boilerplate?