Requisiti di qualità per la revisione dell'app

Stripe esamina ogni app inviata al marketplace rispetto a un insieme completo di requisiti di qualità. Conoscere questi standard prima di iniziare lo sviluppo ti fa risparmiare tempo e riduce il numero di cicli di revisione.

Panoramica

La revisione delle Stripe App valuta la tua app su sei aree chiave:

1. Prezzi trasparenti, comunicazione chiara dei costi
2. Funzionalità dell’app, affidabilità e completezza
3. Standard per gli sviluppatori, qualità del codice e uso delle API
4. Qualità della UX, standard di interfaccia ed esperienza d’uso
5. Sicurezza, protezione dei dati e pratiche sicure
6. Conformità legale, requisiti di privacy e normativi

Prezzi trasparenti

La tua app deve comunicare con chiarezza tutti i costi agli utenti:

• Prezzi dichiarati: tutti i prezzi vanno indicati in anticipo nella scheda del marketplace
• Nessun costo nascosto: gli utenti non devono trovarsi addebiti imprevisti dopo l’installazione
• Condizioni della prova: se offri una prova, indica con chiarezza la durata e cosa succede alla fine
• Flussi di upgrade: gli inviti all’upsell o all’upgrade devono essere discreti e chiaramente facoltativi
• Valuta: mostra i prezzi nella valuta locale dell’utente quando è possibile

Formato di date e orari

Tutte le date e gli orari mostrati nella tua app devono seguire le convenzioni della dashboard di Stripe:

• Usa la lingua dell’utente per il formato delle date quando è disponibile
• Mostra gli orari nel fuso orario locale dell’utente
• Usa timestamp relativi per gli eventi recenti (ad esempio “2 hours ago”)
• Usa timestamp assoluti con data e ora complete per gli eventi più vecchi
• Segui lo standard ISO 8601 per tutti i campi data esposti dalle API

// Good: Use Stripe's date formatting utilities
import { formatDate, formatRelativeTime } from '@stripe/ui-extension-sdk/utils';

const formattedDate = formatDate(timestamp); // Locale-aware
const relativeTime = formatRelativeTime(timestamp); // "2 hours ago"

Impostazioni dell’app

Se la tua app richiede una configurazione:

• Offri una vista Impostazioni dedicata, raggiungibile dal viewport dell’app
• Precompila valori predefiniti sensati dove possibile
• Valida tutti gli input dell’utente con messaggi di errore chiari
• Consenti agli utenti di aggiornare le impostazioni senza reinstallare l’app
• Conserva le impostazioni tra una sessione e l’altra usando la Secret Store API di Stripe

Supporto per la sandbox

La tua app deve funzionare correttamente nella modalità sandbox (test) di Stripe:

• Compatibilità con la modalità test: tutte le funzionalità devono funzionare in modalità test
• Dati di test: usa dati di test realistici, che mostrino cosa sa fare l’app
• Nessun dato reale in sandbox: non esporre mai dati di produzione in modalità test
• Gestione elegante: se una funzionalità non è disponibile in sandbox, mostra un messaggio chiaro che ne spieghi il motivo
• Imposta sandbox_install_compatible: true nel tuo manifest

{
  "sandbox_install_compatible": true
}

Funzionalità dell’app

Affidabilità

• L’app non deve andare in crash o bloccarsi durante l’uso normale
• Tutte le funzionalità pubblicizzate devono funzionare come descritto
• Gli errori di rete vanno gestiti con eleganza, con opzioni di nuovo tentativo
• L’app deve restare reattiva durante le operazioni in background

Completezza

• Nessun contenuto segnaposto, nessuna funzionalità “coming soon”, nessun link rotto
• Tutti gli elementi dell’interfaccia devono funzionare, niente pulsanti morti o controlli inattivi
• I testi di aiuto e i link alla documentazione devono portare a pagine valide
• La disinstallazione deve rimuovere in modo pulito tutti i dati e i webhook dell’app

Prestazioni

• L’interfaccia deve caricarsi entro 3 secondi con una connessione normale
• Le sincronizzazioni in background non devono bloccare l’interfaccia
• I grandi insiemi di dati devono usare la paginazione o il caricamento differito
• Riduci al minimo le chiamate API per evitare i limiti di frequenza

Standard per gli sviluppatori

Uso delle API

• Usa l’ultima versione stabile delle API Stripe
• Segui le buone pratiche delle API Stripe per paginazione, gestione degli errori e idempotenza
• Non superare i limiti di frequenza, implementa un backoff esponenziale per i nuovi tentativi
• Usa i webhook per gli aggiornamenti guidati dagli eventi invece del polling

Qualità del codice

• Nessun errore o avviso in console nelle build di produzione
• Rimuovi tutti i log di debug prima dell’invio
• Gestisci tutti i casi limite (stati vuoti, dati mancanti, guasti di rete)
• Segui i pattern della libreria di componenti di Stripe per un’interfaccia coerente

Versionamento

• Usa il versionamento semantico (MAJOR.MINOR.PATCH)
• Documenta le modifiche non retrocompatibili negli aggiornamenti di versione
• Mantieni la retrocompatibilità dove possibile

Qualità della UX

Pubblicità

• Niente pubblicità: la tua app non deve mostrare annunci di alcun tipo
• Niente cross-promotion: non promuovere altri prodotti o servizi dentro l’interfaccia dell’app
• Contenuti di marca: mostra solo la tua identità di marca, non marchi di terzi (a eccezione dei partner di integrazione come Brevo)

Lingua e contenuti

