Cerințe de calitate pentru evaluarea aplicației

Stripe evaluează fiecare aplicație trimisă în marketplace pe baza unui set cuprinzător de cerințe de calitate. Dacă înțelegi aceste standarde înainte de dezvoltare, economisești timp și reduci numărul de iterații de evaluare.

Prezentare generală

Evaluarea aplicațiilor Stripe îți analizează aplicația în șase domenii principale:

1. Prețuri transparente, comunicarea clară a costurilor
2. Funcționalitatea aplicației, fiabilitate și completitudine
3. Standarde pentru dezvoltatori, calitatea codului și utilizarea API-ului
4. Calitatea UX, standarde pentru interfață și experiența utilizatorului
5. Securitate, protecția datelor și practici sigure
6. Conformitate legală, cerințe de confidențialitate și reglementare

Prețuri transparente

Aplicația ta trebuie să comunice clar utilizatorilor toate costurile:

• Comunicarea prețurilor: toate prețurile trebuie prezentate din start în anunțul din marketplace
• Fără taxe ascunse: utilizatorii nu trebuie să întâmpine costuri neașteptate după instalare
• Condițiile perioadei de probă: dacă oferi o perioadă de probă, precizează clar durata și ce se întâmplă după încheierea ei
• Fluxuri de upgrade: orice mesaj de upsell sau de upgrade trebuie să fie discret și clar opțional
• Moneda: afișează prețurile în moneda locală a utilizatorului atunci când este posibil

Formatarea datei și a orei

Toate datele și orele afișate în aplicația ta trebuie să respecte convențiile din panoul de administrare Stripe:

• Folosește localizarea utilizatorului pentru formatarea datelor atunci când este disponibilă
• Afișează orele în fusul orar local al utilizatorului
• Folosește marcaje de timp relative pentru evenimentele recente (de exemplu „acum 2 ore”)
• Folosește marcaje de timp absolute pentru evenimentele mai vechi, cu dată și oră complete
• Respectă ISO 8601 pentru orice câmp de dată expus prin 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"

Setările aplicației

Dacă aplicația ta are nevoie de configurare:

• Oferă o vizualizare dedicată pentru setări, accesibilă din fereastra aplicației
• Precompletează valori implicite rezonabile acolo unde este posibil
• Validează toate datele introduse de utilizator și afișează mesaje de eroare clare
• Permite utilizatorilor să își actualizeze setările fără să reinstaleze aplicația
• Păstrează setările între sesiuni folosind API-ul Stripe Secret Store

Suport pentru sandbox

Aplicația ta trebuie să funcționeze corect în modul sandbox (test) al Stripe:

• Compatibilitate cu modul de test: toate funcționalitățile trebuie să funcționeze în modul de test
• Date de test: folosește date de test realiste, care demonstrează funcționarea aplicației
• Fără date reale în sandbox: nu expune niciodată date de producție în modul de test
• Tratare elegantă: dacă o funcționalitate nu este disponibilă în sandbox, afișează un mesaj clar care explică de ce
• Setează sandbox_install_compatible: true în manifest

{
  "sandbox_install_compatible": true
}

Funcționalitatea aplicației

Fiabilitate

• Aplicația nu trebuie să se blocheze sau să se oprească din funcționare în timpul utilizării normale
• Toate funcționalitățile promovate trebuie să funcționeze conform descrierii
• Erorile de rețea trebuie tratate elegant, cu opțiuni de reîncercare
• Aplicația trebuie să rămână receptivă în timpul operațiunilor din fundal

Completitudine

• Fără conținut de tip substituent, funcționalități „în curând” sau linkuri nefuncționale
• Toate elementele de interfață trebuie să fie funcționale, fără butoane inactive sau comenzi inerte
• Textele de ajutor și linkurile către documentație trebuie să ducă la pagini valide
• Dezinstalarea trebuie să elimine complet toate datele și webhookurile aplicației

Performanță

• Interfața trebuie să se afișeze în maximum 3 secunde pe o conexiune obișnuită
• Operațiunile de sincronizare din fundal nu trebuie să blocheze interfața
• Seturile mari de date trebuie să folosească paginare sau încărcare leneșă
• Redu numărul de apeluri API pentru a evita limitarea ratei

Standarde pentru dezvoltatori

Utilizarea API-ului

• Folosește cea mai recentă versiune stabilă a API-ului Stripe
• Respectă bunele practici ale API-ului Stripe pentru paginare, tratarea erorilor și idempotență
• Nu depăși limitele de rată, implementează backoff exponențial pentru reîncercări
• Folosește webhookuri pentru actualizări bazate pe evenimente, în loc de interogare repetată

Calitatea codului

• Fără erori sau avertismente în consolă în build-urile de producție
• Elimină toate jurnalele de depanare înainte de trimitere
• Tratează toate cazurile limită (stări goale, date lipsă, erori de rețea)
• Respectă tiparele bibliotecii de componente Stripe pentru o interfață consecventă

Versionare

