Wymagania jakościowe weryfikacji aplikacji

Stripe weryfikuje każdą aplikację zgłoszoną do marketplace według rozbudowanego zestawu wymagań jakościowych. Poznanie tych standardów przed rozpoczęciem prac oszczędza czas i zmniejsza liczbę poprawek w trakcie weryfikacji.

Przegląd

Weryfikacja aplikacji Stripe App ocenia ją w sześciu kluczowych obszarach:

1. Przejrzyste ceny, czyli jasne komunikowanie kosztów
2. Działanie aplikacji, czyli niezawodność i kompletność
3. Standardy programistyczne, czyli jakość kodu i sposób korzystania z API
4. Jakość UX, czyli standardy interfejsu i doświadczenia użytkownika
5. Bezpieczeństwo, czyli ochrona danych i bezpieczne praktyki
6. Zgodność prawna, czyli wymogi dotyczące prywatności i regulacji

Przejrzyste ceny

Twoja aplikacja musi jasno komunikować użytkownikom wszystkie koszty:

• Ujawnienie cen: wszystkie ceny muszą być podane z góry w ofercie w marketplace
• Brak ukrytych opłat: użytkownicy nie mogą natrafić na nieoczekiwane opłaty po instalacji
• Warunki okresu próbnego: jeśli oferujesz okres próbny, jasno podaj jego długość i to, co dzieje się po jego zakończeniu
• Ścieżki zmiany planu: wszelkie komunikaty sprzedażowe i propozycje wyższego planu muszą być nienachalne i wyraźnie opcjonalne
• Waluta: jeśli to możliwe, wyświetlaj ceny w lokalnej walucie użytkownika

Formatowanie daty i godziny

Wszystkie daty i godziny wyświetlane w Twojej aplikacji muszą być zgodne z konwencjami panelu Stripe Dashboard:

• Formatuj daty według ustawień regionalnych użytkownika, jeśli są dostępne
• Wyświetlaj godziny w lokalnej strefie czasowej użytkownika
• Dla niedawnych zdarzeń używaj znaczników względnych (np. “2 godziny temu”)
• Dla starszych zdarzeń używaj znaczników bezwzględnych z pełną datą i godziną
• W polach dat kierowanych do API stosuj 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"

Ustawienia aplikacji

Jeśli Twoja aplikacja wymaga konfiguracji:

• Udostępnij osobny widok ustawień dostępny z poziomu okna aplikacji
• Wszędzie, gdzie to możliwe, ustaw rozsądne wartości domyślne
• Waliduj wszystkie dane wprowadzane przez użytkownika i pokazuj czytelne komunikaty o błędach
• Pozwól użytkownikom zmieniać ustawienia bez ponownej instalacji aplikacji
• Utrwalaj ustawienia między sesjami za pomocą Stripe Secret Store API

Obsługa środowiska sandbox

Twoja aplikacja musi działać poprawnie w trybie sandbox (testowym) Stripe:

• Zgodność z trybem testowym: wszystkie funkcje muszą działać w trybie testowym
• Dane testowe: używaj realistycznych danych testowych, które pokazują możliwości aplikacji
• Żadnych danych produkcyjnych w sandboxie: nigdy nie udostępniaj danych produkcyjnych w trybie testowym
• Kulturalna obsługa braków: jeśli funkcja jest niedostępna w sandboxie, wyświetl czytelny komunikat wyjaśniający dlaczego
• Ustaw sandbox_install_compatible: true w swoim manifeście

{
  "sandbox_install_compatible": true
}

Działanie aplikacji

Niezawodność

• Aplikacja nie może się zawieszać ani przestawać odpowiadać podczas normalnego użycia
• Wszystkie reklamowane funkcje muszą działać zgodnie z opisem
• Błędy sieciowe muszą być obsłużone kulturalnie, z możliwością ponowienia
• Aplikacja musi pozostawać responsywna podczas operacji w tle

Kompletność

• Żadnych treści zastępczych, funkcji “wkrótce” ani niedziałających linków
• Wszystkie elementy interfejsu muszą działać, bez martwych przycisków i nieaktywnych kontrolek
• Teksty pomocy i linki do dokumentacji muszą prowadzić do istniejących stron
• Odinstalowanie musi czysto usuwać wszystkie dane aplikacji i webhooki

Wydajność

• Interfejs musi renderować się w ciągu 3 sekund przy standardowym łączu
• Synchronizacja w tle nie może blokować interfejsu
• Duże zbiory danych muszą korzystać ze stronicowania lub leniwego ładowania
• Ograniczaj liczbę zapytań do API, aby nie przekraczać limitów

Standardy programistyczne

Korzystanie z API

• Używaj najnowszej stabilnej wersji API Stripe
• Stosuj dobre praktyki API Stripe dotyczące stronicowania, obsługi błędów i idempotencji
• Nie przekraczaj limitów zapytań, przy ponowieniach stosuj wykładnicze wycofanie
• Do aktualizacji sterowanych zdarzeniami używaj webhooków zamiast odpytywania

Jakość kodu

• Żadnych błędów i ostrzeżeń w konsoli w buildach produkcyjnych
• Przed zgłoszeniem usuń całe logowanie diagnostyczne
• Obsłuż wszystkie przypadki brzegowe (puste stany, brakujące dane, awarie sieci)
• Stosuj wzorce biblioteki komponentów Stripe, aby interfejs był spójny

Wersjonowanie

