Uygulama İncelemesi Kalite Gereksinimleri

Stripe, pazar yerine gönderilen her uygulamayı kapsamlı bir kalite gereksinimleri kümesine göre inceler. Bu standartları geliştirmeye başlamadan önce bilmek zaman kazandırır ve inceleme turlarının sayısını azaltır.

Genel bakış

Stripe Uygulaması incelemesi, uygulamanızı altı temel alanda değerlendirir:

1. Şeffaf fiyatlandırma, maliyetlerin açıkça iletilmesi
2. Uygulama işlevselliği, güvenilirlik ve eksiksizlik
3. Geliştirici standartları, kod kalitesi ve API kullanımı
4. UX kalitesi, kullanıcı arayüzü ve deneyim standartları
5. Güvenlik, veri koruma ve güvenli uygulamalar
6. Hukuki uyumluluk, gizlilik ve mevzuat gereksinimleri

Şeffaf fiyatlandırma

Uygulamanız tüm maliyetleri kullanıcılara açıkça bildirmelidir:

• Fiyatlandırmanın açıklanması: Tüm fiyatlandırma, pazar yeri listelemesinde en baştan belirtilmelidir
• Gizli ücret yok: Kullanıcılar kurulumdan sonra beklenmedik ücretlerle karşılaşmamalıdır
• Deneme koşulları: Bir deneme sunuyorsanız süresini ve sona erdiğinde ne olacağını açıkça belirtin
• Yükseltme akışları: Her türlü ek satış veya yükseltme istemi rahatsız edici olmamalı ve açıkça isteğe bağlı olmalıdır
• Para birimi: Mümkün olduğunda fiyatları kullanıcının yerel para biriminde gösterin

Tarih ve saat biçimlendirme

Uygulamanızda gösterilen tüm tarih ve saatler Stripe Dashboard kurallarına uymalıdır:

• Mevcut olduğunda tarih biçimlendirmesi için kullanıcının yerel ayarını kullanın
• Saatleri kullanıcının yerel saat diliminde gösterin
• Yakın zamanlı olaylar için göreli zaman damgaları kullanın (örneğin “2 saat önce”)
• Daha eski olaylar için tam tarih ve saat içeren mutlak zaman damgaları kullanın
• API’ye yönelik tüm tarih alanlarında ISO 8601 standardını izleyin

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

Uygulama ayarları

Uygulamanız yapılandırma gerektiriyorsa:

• Uygulamanın görüntü alanından erişilebilen özel bir Ayarlar görünümü sağlayın
• Mümkün olan yerlerde makul varsayılan değerleri önceden doldurun
• Tüm kullanıcı girişlerini net hata mesajlarıyla doğrulayın
• Kullanıcıların uygulamayı yeniden kurmadan ayarları güncelleyebilmesine izin verin
• Ayarları oturumlar arasında Stripe Secret Store API ile kalıcı hale getirin

Sandbox desteği

Uygulamanız Stripe’ın sandbox (test) modunda doğru çalışmalıdır:

• Test modu uyumluluğu: Tüm özellikler test modunda çalışmalıdır
• Test verisi: Uygulama işlevselliğini gösteren gerçekçi test verileri kullanın
• Sandbox’ta canlı veri yok: Üretim verilerini test modunda asla açığa çıkarmayın
• Nazik davranış: Bir özellik sandbox’ta kullanılamıyorsa nedenini açıklayan net bir mesaj gösterin
• Manifest dosyanızda sandbox_install_compatible: true değerini ayarlayın

{
  "sandbox_install_compatible": true
}

Uygulama işlevselliği

Güvenilirlik

• Uygulama normal kullanım sırasında çökmemeli veya donmamalıdır
• Tanıtılan tüm özellikler açıklandığı gibi çalışmalıdır
• Ağ hataları, yeniden deneme seçenekleriyle nazikçe ele alınmalıdır
• Uygulama, arka plan işlemleri sırasında yanıt vermeye devam etmelidir

Eksiksizlik

• Yer tutucu içerik, “yakında geliyor” özellikleri veya kırık bağlantılar bulunmamalıdır
• Tüm arayüz öğeleri işlevsel olmalıdır, ölü düğme veya pasif denetim olmamalıdır
• Yardım metinleri ve dokümantasyon bağlantıları geçerli sayfalara gitmelidir
• Kaldırma işlemi, uygulamanın tüm verilerini ve webhook’larını temiz biçimde silmelidir

Performans

• Arayüz, standart bir bağlantıda 3 saniye içinde görüntülenmelidir
• Arka plandaki senkronizasyon işlemleri arayüzü bloke etmemelidir
• Büyük veri kümeleri sayfalandırma veya geç yükleme kullanmalıdır
• Hız limitine takılmamak için API çağrılarını en aza indirin

Geliştirici standartları

API kullanımı

• Stripe API’nin en güncel kararlı sürümünü kullanın
• Sayfalandırma, hata yönetimi ve idempotency konusunda Stripe API en iyi uygulamalarını izleyin
• Hız limitlerini aşmayın, yeniden denemeler için üstel geri çekilme uygulayın
• Sürekli sorgulama yerine olay tabanlı güncellemeler için webhook kullanın

Kod kalitesi

• Üretim derlemelerinde konsol hatası veya uyarısı olmamalıdır
• Göndermeden önce tüm hata ayıklama günlüklerini kaldırın
• Tüm uç durumları ele alın (boş durumlar, eksik veri, ağ hataları)
• Tutarlı bir arayüz için Stripe’ın bileşen kütüphanesi örüntülerini izleyin

Sürümleme