• Folosește versionare semantică (MAJOR.MINOR.PATCH)
• Documentează modificările incompatibile în actualizările de versiune
• Menține compatibilitatea retroactivă acolo unde este posibil

Calitatea UX

Publicitate

• Fără reclame: aplicația ta nu trebuie să afișeze niciun fel de reclame
• Fără promovare încrucișată: nu promova alte produse sau servicii în interfața aplicației
• Conținut de brand: afișează doar identitatea propriului brand, nu branduri terțe (cu excepția partenerilor de integrare, precum Brevo)

Limbaj și conținut

• Terminologie consecventă: folosește aceiași termeni în toată aplicația
• Ton profesionist: potrivește-te stilului profesionist și concis de comunicare din panoul de administrare Stripe
• Fără jargon: evită jargonul tehnic pe care comercianții s-ar putea să nu îl înțeleagă
• Verificare ortografică: asigură-te că textele nu conțin greșeli de ortografie sau de gramatică
• Doar în engleză: pentru aplicațiile din marketplace, tot textul vizibil utilizatorilor trebuie să fie în engleză

Dialoguri de confirmare

Cere confirmarea utilizatorului pentru acțiunile distructive sau importante:

// 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();
  }
};

Acțiuni care necesită confirmare:

• Deconectarea integrărilor
• Ștergerea datelor sincronizate
• Modificarea setărilor care afectează fluxul de date
• Resetarea configurației la valorile implicite

Stări de încărcare

Afișează întotdeauna indicatori de încărcare pentru operațiunile 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} />;
};

Cerințe:

• Afișează indicatoare rotative sau ecrane schelet în timpul încărcării datelor
• Dezactivează butoanele în timpul trimiterii formularelor
• Afișează indicatoare de progres pentru operațiunile de lungă durată
• Nu afișa niciodată un ecran gol în timpul încărcării

Mesaje de eroare

Oferă mesaje de eroare clare și utile:

// 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."

Reguli pentru mesajele de eroare:

• Explică ce s-a întâmplat, în limbaj simplu
• Sugerează o acțiune concretă prin care utilizatorul poate rezolva problema
• Oferă o modalitate de a reîncerca operațiunea eșuată
• Înregistrează informații detaliate despre eroare pentru depanare (fără să le arăți utilizatorilor)
• Include coduri de eroare pentru referință în relația cu suportul, atunci când este cazul

Securitate

API-ul Secret Store

Folosește API-ul Stripe Secret Store pentru stocarea tuturor datelor sensibile:

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

Nu stoca niciodată date sensibile în:

• Local storage sau session storage
• Cookieuri
• Parametri de URL
• Valori scrise direct în codul sursă
• Fișiere de configurare în text simplu

Criptografie

• Fără criptografie proprie: nu implementa propriii algoritmi de criptare
• Folosește primitivele de securitate integrate ale Stripe (Secret Store, secrete de semnare)
• Folosește HTTPS pentru toate apelurile către API-uri externe
• Validează toate semnăturile webhook înainte de procesare

Manipularea datelor

• Cere doar permisiunile de care aplicația ta chiar are nevoie
• Nu stoca date Stripe dincolo de ce este necesar pentru funcționare
• Implementează politici de păstrare a datelor aliniate cu politica ta de confidențialitate
• Oferă un mecanism prin care utilizatorii pot cere ștergerea datelor

Conformitate legală

Politica de confidențialitate

Aplicația ta trebuie să aibă o politică de confidențialitate accesibilă public, care să acopere:

• Ce date colectează aplicația ta din Stripe
• Cum sunt stocate, procesate și partajate datele
• Politicile de păstrare și de ștergere a datelor
• Drepturile utilizatorilor cu privire la datele lor
• Datele de contact pentru întrebări legate de confidențialitate
• Conformitatea cu reglementările aplicabile (GDPR, CCPA etc.)

Termeni și condiții

• Oferă termeni și condiții clari pentru aplicația ta
• Nu include clauze care intră în conflict cu Termenii și condițiile Stripe
• Precizează clar orice limitări sau restricții de utilizare

Conformitate cu reglementările

• Respectă toate reglementările aplicabile privind protecția datelor
• Implementează acorduri adecvate de prelucrare a datelor
• Acceptă cererile de portabilitate și de ștergere a datelor
• Păstrează jurnale de audit pentru accesul la date și pentru prelucrarea lor

Durata procesului de evaluare

Motive frecvente de respingere

1. Tratarea insuficientă a erorilor, aplicația se blochează la erori de rețea sau la date neașteptate
2. Stări de încărcare insuficiente, ecrane goale în timpul încărcării datelor
3. Prețuri neclare, prețurile nu sunt prezentate complet în anunț
4. Permisiuni excesive, sunt cerute permisiuni de care aplicația nu are nevoie
5. Mod sandbox nefuncțional, aplicația nu funcționează în modul de test
6. Probleme de securitate, secretele sunt stocate în afara API-ului Secret Store
7. Politică de confidențialitate lipsă, nu există un URL accesibil pentru politica de confidențialitate
8. Funcționalitate incompletă, funcționalități „în curând” sau conținut de tip substituent