Požadavky na kvalitu při kontrole aplikace

Stripe kontroluje každou aplikaci odeslanou na marketplace podle komplexního souboru požadavků na kvalitu. Pochopení těchto standardů ještě před vývojem šetří čas a snižuje počet kol kontroly.

Přehled

Kontrola Stripe App hodnotí Vaši aplikaci v šesti klíčových oblastech:

1. Transparentní ceny, jasná komunikace nákladů
2. Funkčnost aplikace, spolehlivost a úplnost
3. Vývojářské standardy, kvalita kódu a používání API
4. Kvalita UX, standardy uživatelského rozhraní a zážitku
5. Bezpečnost, ochrana dat a bezpečné postupy
6. Právní soulad, ochrana osobních údajů a regulatorní požadavky

Transparentní ceny

Vaše aplikace musí uživatelům jasně sdělit všechny náklady:

• Zveřejnění cen: Všechny ceny musí být uvedeny předem v listingu na marketplace
• Žádné skryté poplatky: Uživatelé nesmí po instalaci narazit na neočekávané poplatky
• Podmínky zkušební verze: Pokud nabízíte zkušební verzi, jasně uveďte její délku a co se stane po jejím skončení
• Toky upgradu: Jakékoli upsell nebo upgrade výzvy musí být nevtíravé a zjevně volitelné
• Měna: Zobrazujte ceny v místní měně uživatele, kdykoli je to možné

Formátování data a času

Všechna data a časy zobrazené ve Vaší aplikaci musí dodržovat konvence Stripe Dashboardu:

• Pro formátování data používejte locale uživatele, je-li k dispozici
• Časy zobrazujte v místním časovém pásmu uživatele
• Pro nedávné události používejte relativní časové údaje (např. „před 2 hodinami”)
• Pro starší události používejte absolutní časové údaje s plným datem a časem
• U všech datových polí směřujících do API dodržujte ISO 8601

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

Nastavení aplikace

Pokud Vaše aplikace vyžaduje konfiguraci:

• Poskytněte vyhrazený pohled s nastavením dostupný z viewportu aplikace
• Kde to jde, předvyplňte rozumné výchozí hodnoty
• Validujte všechny vstupy uživatele s jasnými chybovými hláškami
• Umožněte uživatelům měnit nastavení bez nutnosti aplikaci znovu instalovat
• Uchovávejte nastavení napříč relacemi pomocí Stripe Secret Store API

Podpora sandboxu

Vaše aplikace musí správně fungovat v sandboxovém (testovacím) režimu Stripe:

• Kompatibilita s testovacím režimem: Všechny funkce musí fungovat v testovacím režimu
• Testovací data: Používejte realistická testovací data, která demonstrují funkčnost aplikace
• Žádná ostrá data v sandboxu: Nikdy v testovacím režimu nevystavujte produkční data
• Elegantní ošetření: Pokud některá funkce v sandboxu není dostupná, zobrazte jasnou zprávu s vysvětlením proč
• V manifestu nastavte sandbox_install_compatible: true

{
  "sandbox_install_compatible": true
}

Funkčnost aplikace

Spolehlivost

• Aplikace nesmí při běžném používání spadnout ani zamrznout
• Všechny inzerované funkce musí fungovat tak, jak jsou popsané
• Síťové chyby musí být ošetřeny elegantně, s možností opakování
• Aplikace musí zůstat responzivní i během operací na pozadí

Úplnost

• Žádný zástupný obsah, funkce „již brzy” ani nefunkční odkazy
• Všechny prvky UI musí být funkční, žádná mrtvá tlačítka ani neaktivní ovládací prvky
• Nápověda a odkazy na dokumentaci musí vést na platné stránky
• Odinstalace musí čistě odstranit všechna data aplikace a webhooky

Výkon

• UI se musí vykreslit do 3 sekund na běžném připojení
• Synchronizační operace na pozadí nesmí blokovat UI
• Velké objemy dat musí používat stránkování nebo líné načítání
• Minimalizujte počet volání API, abyste se vyhnuli omezení frekvence

Vývojářské standardy

Používání API

• Používejte nejnovější stabilní verzi Stripe API
• Dodržujte nejlepší postupy Stripe API pro stránkování, ošetření chyb a idempotenci
• Nepřekračujte limity frekvence, pro opakování implementujte exponenciální backoff
• Pro aktualizace řízené událostmi používejte místo dotazování webhooky

Kvalita kódu

• Žádné chyby ani varování v konzoli v produkčních buildech
• Před odesláním odstraňte veškeré ladicí logování
• Ošetřete všechny hraniční případy (prázdné stavy, chybějící data, výpadky sítě)
• Pro konzistentní UI dodržujte vzory knihovny komponent od Stripe

Verzování

• Používejte sémantické verzování (MAJOR.MINOR.PATCH)
• Zdokumentujte nekompatibilní změny ve verzích
• Kde je to možné, zachovejte zpětnou kompatibilitu

Kvalita UX

Reklama

