Az app-felülvizsgálat minőségi követelményei

A Stripe minden marketplace-re beküldött appot átfogó minőségi követelmények szerint vizsgál felül. Ha ezeket a fejlesztés előtt megismered, időt takarítasz meg, és kevesebb felülvizsgálati kört kell végigjárnod.

Áttekintés

A Stripe App felülvizsgálata hat kulcsterületen értékeli az appodat:

1. Átlátható árazás, a költségek világos kommunikációja
2. App-funkcionalitás, megbízhatóság és teljesség
3. Fejlesztői elvárások, kódminőség és API-használat
4. UX-minőség, a felhasználói felület és élmény elvárásai
5. Biztonság, adatvédelem és biztonságos gyakorlatok
6. Jogi megfelelés, adatvédelmi és szabályozási követelmények

Átlátható árazás

Az appodnak minden költséget világosan kell közölnie a felhasználókkal:

• Az árazás közlése: minden árat előre fel kell tüntetni a marketplace-listázásban
• Nincsenek rejtett díjak: a felhasználókat nem érheti váratlan díj a telepítés után
• Próbaidőszak feltételei: ha próbaidőszakot kínálsz, add meg egyértelműen az időtartamát és azt, mi történik a végén
• Előfizetés-bővítési folyamatok: minden upsell vagy bővítési felszólítás legyen nem tolakodó és egyértelműen opcionális
• Pénznem: ahol lehet, a felhasználó helyi pénznemében jelenítsd meg az árakat

Dátum- és időformátum

Az appodban megjelenő minden dátumnak és időpontnak követnie kell a Stripe irányítópult konvencióit:

• Ha elérhető, a felhasználó területi beállítása szerint formázd a dátumot
• Az időpontokat a felhasználó helyi időzónájában jelenítsd meg
• A friss eseményekhez használj relatív időbélyeget (például „2 órája”)
• A régebbi eseményekhez használj abszolút időbélyeget, teljes dátummal és időponttal
• Az API felé menő dátummezőknél kövesd az ISO 8601 szabványt

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

App-beállítások

Ha az appod konfigurációt igényel:

• Biztosíts külön beállítási nézetet, amely az app nézetéből elérhető
• Ahol lehet, töltsd ki előre az ésszerű alapértékeket
• Ellenőrizz minden felhasználói bevitelt, és adj világos hibaüzenetet
• Tedd lehetővé a beállítások módosítását az app újratelepítése nélkül
• A beállításokat a Stripe Secret Store API-val őrizd meg a munkamenetek között

Sandbox támogatása

Az appodnak helyesen kell működnie a Stripe sandbox (teszt) módjában:

• Teszt módú működés: minden funkciónak működnie kell teszt módban
• Tesztadatok: életszerű tesztadatokkal mutasd be az app működését
• Éles adat nem kerülhet a sandboxba: soha ne tegyél elérhetővé éles adatot teszt módban
• Kulturált kezelés: ha egy funkció nem érhető el a sandboxban, jelenítsd meg világosan, hogy miért
• Állítsd a sandbox_install_compatible: true értéket a manifesztedben

{
  "sandbox_install_compatible": true
}

App-funkcionalitás

Megbízhatóság

• Az app nem omolhat össze és nem fagyhat le normál használat közben
• Minden meghirdetett funkciónak a leírás szerint kell működnie
• A hálózati hibákat kulturáltan, újrapróbálkozási lehetőséggel kell kezelni
• Az appnak reagálóképesnek kell maradnia a háttérműveletek alatt

Teljesség

• Nincs helykitöltő tartalom, „hamarosan” funkció vagy törött hivatkozás
• Minden felületi elem működjön, ne legyenek halott gombok vagy inaktív vezérlők
• A súgószövegek és a dokumentációs hivatkozások érvényes oldalakra vezessenek
• Az eltávolításnak tisztán el kell takarítania minden app-adatot és webhookot

Teljesítmény

• A felületnek átlagos kapcsolaton 3 másodpercen belül meg kell jelennie
• A háttérben futó szinkronizálás nem blokkolhatja a felületet
• A nagy adathalmazokhoz használj lapozást vagy késleltetett betöltést
• Minimalizáld az API-hívásokat, hogy elkerüld a hívásszám-korlátozást

Fejlesztői elvárások

API-használat

• A Stripe API legfrissebb stabil verzióját használd
• Kövesd a Stripe API bevált gyakorlatait a lapozásra, a hibakezelésre és az idempotenciára
• Ne lépd túl a hívásszám-korlátokat, az újrapróbálkozásokhoz alkalmazz exponenciális visszalépést
• Az eseményvezérelt frissítésekhez webhookokat használj lekérdezgetés helyett

Kódminőség

• Az éles buildekben ne legyen konzolhiba vagy figyelmeztetés
• Beküldés előtt távolíts el minden hibakeresési naplózást
• Kezeld az összes határesetet (üres állapotok, hiányzó adat, hálózati hiba)
• Kövesd a Stripe komponenskönyvtárának mintáit az egységes felületért

Verziózás

• Használj szemantikus verziózást (MAJOR.MINOR.PATCH)
• Dokumentáld a törő változásokat a verziófrissítésekben
• Ahol lehet, tartsd meg a visszafelé kompatibilitást

UX-minőség

Hirdetések