• Stosuj wersjonowanie semantyczne (MAJOR.MINOR.PATCH)
• Dokumentuj zmiany łamiące zgodność w opisach aktualizacji
• Tam, gdzie to możliwe, zachowuj wsteczną zgodność

Jakość UX

Reklamy

• Żadnych reklam: Twoja aplikacja nie może wyświetlać reklam w jakiejkolwiek formie
• Żadnej promocji krzyżowej: nie promuj innych produktów ani usług w interfejsie aplikacji
• Treści markowe: prezentuj wyłącznie własną identyfikację wizualną, a nie marki trzecie (poza partnerami integracyjnymi, takimi jak Brevo)

Język i treść

• Spójny język: stosuj spójną terminologię w całej aplikacji
• Profesjonalny ton: dopasuj się do profesjonalnego i zwięzłego stylu komunikacji panelu Stripe Dashboard
• Bez żargonu: unikaj technicznego żargonu, którego sprzedawcy mogą nie rozumieć
• Sprawdzanie pisowni: zadbaj, aby wszystkie teksty były wolne od błędów ortograficznych i gramatycznych
• Tylko po angielsku: w aplikacjach z marketplace cały tekst widoczny dla użytkownika musi być po angielsku

Okna potwierdzenia

Wymagaj potwierdzenia użytkownika przy działaniach destrukcyjnych lub istotnych:

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

Działania wymagające potwierdzenia:

• Rozłączanie integracji
• Usuwanie zsynchronizowanych danych
• Zmiana ustawień wpływających na przepływ danych
• Przywracanie konfiguracji domyślnej

Stany ładowania

Zawsze pokazuj wskaźniki ładowania przy operacjach asynchronicznych:

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

Wymagania:

• Podczas ładowania danych pokazuj spinnery lub szkielety ekranów
• Blokuj przyciski w trakcie wysyłania formularza
• Przy długotrwałych operacjach wyświetlaj wskaźniki postępu
• Nigdy nie pokazuj pustego ekranu podczas ładowania

Komunikaty o błędach

Podawaj jasne komunikaty o błędach, na które można zareagować:

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

Zasady tworzenia komunikatów o błędach:

• Wyjaśnij prostym językiem, co się stało
• Zaproponuj konkretne działanie, które rozwiąże problem
• Daj możliwość ponowienia nieudanej operacji
• Zapisuj szczegółowe informacje o błędzie do celów diagnostycznych (niewidoczne dla użytkownika)
• Tam, gdzie ma to sens, dołączaj kody błędów na potrzeby wsparcia

Bezpieczeństwo

Secret Store API

Do przechowywania wszystkich wrażliwych danych używaj Stripe Secret Store API:

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

Nigdy nie przechowuj wrażliwych danych w:

• Local storage ani session storage
• Plikach cookie
• Parametrach URL
• Wartościach zapisanych na stałe w kodzie źródłowym
• Plikach konfiguracyjnych w postaci zwykłego tekstu

Kryptografia

• Żadnej własnej kryptografii: nie implementuj własnych algorytmów szyfrowania
• Korzystaj z wbudowanych mechanizmów bezpieczeństwa Stripe (Secret Store, sekrety podpisu)
• Wszystkie zewnętrzne wywołania API prowadź przez HTTPS
• Przed przetworzeniem waliduj wszystkie podpisy webhooków

Postępowanie z danymi

• Proś wyłącznie o uprawnienia, których Twoja aplikacja rzeczywiście potrzebuje
• Nie przechowuj danych Stripe wykraczających poza to, co jest niezbędne do działania
• Wdróż zasady retencji danych spójne z Twoją polityką prywatności
• Zapewnij mechanizm, dzięki któremu użytkownicy mogą zażądać usunięcia danych

Zgodność prawna

Polityka prywatności

Twoja aplikacja musi mieć publicznie dostępną politykę prywatności, która obejmuje:

• Jakie dane Twoja aplikacja zbiera ze Stripe
• Jak dane są przechowywane, przetwarzane i udostępniane
• Zasady retencji i usuwania danych
• Prawa użytkowników do ich danych
• Dane kontaktowe w sprawach dotyczących prywatności
• Zgodność z obowiązującymi regulacjami (GDPR, CCPA itp.)

Regulamin

• Udostępnij czytelny regulamin swojej aplikacji
• Nie umieszczaj w nim zapisów sprzecznych z regulaminem Stripe
• Jasno opisz wszelkie ograniczenia korzystania z aplikacji

Zgodność z przepisami

• Przestrzegaj wszystkich obowiązujących przepisów o ochronie danych
• Wdróż odpowiednie umowy powierzenia przetwarzania danych
• Obsługuj żądania przenoszenia i usunięcia danych
• Prowadź logi audytowe dostępu do danych i ich przetwarzania

Harmonogram procesu weryfikacji

Najczęstsze powody odrzucenia

1. Brak obsługi błędów, aplikacja zawiesza się przy błędach sieci lub nieoczekiwanych danych
2. Niewystarczające stany ładowania, puste ekrany podczas pobierania danych
3. Niejasne ceny, ceny nie zostały w pełni ujawnione w ofercie
4. Nadmiarowe uprawnienia, prośba o uprawnienia, których aplikacja nie potrzebuje
5. Niedziałający tryb sandbox, aplikacja nie działa w trybie testowym
6. Problemy z bezpieczeństwem, przechowywanie sekretów poza Secret Store API
7. Brak polityki prywatności, brak dostępnego adresu URL polityki prywatności
8. Niekompletna funkcjonalność, funkcje “wkrótce” lub treści zastępcze