Qualitätsanforderungen der App-Überprüfung

Stripe prüft jede im Marketplace eingereichte App anhand eines umfassenden Katalogs von Qualitätsanforderungen. Wenn du diese Standards schon vor der Entwicklung kennst, sparst du Zeit und brauchst weniger Überprüfungsrunden.

Überblick

Die Überprüfung einer Stripe App bewertet deine App in sechs zentralen Bereichen:

1. Transparente Preise, klare Kommunikation der Kosten
2. App-Funktionalität, Zuverlässigkeit und Vollständigkeit
3. Entwicklungsstandards, Codequalität und API-Nutzung
4. UX-Qualität, Standards für Oberfläche und Nutzungserlebnis
5. Sicherheit, Datenschutz und sichere Verfahren
6. Rechtliche Konformität, Datenschutz- und Regulierungsanforderungen

Transparente Preise

Deine App muss alle Kosten eindeutig kommunizieren:

• Preisangabe: Alle Preise müssen im Marketplace-Listing vorab genannt werden
• Keine versteckten Gebühren: Nach der Installation dürfen keine unerwarteten Kosten auftauchen
• Testbedingungen: Wenn du einen Testzeitraum anbietest, nenne klar die Dauer und was danach passiert
• Upgrade-Wege: Hinweise auf Upsells oder Upgrades müssen unaufdringlich und erkennbar freiwillig sein
• Währung: Zeige Preise nach Möglichkeit in der lokalen Währung der Nutzer:innen

Datums- und Zeitformate

Alle Datums- und Zeitangaben in deiner App müssen den Konventionen des Stripe Dashboards folgen:

• Nutze für die Datumsformatierung die Locale der Nutzer:innen, sofern verfügbar
• Zeige Zeiten in der lokalen Zeitzone der Nutzer:innen
• Verwende relative Zeitangaben für aktuelle Ereignisse (z. B. „vor 2 Stunden“)
• Verwende absolute Zeitstempel mit vollständigem Datum und Uhrzeit für ältere Ereignisse
• Halte dich bei allen Datumsfeldern Richtung API an 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"

App-Einstellungen

Wenn deine App konfiguriert werden muss:

• Stelle eine eigene Einstellungsansicht bereit, die aus dem Viewport der App erreichbar ist
• Belege Felder wo möglich mit sinnvollen Standardwerten vor
• Validiere alle Eingaben mit klaren Fehlermeldungen
• Lass Nutzer:innen Einstellungen ändern, ohne die App neu zu installieren
• Speichere Einstellungen sitzungsübergreifend über die Stripe Secret Store API

Sandbox-Unterstützung

Deine App muss im Sandbox-Modus (Testmodus) von Stripe korrekt funktionieren:

• Kompatibilität mit dem Testmodus: Alle Funktionen müssen im Testmodus laufen
• Testdaten: Verwende realistische Testdaten, die die Funktionsweise der App zeigen
• Keine Live-Daten in der Sandbox: Gib im Testmodus niemals Produktionsdaten preis
• Sauberer Umgang mit Lücken: Ist eine Funktion in der Sandbox nicht verfügbar, zeige eine klare Meldung mit der Begründung
• Setze sandbox_install_compatible: true in deinem Manifest

{
  "sandbox_install_compatible": true
}

App-Funktionalität

Zuverlässigkeit

• Die App darf im normalen Betrieb nicht abstürzen oder einfrieren
• Alle beworbenen Funktionen müssen wie beschrieben arbeiten
• Netzwerkfehler müssen sauber abgefangen werden, mit Möglichkeit zur Wiederholung
• Die App muss auch während Hintergrundvorgängen reaktionsfähig bleiben

Vollständigkeit

• Keine Platzhalterinhalte, keine Funktionen mit dem Hinweis „coming soon“, keine toten Links
• Alle UI-Elemente müssen funktionieren, keine wirkungslosen Buttons oder inaktiven Bedienelemente
• Hilfetexte und Doku-Links müssen auf gültige Seiten führen
• Die Deinstallation muss alle App-Daten und Webhooks restlos entfernen

Performance

• Die Oberfläche muss bei üblicher Verbindung innerhalb von 3 Sekunden rendern
• Synchronisierungen im Hintergrund dürfen die Oberfläche nicht blockieren
• Große Datenmengen müssen paginiert oder verzögert geladen werden
• Halte API-Aufrufe gering, um nicht in die Ratenbegrenzung zu laufen

Entwicklungsstandards

API-Nutzung

• Verwende die aktuelle stabile Version der Stripe API
• Folge den Best Practices der Stripe API für Pagination, Fehlerbehandlung und Idempotenz
• Überschreite keine Ratenlimits, nutze exponentielles Backoff für Wiederholungen
• Setze Webhooks für ereignisgesteuerte Aktualisierungen ein statt Polling

Codequalität

• Keine Konsolenfehler oder Warnungen in Produktions-Builds
• Entferne vor der Einreichung alle Debug-Ausgaben
• Behandle alle Randfälle (leere Zustände, fehlende Daten, Netzwerkausfälle)
• Folge den Mustern der Komponentenbibliothek von Stripe für eine einheitliche Oberfläche

Versionierung

• Nutze semantische Versionierung (MAJOR.MINOR.PATCH)
• Dokumentiere Breaking Changes in den Versionsupdates
• Halte die Abwärtskompatibilität, wo es möglich ist