• Nincs reklám: az appod semmilyen hirdetést nem jeleníthet meg
• Nincs keresztpromóció: ne népszerűsíts más terméket vagy szolgáltatást az app felületén
• Márkázott tartalom: csak a saját márkádat jelenítsd meg, harmadik felek márkáit ne (kivéve az integrációs partnereket, például a Brevót)

Nyelv és tartalom

• Egységes nyelvhasználat: az appban végig ugyanazokat a kifejezéseket használd
• Szakmai hangnem: igazodj a Stripe irányítópult szakszerű, tömör kommunikációs stílusához
• Kerüld a szakzsargont: ne használj olyan műszaki kifejezéseket, amelyeket a kereskedők nem értenek
• Helyesírás-ellenőrzés: gondoskodj róla, hogy a szövegben ne legyen helyesírási vagy nyelvtani hiba
• Csak angolul: a marketplace-appok minden felhasználónak szóló szövegének angolul kell lennie

Megerősítő párbeszédablakok

A romboló vagy jelentős hatású műveletekhez kérj felhasználói megerősítést:

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

Megerősítést igénylő műveletek:

• Integrációk lekapcsolása
• Szinkronizált adatok törlése
• Az adatáramlást érintő beállítások módosítása
• A konfiguráció visszaállítása az alapértékekre

Betöltési állapotok

Az aszinkron műveleteknél mindig jelezd a betöltést:

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

Követelmények:

• Adatbetöltés közben mutass forgó jelzőt vagy vázlatképernyőt
• Űrlap beküldése közben tiltsd le a gombokat
• A hosszan futó műveletekhez jelenítsd meg a folyamat állapotát
• Betöltés közben soha ne mutass üres képernyőt

Hibaüzenetek

Adj világos, cselekvésre vezető hibaüzeneteket:

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

Irányelvek a hibaüzenetekhez:

• Magyarázd el közérthetően, mi történt
• Javasolj konkrét lépést, amellyel a felhasználó megoldhatja a problémát
• Adj lehetőséget a sikertelen művelet újrapróbálására
• A részletes hibainformációt naplózd a hibakereséshez (a felhasználónak ne jelenjen meg)
• Ahol értelmezhető, tüntess fel hibakódot a támogatási hivatkozáshoz

Biztonság

Secret Store API

Minden érzékeny adat tárolásához a Stripe Secret Store API-ját használd:

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

Érzékeny adatot soha ne tárolj a következőkben:

• Local storage vagy session storage
• Sütik
• URL-paraméterek
• A forráskódba beégetett értékek
• Egyszerű szöveges konfigurációs fájlok

Kriptográfia

• Nincs saját kriptográfia: ne írj saját titkosítási algoritmust
• Használd a Stripe beépített biztonsági eszközeit (Secret Store, aláírási titkok)
• Minden külső API-híváshoz HTTPS-t használj
• Feldolgozás előtt ellenőrizz minden webhook-aláírást

Adatkezelés

• Csak azokat az engedélyeket kérd, amelyekre az appodnak valóban szüksége van
• Ne tárolj több Stripe-adatot, mint amennyi a működéshez szükséges
• Alkalmazz az adatvédelmi tájékoztatóddal összhangban lévő adatmegőrzési szabályokat
• Biztosíts módot arra, hogy a felhasználók adattörlést kérhessenek

Jogi megfelelés

Adatvédelmi tájékoztató

Az appodnak nyilvánosan elérhető adatvédelmi tájékoztatóval kell rendelkeznie, amely kitér a következőkre:

• Milyen adatot gyűjt az appod a Stripe-ból
• Hogyan tárolod, dolgozod fel és osztod meg az adatot
• Adatmegőrzési és -törlési szabályok
• A felhasználók jogai a saját adataikkal kapcsolatban
• Elérhetőség az adatvédelmi megkeresésekhez
• Az alkalmazandó jogszabályoknak való megfelelés (GDPR, CCPA és így tovább)

Felhasználási feltételek

• Adj közre világos felhasználási feltételeket az appodhoz
• Ne szerepeljenek bennük a Stripe felhasználási feltételeivel ütköző kikötések
• Egyértelműen tüntesd fel a használati korlátozásokat

Szabályozási megfelelés

• Felelj meg minden alkalmazandó adatvédelmi jogszabálynak
• Kösd meg a szükséges adatfeldolgozási megállapodásokat
• Támogasd az adathordozhatósági és törlési kéréseket
• Vezess auditnaplót az adathozzáférésről és -feldolgozásról

A felülvizsgálati folyamat ütemezése

Gyakori elutasítási okok

1. Hiányzó hibakezelés, az app összeomlik hálózati hibánál vagy váratlan adatnál
2. Elégtelen betöltési állapotok, üres képernyők adatlekérés közben
3. Nem egyértelmű árazás, az árazás nincs teljes körűen feltüntetve a listázásban
4. Túl sok engedély, olyan engedélyek kérése, amelyekre az appnak nincs szüksége
5. Nem működő sandbox mód, az app nem működik teszt módban
6. Biztonsági problémák, titkok tárolása a Secret Store API-n kívül
7. Hiányzó adatvédelmi tájékoztató, nincs elérhető adatvédelmi tájékoztató URL
8. Hiányos működés, „hamarosan” funkciók vagy helykitöltő tartalom