• Anlamsal sürümleme (MAJOR.MINOR.PATCH) kullanın
• Sürüm güncellemelerinde geriye dönük uyumsuz değişiklikleri belgeleyin
• Mümkün olan yerlerde geriye dönük uyumluluğu koruyun

UX kalitesi

Reklam

• Reklam yok: Uygulamanız hiçbir türde reklam göstermemelidir
• Çapraz tanıtım yok: Uygulama arayüzü içinde başka ürün veya hizmetleri tanıtmayın
• Markalı içerik: Yalnızca kendi marka kimliğinizi gösterin, üçüncü taraf markaları göstermeyin (Brevo gibi entegrasyon iş ortakları hariç)

Dil ve içerik

• Tutarlı dil: Uygulama boyunca tutarlı terminoloji kullanın
• Profesyonel ton: Stripe Dashboard’un profesyonel ve özlü iletişim tarzıyla uyum sağlayın
• Jargon yok: Satıcıların anlamayabileceği teknik jargondan kaçının
• Yazım denetimi: Tüm metinlerin yazım ve dil bilgisi hatalarından arınmış olduğundan emin olun
• Yalnızca İngilizce: Pazar yeri uygulamalarında kullanıcıya görünen tüm metinler İngilizce olmalıdır

Onay iletişim kutuları

Yıkıcı veya önemli işlemler için kullanıcı onayı isteyin:

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

Onay gerektiren işlemler:

• Entegrasyonların bağlantısını kesme
• Senkronize edilmiş verileri silme
• Veri akışını etkileyen ayarları değiştirme
• Yapılandırmayı varsayılan değerlere sıfırlama

Yükleniyor durumları

Asenkron işlemler için her zaman yükleniyor göstergeleri gösterin:

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

Gereksinimler:

• Veri yüklenirken dönen göstergeler veya iskelet ekranlar gösterin
• Form gönderimi sırasında düğmeleri devre dışı bırakın
• Uzun süren işlemler için ilerleme göstergeleri gösterin
• Yükleme sırasında asla boş bir ekran göstermeyin

Hata mesajları

Net ve eyleme dönüştürülebilir hata mesajları sunun:

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

Hata mesajı ilkeleri:

• Ne olduğunu sade bir dille açıklayın
• Kullanıcının sorunu çözmek için yapabileceği somut bir eylem önerin
• Başarısız olan işlemi yeniden denemenin bir yolunu sunun
• Hata ayıklama için ayrıntılı hata bilgisini günlüğe yazın (kullanıcıya gösterilmez)
• Uygun olduğunda destek başvurusunda kullanılmak üzere hata kodlarını ekleyin

Güvenlik

Secret Store API

Tüm hassas veri depolaması için Stripe’ın Secret Store API’sini kullanın:

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

Hassas verileri asla şuralarda saklamayın:

• Yerel depolama veya oturum depolaması
• Çerezler
• URL parametreleri
• Kaynak kodunda sabit değerler
• Düz metin yapılandırma dosyaları

Kriptografi

• Özel kriptografi yok: Kendi şifreleme algoritmalarınızı geliştirmeyin
• Stripe’ın yerleşik güvenlik yapı taşlarını kullanın (Secret Store, imzalama gizli anahtarları)
• Tüm dış API çağrıları için HTTPS kullanın
• İşlemeden önce tüm webhook imzalarını doğrulayın

Veri işleme

• Yalnızca uygulamanızın gerçekten ihtiyaç duyduğu izinleri isteyin
• İşlevsellik için gerekli olanın ötesinde Stripe verisi saklamayın
• Gizlilik politikanızla uyumlu veri saklama politikaları uygulayın
• Kullanıcıların veri silme talebinde bulunabileceği bir mekanizma sunun

Hukuki uyumluluk

Gizlilik politikası

Uygulamanızın, aşağıdakileri kapsayan herkese açık bir gizlilik politikası olmalıdır:

• Uygulamanızın Stripe’tan hangi verileri topladığı
• Verilerin nasıl saklandığı, işlendiği ve paylaşıldığı
• Veri saklama ve silme politikaları
• Kullanıcıların verileriyle ilgili hakları
• Gizlilik soruları için iletişim bilgileri
• Geçerli mevzuata uyum (GDPR, CCPA vb.)

Hizmet koşulları

• Uygulamanız için net hizmet koşulları sunun
• Stripe’ın Hizmet Koşulları ile çelişen maddeler eklemeyin
• Her türlü kullanım sınırlamasını veya kısıtlamasını açıkça belirtin

Mevzuata uyum

• Geçerli tüm veri koruma mevzuatına uyun
• Uygun veri işleme sözleşmelerini yürürlüğe koyun
• Veri taşınabilirliği ve silme taleplerini destekleyin
• Veri erişimi ve işleme için denetim günlükleri tutun

İnceleme süreci takvimi

Yaygın ret nedenleri

1. Eksik hata yönetimi, uygulamanın ağ hatalarında veya beklenmedik veride çökmesi
2. Yetersiz yükleniyor durumları, veri alınırken boş ekranlar
3. Belirsiz fiyatlandırma, fiyatlandırmanın listelemede tam olarak açıklanmaması
4. Aşırı izin, uygulamanın ihtiyaç duymadığı izinlerin istenmesi
5. Bozuk sandbox modu, uygulamanın test modunda çalışmaması
6. Güvenlik sorunları, gizli anahtarların Secret Store API dışında saklanması
7. Gizlilik politikasının eksikliği, erişilebilir bir gizlilik politikası URL’sinin bulunmaması
8. Eksik işlevsellik, “yakında geliyor” özellikleri veya yer tutucu içerik