UX-Qualität

Werbung

• Keine Anzeigen: Deine App darf keinerlei Werbung anzeigen
• Keine Cross-Promotion: Bewirb in der App-Oberfläche keine anderen Produkte oder Dienste
• Eigene Marke: Zeige nur deine eigene Markenidentität, nicht die Dritter (mit Ausnahme von Integrationspartnern wie Brevo)

Sprache und Inhalte

• Einheitliche Sprache: Verwende in der gesamten App eine einheitliche Terminologie
• Professioneller Ton: Triff den professionellen, knappen Kommunikationsstil des Stripe Dashboards
• Kein Fachjargon: Vermeide technische Begriffe, die Händler:innen nicht verstehen
• Rechtschreibprüfung: Sorge dafür, dass alle Texte frei von Rechtschreib- und Grammatikfehlern sind
• Nur Englisch: Alle für Nutzer:innen sichtbaren Texte müssen bei Marketplace-Apps auf Englisch sein

Bestätigungsdialoge

Verlange eine Bestätigung bei zerstörenden oder folgenreichen Aktionen:

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

Aktionen, die eine Bestätigung brauchen:

• Integrationen trennen
• Synchronisierte Daten löschen
• Einstellungen ändern, die den Datenfluss betreffen
• Konfiguration auf die Standardwerte zurücksetzen

Ladezustände

Zeige bei asynchronen Vorgängen immer eine Ladeanzeige:

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

Anforderungen:

• Zeige während des Datenladens Spinner oder Skeleton-Ansichten
• Deaktiviere Buttons während des Absendens eines Formulars
• Zeige Fortschrittsanzeigen bei lang laufenden Vorgängen
• Zeige während des Ladens niemals einen leeren Bildschirm

Fehlermeldungen

Formuliere klare, handlungsleitende Fehlermeldungen:

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

Leitlinien für Fehlermeldungen:

• Erkläre in einfacher Sprache, was passiert ist
• Nenne eine konkrete Aktion, mit der sich das Problem lösen lässt
• Biete eine Möglichkeit, den fehlgeschlagenen Vorgang zu wiederholen
• Protokolliere ausführliche Fehlerdetails für die Fehlersuche (ohne sie anzuzeigen)
• Gib, wo sinnvoll, Fehlercodes für Rückfragen beim Support an

Sicherheit

Secret Store API

Nutze die Secret Store API von Stripe für die Ablage aller sensiblen Daten:

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

Sensible Daten gehören niemals in:

• Local Storage oder Session Storage
• Cookies
• URL-Parameter
• Fest einprogrammierte Werte im Quellcode
• Konfigurationsdateien im Klartext

Kryptografie

• Keine eigene Kryptografie: Implementiere keine eigenen Verschlüsselungsverfahren
• Nutze die eingebauten Sicherheitsbausteine von Stripe (Secret Store, Signing Secrets)
• Verwende HTTPS für alle externen API-Aufrufe
• Prüfe alle Webhook-Signaturen, bevor du sie verarbeitest

Umgang mit Daten

• Fordere nur die Berechtigungen an, die deine App wirklich braucht
• Speichere von den Stripe-Daten nur, was für die Funktion nötig ist
• Setze Aufbewahrungsfristen um, die zu deiner Datenschutzerklärung passen
• Biete einen Weg an, über den Nutzer:innen die Löschung ihrer Daten verlangen können

Rechtliche Konformität

Datenschutzerklärung

Deine App braucht eine öffentlich zugängliche Datenschutzerklärung, die Folgendes abdeckt:

• Welche Daten deine App von Stripe erhebt
• Wie die Daten gespeichert, verarbeitet und weitergegeben werden
• Aufbewahrungs- und Löschfristen
• Die Rechte der Nutzer:innen an ihren Daten
• Kontaktdaten für Datenschutzanfragen
• Konformität mit den geltenden Vorschriften (GDPR, CCPA und weitere)

Nutzungsbedingungen

• Stelle klare Nutzungsbedingungen für deine App bereit
• Nimm keine Bedingungen auf, die den Nutzungsbedingungen von Stripe widersprechen
• Nenne Nutzungsgrenzen oder Einschränkungen eindeutig

Regulatorische Konformität

• Halte alle geltenden Datenschutzvorschriften ein
• Setze passende Auftragsverarbeitungsverträge um
• Unterstütze Anfragen zur Datenübertragbarkeit und zur Löschung
• Führe Audit-Logs über Zugriff auf und Verarbeitung von Daten

Zeitplan der Überprüfung

Häufige Ablehnungsgründe

1. Fehlende Fehlerbehandlung, die App stürzt bei Netzwerkfehlern oder unerwarteten Daten ab
2. Unzureichende Ladezustände, leere Bildschirme während des Datenabrufs
3. Unklare Preise, die Preise sind im Listing nicht vollständig offengelegt
4. Zu viele Berechtigungen, angefordert werden Berechtigungen, die die App nicht braucht
5. Defekter Sandbox-Modus, die App funktioniert im Testmodus nicht
6. Sicherheitsprobleme, Secrets werden außerhalb der Secret Store API abgelegt
7. Fehlende Datenschutzerklärung, keine erreichbare URL zur Datenschutzerklärung
8. Unvollständige Funktionalität, Funktionen mit dem Hinweis „coming soon“ oder Platzhalterinhalte