• Terminologia coerente: usa la stessa terminologia in tutta l’app
• Tono professionale: allineati allo stile comunicativo professionale e conciso della dashboard di Stripe
• Niente gergo: evita il gergo tecnico che i merchant potrebbero non capire
• Controllo ortografico: assicurati che i testi non abbiano errori di ortografia o di grammatica
• Solo in inglese: tutti i testi visibili agli utenti devono essere in inglese per le app del marketplace

Finestre di conferma

Richiedi una conferma dell’utente per le azioni distruttive o rilevanti:

// Good: Confirm before destructive actions
const handleDisconnect = async () => {
  const confirmed = await showConfirmation({
    title: 'Disconnect Brevo Integration',
    message: 'This will stop syncing customer data to Brevo. You can reconnect at any time.',
    confirmLabel: 'Disconnect',
    cancelLabel: 'Cancel',
    destructive: true,
  });

  if (confirmed) {
    await disconnectIntegration();
  }
};

Azioni che richiedono conferma:

• Scollegare integrazioni
• Eliminare dati sincronizzati
• Cambiare impostazioni che incidono sul flusso dei dati
• Riportare la configurazione ai valori predefiniti

Stati di caricamento

Mostra sempre un indicatore di caricamento per le operazioni asincrone:

// Good: Show loading state during data fetch
const CustomerSyncStatus = () => {
  const { data, isLoading, error } = useSyncStatus();

  if (isLoading) {
    return <Spinner label="Loading sync status..." />;
  }

  if (error) {
    return <Banner type="critical" title="Failed to load sync status">
      {error.message}
    </Banner>;
  }

  return <SyncStatusDisplay data={data} />;
};

Requisiti:

• Mostra spinner o schermate scheletro durante il caricamento dei dati
• Disattiva i pulsanti durante l’invio dei moduli
• Mostra indicatori di avanzamento per le operazioni lunghe
• Non mostrare mai una schermata vuota durante il caricamento

Messaggi di errore

Fornisci messaggi di errore chiari e utili:

// Bad: Generic error
"Something went wrong"

// Good: Specific and actionable
"Unable to sync customer data to Brevo. Please verify your Brevo API key
in Settings and try again."

Linee guida per i messaggi di errore:

• Spiega cosa è successo con parole semplici
• Suggerisci un’azione concreta che l’utente può fare per risolvere
• Offri un modo per riprovare l’operazione fallita
• Registra informazioni di errore dettagliate per il debug (non mostrate agli utenti)
• Includi codici di errore da citare all’assistenza, quando ha senso

Sicurezza

Secret Store API

Usa la Secret Store API di Stripe per conservare tutti i dati sensibili:

import { createHttpClient, STRIPE_API_KEY } from '@stripe/ui-extension-sdk/http_client';

// Good: Store secrets using the Secret Store API
const storeBrevoApiKey = async (apiKey: string) => {
  const stripe = createHttpClient(STRIPE_API_KEY);
  await stripe.apps.secrets.create({
    name: 'brevo_api_key',
    payload: apiKey,
    scope: { type: 'account' },
  });
};

// Good: Retrieve secrets from the Secret Store
const getBrevoApiKey = async () => {
  const stripe = createHttpClient(STRIPE_API_KEY);
  const secret = await stripe.apps.secrets.find({
    name: 'brevo_api_key',
    scope: { type: 'account' },
  });
  return secret.payload;
};

Non conservare mai dati sensibili in:

• Local storage o session storage
• Cookie
• Parametri dell’URL
• Valori scritti nel codice sorgente
• File di configurazione in chiaro

Crittografia

• Niente crittografia fatta in casa: non implementare algoritmi di cifratura tuoi
• Usa le primitive di sicurezza integrate di Stripe (Secret Store, signing secret)
• Usa HTTPS per tutte le chiamate ad API esterne
• Verifica tutte le firme dei webhook prima di elaborarli

Trattamento dei dati

• Richiedi solo i permessi che la tua app usa davvero
• Non conservare dati Stripe oltre a quanto serve al funzionamento
• Applica politiche di conservazione dei dati coerenti con la tua informativa sulla privacy
• Offri un modo per richiedere la cancellazione dei dati

Conformità legale

Informativa sulla privacy

La tua app deve avere un’informativa sulla privacy accessibile pubblicamente, che copra:

• Quali dati la tua app raccoglie da Stripe
• Come i dati vengono conservati, elaborati e condivisi
• Le politiche di conservazione e cancellazione dei dati
• I diritti degli utenti sui propri dati
• I contatti per le richieste sulla privacy
• La conformità alle normative applicabili (GDPR, CCPA e altre)

Termini di servizio

• Fornisci termini di servizio chiari per la tua app
• Non inserire condizioni in conflitto con i Termini di servizio di Stripe
• Dichiara con chiarezza eventuali limiti o restrizioni d’uso

Conformità normativa

• Rispetta tutte le normative applicabili sulla protezione dei dati
• Predisponi accordi di trattamento dei dati adeguati
• Supporta le richieste di portabilità e di cancellazione dei dati
• Conserva log di audit sugli accessi e sul trattamento dei dati

Tempi del processo di revisione

Motivi di rifiuto più comuni

1. Gestione degli errori assente, l’app va in crash con errori di rete o dati imprevisti
2. Stati di caricamento insufficienti, schermate vuote durante il recupero dei dati
3. Prezzi poco chiari, prezzi non dichiarati per intero nella scheda
4. Permessi eccessivi, richiesta di permessi che l’app non usa
5. Modalità sandbox non funzionante, l’app non funziona in modalità test
6. Problemi di sicurezza, segreti conservati fuori dalla Secret Store API
7. Informativa sulla privacy mancante, nessun URL raggiungibile dell’informativa
8. Funzionalità incomplete, funzioni “coming soon” o contenuti segnaposto