Referencia manifestu aplikácie
Súbor manifestu stripe-app.json je centrálnou konfiguráciou Vašej aplikácie Stripe App. Deklaruje identitu aplikácie, oprávnenia, UI pohľady, bezpečnostné politiky a správanie po inštalácii.
Úplný príklad manifestu
{ "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" }}Referencia schémy
Polia najvyššej úrovne
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
id | string | Áno | Jedinečný identifikátor aplikácie v obrátenej doménovej notácii (formát slug) |
version | string | Áno | Reťazec sémantickej verzie (napríklad "1.2.0") |
name | string | Áno | Zobrazovaný názov v marketplace (maximálne 35 znakov) |
icon | string | Áno | Relatívna cesta k súboru s ikonou aplikácie (300x300 PNG alebo SVG) |
distribution_type | string | Áno | "public" pre marketplace alebo "private" pre interné použitie |
sandbox_install_compatible | boolean | Nie | Či sa aplikácia dá nainštalovať v režime sandbox alebo test |
stripe_api_access_type | string | Nie | Spôsob prístupu k API: "oauth" alebo "api_key" |
allowed_redirect_uris | string[] | Nie | Povolené OAuth presmerovacie URI pre inštalačný postup |
permissions | PermissionRequest[] | Áno | Pole požiadaviek na oprávnenia |
ui_extension | UIExtensionManifest | Nie | Konfigurácia rozšírenia používateľského rozhrania |
post_install_action | PostInstallAction | Nie | Akcia, ktorá sa vykoná po inštalácii aplikácie |
constants | object | Nie | Dvojice kľúč a hodnota dostupné v aplikácii za behu |
id
Identifikátor aplikácie je reťazec vo formáte slug, zvyčajne v obrátenej doménovej notácii:
"id": "com.tajo.brevo-integration"- Musí byť globálne jedinečný naprieč všetkými aplikáciami Stripe Apps
- Používajte iba malé písmená, číslice, spojovníky a bodky
- Po vytvorení aplikácie sa už nedá zmeniť
- Určuje URL aplikácie v marketplace
version
Riadi sa sémantickým verzovaním:
"version": "1.2.0"- MAJOR: nekompatibilné zmeny alebo významné rozšírenia funkcií
- MINOR: nové funkcie, spätne kompatibilné
- PATCH: opravy chýb a drobné vylepšenia
- Pri každom nahratí sa musí zvýšiť
distribution_type
Určuje, kto si môže Vašu aplikáciu nainštalovať:
| Hodnota | Popis |
|---|---|
"public" | Dostupná všetkým používateľom v Stripe App Marketplace |
"private" | Nainštalovateľná iba vo Vašom vlastnom účte Stripe |
stripe_api_access_type
Určuje, ako sa Vaša aplikácia autentifikuje voči Stripe API:
| Hodnota | Popis |
|---|---|
"oauth" | Používa postup OAuth 2.0 na autentifikáciu (odporúčané pre verejné aplikácie) |
"api_key" | Používa obmedzené API kľúče (vhodné pre súkromné aplikácie) |
PermissionRequest
Každá požiadavka na oprávnenie deklaruje konkrétne oprávnenie Stripe API, ktoré Vaša aplikácia potrebuje:
{ "permission": "customer_read", "purpose": "Read customer profiles to sync with Brevo contacts"}| Pole | Typ | Povinné | Popis |
|---|---|---|---|
permission | string | Áno | Identifikátor oprávnenia (pozrite Referenciu oprávnení) |
purpose | string | Áno | Ľudsky zrozumiteľné vysvetlenie, prečo je toto oprávnenie potrebné |
Odporúčania pre pole purpose:
- Píšte jasné a konkrétne vysvetlenia, ktorým obchodníci rozumejú
- Vysvetlite, na čo sa oprávnenie používa, nielen čo umožňuje
- Popisy udržujte stručné (jedna veta)
- Vyhnite sa technickému žargónu
UIExtensionManifest
Konfiguruje UI komponenty Vašej aplikácie:
{ "ui_extension": { "views": [...], "content_security_policy": {...} }}| Pole | Typ | Povinné | Popis |
|---|---|---|---|
views | ViewManifest[] | Áno | Pole deklarácií pohľadov |
content_security_policy | CSPRequest | Nie | Content Security Policy pre externé zdroje |
ViewManifest
Každý pohľad mapuje React komponent na viewport v Stripe Dashboarde:
{ "viewport": "stripe.dashboard.customer.detail", "component": "CustomerDetailView"}| Pole | Typ | Povinné | Popis |
|---|---|---|---|
viewport | string | Áno | Miesto v Dashboarde, kde sa tento pohľad vykreslí (pozrite Referenciu viewportov) |
component | string | Áno | Názov React komponentu, ktorý sa má vykresliť (musí zodpovedať názvu exportovaného komponentu) |
Jediná aplikácia môže deklarovať viacero pohľadov pre rôzne viewporty:
"views": [ { "viewport": "stripe.dashboard.customer.detail", "component": "CustomerDetailView" }, { "viewport": "stripe.dashboard.payment.detail", "component": "PaymentDetailView" }, { "viewport": "stripe.dashboard.home.overview", "component": "OverviewView" }]CSPRequest
Content Security Policy určuje, ku ktorým externým doménam sa Vaša aplikácia môže pripájať:
{ "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" }}| Pole | Typ | Povinné | Popis |
|---|---|---|---|
connect-src | string[] | Nie | Domény, na ktoré aplikácia môže posielať sieťové požiadavky |
image-src | string[] | Nie | Domény, z ktorých aplikácia môže načítavať obrázky |
purpose | string | Áno | Vysvetlenie, prečo sú tieto externé spojenia potrebné |
Caution
Uvádzajte iba domény, ku ktorým sa Vaša aplikácia naozaj potrebuje pripájať. Nadmerný počet položiek v CSP môže vyvolať prísnejšiu kontrolu pri posudzovaní.
PostInstallAction
Konfiguruje, čo sa stane hneď po tom, ako si používateľ nainštaluje Vašu aplikáciu:
{ "post_install_action": { "type": "onboarding" }}| Pole | Typ | Povinné | Popis |
|---|---|---|---|
type | string | Áno | Typ akcie (pozrite nižšie) |
url | string | Podmienene | URL pre akcie typu external |
Typy akcií
| Typ | Správanie |
|---|---|
"onboarding" | Otvorí onboardingový pohľad aplikácie v Dashboarde |
"settings" | Otvorí pohľad s nastaveniami aplikácie v Dashboarde |
"external" | Presmeruje používateľa na externú URL (vyžaduje pole url) |
Príklady:
// 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" }}Podrobné implementačné vzory nájdete v príručke k akciám po inštalácii.
Konštanty
Definujte statické dvojice kľúč a hodnota dostupné vo Vašej aplikácii za behu:
{ "constants": { "API_BASE_URL": "https://api.tajo.io/v1", "SYNC_INTERVAL_SECONDS": "300", "MAX_BATCH_SIZE": "100" }}- Všetky hodnoty musia byť reťazce
- Konštanty sa do aplikácie vkladajú pri zostavovaní
- Konštanty používajte na konfiguráciu, ktorá sa líši medzi prostrediami
- Nikdy neukladajte tajomstvá ani API kľúče ako konštanty, namiesto toho použite Secret Store API
Prístup ku konštantám v kóde aplikácie:
import { constants } from '@stripe/ui-extension-sdk/constants';
const apiUrl = constants.API_BASE_URL;Rozšírený manifest pre vývoj
Počas lokálneho vývoja sú dostupné ďalšie polia:
{ "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 }}Sekcia dev sa pri produkčných zostaveniach a nahrávaní aplikácie odstraňuje. Používajte ju iba na pohodlné nastavenia počas lokálneho vývoja.
Validácia
Pred nahratím si manifest overte:
# Validate manifest syntax and schemastripe apps validate
# Check for common issuesstripe apps checkBežné validačné chyby:
| Chyba | Príčina | Riešenie |
|---|---|---|
Invalid permission | Neznámy identifikátor oprávnenia | Skontrolujte Referenciu oprávnení |
Invalid viewport | Neznámy identifikátor viewportu | Skontrolujte Referenciu viewportov |
Missing purpose | Oprávnenie bez poľa purpose | Ku každému oprávneniu doplňte reťazec purpose |
Invalid version | Reťazec verzie, ktorý nie je semver | Použite formát MAJOR.MINOR.PATCH |
Icon not found | Cesta k ikone sa nedá vyhodnotiť | Overte, či súbor s ikonou existuje na zadanej ceste |