Uygulama Manifesti Referansı
stripe-app.json manifest dosyası, Stripe App’inizin merkezi yapılandırmasıdır. Uygulamanızın kimliğini, izinlerini, arayüz görünümlerini, güvenlik politikalarını ve kurulum sonrası davranışını bildirir.
Eksiksiz manifest örneği
{ "id": "com.tajo.brevo-integration", "version": "1.2.0", "name": "Tajo for Brevo", "icon": "./assets/icon.png", "distribution_type": "public", "sandbox_install_compatible": true, "stripe_api_access_type": "oauth", "allowed_redirect_uris": [ "https://tajo.io/stripe/callback", "https://tajo.io/stripe/oauth/complete" ], "permissions": [ { "permission": "customer_read", "purpose": "Read customer profiles to sync with Brevo contacts" }, { "permission": "customer_write", "purpose": "Update customer metadata with Brevo sync status" }, { "permission": "charge_read", "purpose": "Access payment history for Brevo event tracking" }, { "permission": "product_read", "purpose": "Sync product catalog to Brevo for personalized campaigns" }, { "permission": "event_read", "purpose": "Subscribe to real-time events for Brevo automation triggers" }, { "permission": "invoice_read", "purpose": "Track invoice lifecycle events in Brevo" } ], "ui_extension": { "views": [ { "viewport": "stripe.dashboard.customer.detail", "component": "CustomerDetailView" }, { "viewport": "stripe.dashboard.customer.list", "component": "CustomerListView" }, { "viewport": "stripe.dashboard.home.overview", "component": "OverviewView" }, { "viewport": "stripe.dashboard.drawer.default", "component": "DrawerView" }, { "viewport": "stripe.dashboard.settings", "component": "SettingsView" }, { "viewport": "stripe.dashboard.onboarding", "component": "OnboardingView" } ], "content_security_policy": { "connect-src": [ "https://api.tajo.io", "https://api.brevo.com" ], "image-src": [ "https://cdn.tajo.io", "https://assets.brevo.com" ], "purpose": "Connect to Tajo API for data sync and Brevo API for contact management" } }, "post_install_action": { "type": "onboarding" }, "constants": { "API_BASE_URL": "https://api.tajo.io/v1", "SYNC_INTERVAL_SECONDS": "300" }}Şema referansı
Üst düzey alanlar
| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
id | string | Evet | Ters alan adı gösteriminde benzersiz uygulama tanımlayıcısı (slug biçimi) |
version | string | Evet | Anlamsal sürüm dizesi (örneğin "1.2.0") |
name | string | Evet | Pazar yerinde görünen ad (en fazla 35 karakter) |
icon | string | Evet | Uygulama simgesi dosyasının göreli yolu (300x300 PNG veya SVG) |
distribution_type | string | Evet | Pazar yeri için "public", kurum içi kullanım için "private" |
sandbox_install_compatible | boolean | Hayır | Uygulamanın sandbox veya test modunda kurulabilip kurulamayacağı |
stripe_api_access_type | string | Hayır | API erişim yöntemi: "oauth" veya "api_key" |
allowed_redirect_uris | string[] | Hayır | Kurulum akışı için izin verilen OAuth yönlendirme URI’leri |
permissions | PermissionRequest[] | Evet | İzin isteklerinden oluşan dizi |
ui_extension | UIExtensionManifest | Hayır | Arayüz uzantısı yapılandırması |
post_install_action | PostInstallAction | Hayır | Uygulama kurulduktan sonra yapılacak işlem |
constants | object | Hayır | Uygulamada çalışma zamanında erişilebilen anahtar-değer çiftleri |
id
Uygulama tanımlayıcısı, genellikle ters alan adı gösteriminde yazılan slug biçiminde bir dizedir:
"id": "com.tajo.brevo-integration"- Tüm Stripe Apps genelinde benzersiz olmalıdır
- Yalnızca küçük harf, rakam, kısa çizgi ve nokta kullanın
- Uygulama oluşturulduktan sonra değiştirilemez
- Uygulamanın pazar yerindeki URL’sini belirler
version
Anlamsal sürümlemeye uyar:
"version": "1.2.0"- MAJOR: Geriye dönük uyumsuz değişiklikler veya önemli özellik eklemeleri
- MINOR: Geriye dönük uyumlu yeni özellikler
- PATCH: Hata düzeltmeleri ve küçük iyileştirmeler
- Her yükleme için artırılmalıdır
distribution_type
Uygulamanızı kimlerin kurabileceğini denetler:
| Değer | Açıklama |
|---|---|
"public" | Stripe App Marketplace üzerinden tüm kullanıcılara açıktır |
"private" | Yalnızca kendi Stripe hesabınıza kurulabilir |
stripe_api_access_type
Uygulamanızın Stripe API ile nasıl kimlik doğrulayacağını belirler:
| Değer | Açıklama |
|---|---|
"oauth" | Kimlik doğrulama için OAuth 2.0 akışını kullanır (herkese açık uygulamalar için önerilir) |
"api_key" | Kısıtlı API anahtarlarını kullanır (kurum içi uygulamalar için uygundur) |
PermissionRequest
Her izin isteği, uygulamanızın ihtiyaç duyduğu belirli bir Stripe API iznini bildirir:
{ "permission": "customer_read", "purpose": "Read customer profiles to sync with Brevo contacts"}| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
permission | string | Evet | İzin tanımlayıcısı (bkz. İzinler Referansı) |
purpose | string | Evet | Bu iznin neden gerekli olduğunun okunabilir açıklaması |
Amaç yazma kuralları:
- Satıcıların anlayabileceği açık ve somut açıklamalar yazın
- İznin yalnızca neye yetki verdiğini değil, ne için kullanıldığını anlatın
- Açıklamaları kısa tutun (tek cümle)
- Teknik jargondan kaçının
UIExtensionManifest
Uygulamanızın arayüz bileşenlerini yapılandırır:
{ "ui_extension": { "views": [...], "content_security_policy": {...} }}| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
views | ViewManifest[] | Evet | Görünüm bildirimlerinden oluşan dizi |
content_security_policy | CSPRequest | Hayır | Dış kaynaklar için içerik güvenliği politikası |
ViewManifest
Her görünüm, bir React bileşenini bir Stripe Dashboard görüntü alanına eşler:
{ "viewport": "stripe.dashboard.customer.detail", "component": "CustomerDetailView"}| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
viewport | string | Evet | Bu görünümün işleneceği Dashboard konumu (bkz. Görüntü Alanları Referansı) |
component | string | Evet | İşlenecek React bileşeninin adı (dışa aktarılan bileşen adıyla aynı olmalıdır) |
Tek bir uygulama, farklı görüntü alanları için birden çok görünüm bildirebilir:
"views": [ { "viewport": "stripe.dashboard.customer.detail", "component": "CustomerDetailView" }, { "viewport": "stripe.dashboard.payment.detail", "component": "PaymentDetailView" }, { "viewport": "stripe.dashboard.home.overview", "component": "OverviewView" }]CSPRequest
İçerik güvenliği politikası, uygulamanızın hangi dış alan adlarına bağlanabileceğini denetler:
{ "content_security_policy": { "connect-src": [ "https://api.tajo.io", "https://api.brevo.com" ], "image-src": [ "https://cdn.tajo.io" ], "purpose": "Connect to Tajo API for data sync and load images from CDN" }}| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
connect-src | string[] | Hayır | Uygulamanın ağ isteği gönderebileceği alan adları |
image-src | string[] | Hayır | Uygulamanın görsel yükleyebileceği alan adları |
purpose | string | Evet | Bu dış bağlantıların neden gerektiğinin açıklaması |
Caution
Yalnızca uygulamanızın gerçekten bağlanması gereken alan adlarını ekleyin. Gereğinden fazla CSP girdisi, incelemede ek denetime yol açabilir.
PostInstallAction
Kullanıcı uygulamanızı kurduktan hemen sonra ne olacağını yapılandırır:
{ "post_install_action": { "type": "onboarding" }}| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
type | string | Evet | İşlem türü (aşağıya bakın) |
url | string | Koşullu | external türündeki işlemler için URL |
İşlem türleri
| Tür | Davranış |
|---|---|
"onboarding" | Uygulamanın başlangıç görünümünü Dashboard içinde açar |
"settings" | Uygulamanın ayarlar görünümünü Dashboard içinde açar |
"external" | Kullanıcıyı dış bir URL’ye yönlendirir (url alanı gerekir) |
Örnekler:
// Open onboarding flow{ "post_install_action": { "type": "onboarding" }}
// Open settings page{ "post_install_action": { "type": "settings" }}
// Redirect to external setup{ "post_install_action": { "type": "external", "url": "https://app.tajo.io/stripe/setup" }}Ayrıntılı uygulama desenleri için Kurulum Sonrası İşlemler kılavuzuna bakın.
Sabitler
Uygulamanızda çalışma zamanında erişilebilen statik anahtar-değer çiftleri tanımlayın:
{ "constants": { "API_BASE_URL": "https://api.tajo.io/v1", "SYNC_INTERVAL_SECONDS": "300", "MAX_BATCH_SIZE": "100" }}- Tüm değerler dize olmalıdır
- Sabitler derleme sırasında uygulamaya gömülür
- Ortamdan ortama değişen yapılandırmalar için sabitleri kullanın
- Gizli bilgileri veya API anahtarlarını asla sabit olarak saklamayın, bunun yerine Secret Store API’sini kullanın
Uygulama kodunuzda sabitlere erişin:
import { constants } from '@stripe/ui-extension-sdk/constants';
const apiUrl = constants.API_BASE_URL;Geliştirme için genişletilmiş manifest
Yerel geliştirme sırasında ek alanlar kullanılabilir:
{ "id": "com.tajo.brevo-integration", "version": "0.1.0", "name": "Tajo for Brevo (Dev)", "icon": "./assets/icon-dev.png", "distribution_type": "private", "sandbox_install_compatible": true, "dev": { "hot_reload": true, "port": 4242 }}dev bölümü, üretim derlemeleri ve uygulama yüklemeleri sırasında kaldırılır. Bu bölümü yalnızca yerel geliştirme kolaylığı sağlayan ayarlar için kullanın.
Doğrulama
Manifest dosyanızı yüklemeden önce doğrulayın:
# Validate manifest syntax and schemastripe apps validate
# Check for common issuesstripe apps checkSık karşılaşılan doğrulama hataları:
| Hata | Nedeni | Çözüm |
|---|---|---|
Invalid permission | Bilinmeyen izin tanımlayıcısı | İzinler Referansı sayfasını denetleyin |
Invalid viewport | Bilinmeyen görüntü alanı tanımlayıcısı | Görüntü Alanları Referansı sayfasını denetleyin |
Missing purpose | purpose alanı olmayan izin | Her izne bir purpose dizesi ekleyin |
Invalid version | Anlamsal sürüm biçiminde olmayan sürüm dizesi | MAJOR.MINOR.PATCH biçimini kullanın |
Icon not found | Simge yolu çözümlenemiyor | Simge dosyasının belirtilen yolda bulunduğunu doğrulayın |