• Žádné reklamy: Vaše aplikace nesmí zobrazovat reklamy jakéhokoli druhu
• Žádná křížová propagace: Nepropagujte v UI aplikace jiné produkty ani služby
• Značkový obsah: Zobrazujte pouze vlastní identitu značky, nikoli značky třetích stran (s výjimkou integračních partnerů, jako je Brevo)

Jazyk a obsah

• Konzistentní jazyk: Používejte v celé aplikaci konzistentní terminologii
• Profesionální tón: Držte se profesionálního a stručného stylu komunikace Stripe Dashboardu
• Žádný žargon: Vyhněte se technickému žargonu, kterému obchodníci nemusí rozumět
• Kontrola pravopisu: Zajistěte, aby všechny texty byly bez pravopisných a gramatických chyb
• Pouze angličtina: Veškerý text viditelný uživateli musí být u aplikací na marketplace v angličtině

Potvrzovací dialogy

U destruktivních nebo významných akcí vyžadujte potvrzení uživatele:

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

Akce, které vyžadují potvrzení:

• Odpojení integrací
• Mazání synchronizovaných dat
• Změny nastavení, která ovlivňují tok dat
• Obnovení konfigurace do výchozího stavu

Stavy načítání

U asynchronních operací vždy zobrazujte indikátory načítání:

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

Požadavky:

• Během načítání dat zobrazujte spinnery nebo skeleton obrazovky
• Během odesílání formuláře deaktivujte tlačítka
• U dlouho běžících operací zobrazujte indikátor průběhu
• Během načítání nikdy nezobrazujte prázdnou obrazovku

Chybové hlášky

Poskytujte jasné chybové hlášky, se kterými lze něco udělat:

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

Pravidla pro chybové hlášky:

• Vysvětlete srozumitelným jazykem, co se stalo
• Navrhněte konkrétní krok, kterým může uživatel problém vyřešit
• Nabídněte způsob, jak neúspěšnou operaci zopakovat
• Zaznamenávejte podrobné informace o chybě pro ladění (uživatelům se nezobrazují)
• Tam, kde to dává smysl, uveďte kód chyby pro potřeby podpory

Bezpečnost

Secret Store API

Pro veškeré ukládání citlivých dat používejte Secret Store API od Stripe:

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

Citlivá data nikdy neukládejte do:

• Local storage ani session storage
• Cookies
• Parametrů URL
• Natvrdo zapsaných hodnot ve zdrojovém kódu
• Konfiguračních souborů v prostém textu

Kryptografie

• Žádná vlastní kryptografie: Neimplementujte vlastní šifrovací algoritmy
• Používejte vestavěné bezpečnostní primitivy Stripe (Secret Store, podpisová tajemství)
• Pro všechna volání externích API používejte HTTPS
• Před zpracováním ověřte všechny podpisy webhooků

Zacházení s daty

• Požadujte pouze oprávnění, která Vaše aplikace skutečně potřebuje
• Neukládejte data ze Stripe nad rámec toho, co je pro funkčnost nezbytné
• Zaveďte pravidla uchovávání dat v souladu se svými zásadami ochrany osobních údajů
• Poskytněte mechanismus, jak si uživatelé mohou vyžádat smazání dat

Právní soulad

Zásady ochrany osobních údajů

Vaše aplikace musí mít veřejně přístupné zásady ochrany osobních údajů, které pokrývají:

• Jaká data Vaše aplikace shromažďuje ze Stripe
• Jak jsou data ukládána, zpracovávána a sdílena
• Pravidla pro uchovávání a mazání dat
• Práva uživatelů týkající se jejich dat
• Kontaktní údaje pro dotazy k ochraně soukromí
• Soulad s platnými předpisy (GDPR, CCPA a další)

Obchodní podmínky

• Poskytněte pro svou aplikaci jasné obchodní podmínky
• Neuvádějte podmínky, které jsou v rozporu s podmínkami Stripe
• Jasně uveďte veškerá omezení použití

Regulatorní soulad

• Dodržujte všechny platné předpisy o ochraně osobních údajů
• Uzavřete odpovídající smlouvy o zpracování osobních údajů
• Podporujte přenositelnost dat a žádosti o jejich smazání
• Veďte auditní záznamy o přístupu k datům a jejich zpracování

Časový harmonogram procesu kontroly

Běžné důvody zamítnutí

1. Chybějící ošetření chyb, aplikace padá při síťových chybách nebo neočekávaných datech
2. Nedostatečné stavy načítání, prázdné obrazovky během načítání dat
3. Nejasné ceny, ceny nejsou v listingu plně zveřejněny
4. Nadměrná oprávnění, požadování oprávnění, která aplikace nepotřebuje
5. Nefunkční sandbox režim, aplikace nefunguje v testovacím režimu
6. Bezpečnostní problémy, ukládání tajemství mimo Secret Store API
7. Chybějící zásady ochrany osobních údajů, žádná dostupná URL se zásadami
8. Neúplná funkčnost, funkce „již brzy” nebo zástupný obsah