Erken erişim talep edin

Adınızı ve e-posta adresinizi veya telefon numaranızı paylaşın. Tajo erişim ayrıntıları için sizinle iletişime geçeceğiz.

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

AlanTürZorunluAçıklama
idstringEvetTers alan adı gösteriminde benzersiz uygulama tanımlayıcısı (slug biçimi)
versionstringEvetAnlamsal sürüm dizesi (örneğin "1.2.0")
namestringEvetPazar yerinde görünen ad (en fazla 35 karakter)
iconstringEvetUygulama simgesi dosyasının göreli yolu (300x300 PNG veya SVG)
distribution_typestringEvetPazar yeri için "public", kurum içi kullanım için "private"
sandbox_install_compatiblebooleanHayırUygulamanın sandbox veya test modunda kurulabilip kurulamayacağı
stripe_api_access_typestringHayırAPI erişim yöntemi: "oauth" veya "api_key"
allowed_redirect_urisstring[]HayırKurulum akışı için izin verilen OAuth yönlendirme URI’leri
permissionsPermissionRequest[]Evetİzin isteklerinden oluşan dizi
ui_extensionUIExtensionManifestHayırArayüz uzantısı yapılandırması
post_install_actionPostInstallActionHayırUygulama kurulduktan sonra yapılacak işlem
constantsobjectHayırUygulamada ç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ğerAçı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ğerAçı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"
}
AlanTürZorunluAçıklama
permissionstringEvetİzin tanımlayıcısı (bkz. İzinler Referansı)
purposestringEvetBu 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": {...}
}
}
AlanTürZorunluAçıklama
viewsViewManifest[]EvetGörünüm bildirimlerinden oluşan dizi
content_security_policyCSPRequestHayırDış 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"
}
AlanTürZorunluAçıklama
viewportstringEvetBu görünümün işleneceği Dashboard konumu (bkz. Görüntü Alanları Referansı)
componentstringEvetİş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"
}
}
AlanTürZorunluAçıklama
connect-srcstring[]HayırUygulamanın ağ isteği gönderebileceği alan adları
image-srcstring[]HayırUygulamanın görsel yükleyebileceği alan adları
purposestringEvetBu 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"
}
}
AlanTürZorunluAçıklama
typestringEvetİşlem türü (aşağıya bakın)
urlstringKoşulluexternal türündeki işlemler için URL

İşlem türleri

TürDavranış
"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:

Terminal window
# Validate manifest syntax and schema
stripe apps validate
# Check for common issues
stripe apps check

Sık karşılaşılan doğrulama hataları:

HataNedeniÇözüm
Invalid permissionBilinmeyen izin tanımlayıcısıİzinler Referansı sayfasını denetleyin
Invalid viewportBilinmeyen görüntü alanı tanımlayıcısıGörüntü Alanları Referansı sayfasını denetleyin
Missing purposepurpose alanı olmayan izinHer izne bir purpose dizesi ekleyin
Invalid versionAnlamsal sürüm biçiminde olmayan sürüm dizesiMAJOR.MINOR.PATCH biçimini kullanın
Icon not foundSimge yolu çözümlenemiyorSimge dosyasının belirtilen yolda bulunduğunu doğrulayın

Erken erişim talep edin

Adınızı ve e-posta adresinizi veya telefon numaranızı paylaşın. Tajo erişim ayrıntıları için sizinle iletişime geçeceğiz.

otomatik algılama
AI Asistan

Merhaba! Belgeler hakkında her şeyi sorabilirsiniz.