App Manifest Reference
stripe-app.json-manifestfilen er den centrale konfiguration for din Stripe App. Den deklarerer din apps identitet, tilladelser, UI-visninger, sikkerhedspolitikker og post-installationsadfærd.
Fuldt manifest-eksempel
{ "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" }}Schema-reference
Felter på øverste niveau
| Felt | Type | Påkrævet | Beskrivelse |
|---|---|---|---|
id | string | Ja | Unikt app-id i omvendt domæne-notation (slug-format) |
version | string | Ja | Semantisk versionstreng (f.eks. "1.2.0") |
name | string | Ja | Visningsnavn vist på marketplace (maks. 35 tegn) |
icon | string | Ja | Relativ sti til app-ikonfilen (300x300 PNG eller SVG) |
distribution_type | string | Ja | "public" til marketplace eller "private" til intern brug |
sandbox_install_compatible | boolean | Nej | Om appen kan installeres i sandbox/testmodus |
stripe_api_access_type | string | Nej | API-adgangsmetode: "oauth" eller "api_key" |
allowed_redirect_uris | string[] | Nej | Tilladte OAuth-redirect-URI’er til installationsflow |
permissions | PermissionRequest[] | Ja | Array af tilladelsesanmodninger |
ui_extension | UIExtensionManifest | Nej | UI-udvidelseskonfiguration |
post_install_action | PostInstallAction | Nej | Handling der udføres efter app-installation |
constants | object | Nej | Nøgle-værdi-par tilgængelige i appen ved kørselstid |
id
App-id’et er en slug-formateret streng, typisk i omvendt domæne-notation:
"id": "com.tajo.brevo-integration"- Skal være globalt unikt på tværs af alle Stripe Apps
- Brug kun små bogstaver, tal, bindestreger og punktummer
- Kan ikke ændres efter appen er oprettet
- Bestemmer appens URL på marketplace
version
Følger semantisk versionering:
"version": "1.2.0"- MAJOR: Brydende ændringer eller betydelige funktionstilføjelser
- MINOR: Nye funktioner, bagudkompatibelt
- PATCH: Fejlrettelser og mindre forbedringer
- Skal øges for hvert upload
distribution_type
Styrer hvem der kan installere din app:
| Værdi | Beskrivelse |
|---|---|
"public" | Tilgængelig på Stripe App Marketplace for alle brugere |
"private" | Kan kun installeres af din egen Stripe-konto |
stripe_api_access_type
Bestemmer hvordan din app godkender sig med Stripe API:
| Værdi | Beskrivelse |
|---|---|
"oauth" | Bruger OAuth 2.0-flow til godkendelse (anbefalet til offentlige apps) |
"api_key" | Bruger begrænsede API-nøgler (egnet til private apps) |
PermissionRequest
Hver tilladelsesanmodning deklarerer en specifik Stripe API-tilladelse din app behøver:
{ "permission": "customer_read", "purpose": "Read customer profiles to sync with Brevo contacts"}| Felt | Type | Påkrævet | Beskrivelse |
|---|---|---|---|
permission | string | Ja | Tilladelsesidentifikatoren (se Tilladelsesreference) |
purpose | string | Ja | Menneskelig læsbar forklaring af hvorfor denne tilladelse er nødvendig |
Retningslinjer for formål:
- Skriv klare, specifikke forklaringer som sælgere kan forstå
- Forklar hvad tilladelsen bruges til, ikke bare hvad den giver
- Hold beskrivelser korte (én sætning)
- Undgå teknisk jargon
UIExtensionManifest
Konfigurerer UI-komponenterne i din app:
{ "ui_extension": { "views": [...], "content_security_policy": {...} }}| Felt | Type | Påkrævet | Beskrivelse |
|---|---|---|---|
views | ViewManifest[] | Ja | Array af visningsdeklarationer |
content_security_policy | CSPRequest | Nej | Content Security Policy til eksterne ressourcer |
ViewManifest
Hver visning mapper en React-komponent til en Stripe Dashboard-viewport:
{ "viewport": "stripe.dashboard.customer.detail", "component": "CustomerDetailView"}| Felt | Type | Påkrævet | Beskrivelse |
|---|---|---|---|
viewport | string | Ja | Dashboard-placeringen hvor denne visning gengives (se Viewportreference) |
component | string | Ja | Navn på React-komponenten der gengives (skal matche det eksporterede komponentnavn) |
CSPRequest
Content Security Policy styrer hvilke eksterne domæner din app kan forbinde til:
{ "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" }}| Felt | Type | Påkrævet | Beskrivelse |
|---|---|---|---|
connect-src | string[] | Nej | Domæner appen kan lave netværksanmodninger til |
image-src | string[] | Nej | Domæner appen kan indlæse billeder fra |
purpose | string | Ja | Forklaring af hvorfor disse eksterne forbindelser er nødvendige |
Caution
Inkluder kun domæner som din app faktisk behøver at forbinde til. Overdrevne CSP-indgange kan udløse yderligere gennemgangskontrol.
PostInstallAction
Konfigurerer hvad der sker umiddelbart efter en bruger installerer din app:
{ "post_install_action": { "type": "onboarding" }}| Felt | Type | Påkrævet | Beskrivelse |
|---|---|---|---|
type | string | Ja | Handlingstypen (se nedenfor) |
url | string | Betinget | URL til external type handlinger |
Handlingstyper
| Type | Adfærd |
|---|---|
"onboarding" | Åbner appens onboarding-visning i Dashboard |
"settings" | Åbner appens indstillingsvisning i Dashboard |
"external" | Omdirigerer brugeren til en ekstern URL (kræver url-felt) |
Se Post-installationshandlingsguiden for detaljerede implementeringsmønstre.
Konstanter
Definer statiske nøgle-værdi-par tilgængelige ved kørselstid i din app:
{ "constants": { "API_BASE_URL": "https://api.tajo.io/v1", "SYNC_INTERVAL_SECONDS": "300", "MAX_BATCH_SIZE": "100" }}- Alle værdier skal være strenge
- Konstanter er indlejret i appen ved byggetid
- Brug konstanter til konfiguration der varierer mellem miljøer
- Gem aldrig hemmeligheder eller API-nøgler som konstanter, brug Secret Store API i stedet
Validering
Valider dit manifest før upload:
# Valider manifest-syntaks og schemastripe apps validate
# Kontroller for almindelige problemerstripe apps checkAlmindelige valideringsfejl:
| Fejl | Årsag | Løsning |
|---|---|---|
Invalid permission | Ukendt tilladelsesidentifikator | Kontroller Tilladelsesreference |
Invalid viewport | Ukendt viewport-identifikator | Kontroller Viewportreference |
Missing purpose | Tilladelse uden formål-felt | Tilføj en formål-streng til hver tilladelse |
Invalid version | Ikke-semver versionstreng | Brug formatet MAJOR.MINOR.PATCH |
Icon not found | Ikonsti løser ikke op | Verificer at ikonfilen eksisterer ved den angivne sti |