On this page

App Manifest-referens

Manifestfilen stripe-app.json är den centrala konfigurationen för din Stripe App. Den deklarerar din apps identitet, behörigheter, UI-vyer, säkerhetspolicyer och beteende efter installation.

Fullständigt manifestexempel

{
  "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"
  }
}

Schemareferens

Toppnivåfält

Fält	Typ	Obligatorisk	Beskrivning
`id`	sträng	Ja	Unik appidentifierare i omvänt domännotation (slug-format)
`version`	sträng	Ja	Semantisk versionssträng (t.ex. `"1.2.0"`)
`name`	sträng	Ja	Visningsnamn som visas på marketplace (max 35 tecken)
`icon`	sträng	Ja	Relativ sökväg till appikonsfilen (300x300 PNG eller SVG)
`distribution_type`	sträng	Ja	`"public"` för marketplace eller `"private"` för intern användning
`sandbox_install_compatible`	boolean	Nej	Om appen kan installeras i sandbox/testläge
`stripe_api_access_type`	sträng	Nej	API-åtkomstmetod: `"oauth"` eller `"api_key"`
`allowed_redirect_uris`	sträng[]	Nej	Tillåtna OAuth-omdirigeringsadresser för installationsflödet
`permissions`	PermissionRequest[]	Ja	Array med behörighetsbegäranden
`ui_extension`	UIExtensionManifest	Nej	UI-tilläggskonfiguration
`post_install_action`	PostInstallAction	Nej	Åtgärd att vidta efter appinstallation
`constants`	objekt	Nej	Nyckel-värdepar tillgängliga i appen vid körtid

id

Appidentifieraren är en slug-formaterad sträng, vanligtvis i omvänt domännotation:

"id": "com.tajo.brevo-integration"

Måste vara globalt unik för alla Stripe Apps
Använd bara gemener, siffror, bindestreck och punkter
Kan inte ändras efter att appen skapats
Bestämmer appens URL på marketplace

version

Följer semantisk versionshantering:

"version": "1.2.0"

MAJOR: Brytande ändringar eller betydande funktionstillägg
MINOR: Nya funktioner, bakåtkompatibla
PATCH: Buggfixar och mindre förbättringar
Måste ökas för varje uppladdning

distribution_type

Kontrollerar vem som kan installera din app:

Värde	Beskrivning
`"public"`	Tillgänglig på Stripe App Marketplace för alla användare
`"private"`	Kan bara installeras av ditt eget Stripe-konto

stripe_api_access_type

Bestämmer hur din app autentiserar med Stripe API:

Värde	Beskrivning
`"oauth"`	Använder OAuth 2.0-flöde för autentisering (rekommenderat för offentliga appar)
`"api_key"`	Använder begränsade API-nycklar (lämpligt för privata appar)

PermissionRequest

Varje behörighetsbegäran deklarerar en specifik Stripe API-behörighet din app behöver:

{
  "permission": "customer_read",
  "purpose": "Read customer profiles to sync with Brevo contacts"
}

Fält	Typ	Obligatorisk	Beskrivning
`permission`	sträng	Ja	Behörighetsidentifieraren (se Behörighetsreferens)
`purpose`	sträng	Ja	Läsbar förklaring av varför denna behörighet behövs

Riktlinjer för syfte:

Skriv tydliga, specifika förklaringar som säljare kan förstå
Förklara vad behörigheten används till, inte bara vad den beviljar
Håll beskrivningarna kortfattade (en mening)
Undvik teknisk jargong

UIExtensionManifest

Konfigurerar UI-komponenterna i din app:

{
  "ui_extension": {
    "views": [...],
    "content_security_policy": {...}
  }
}

Fält	Typ	Obligatorisk	Beskrivning
`views`	ViewManifest[]	Ja	Array med vydeklarationer
`content_security_policy`	CSPRequest	Nej	Content Security Policy för externa resurser

ViewManifest

Varje vy mappar en React-komponent till en Stripe Dashboard-viewport:

{
  "viewport": "stripe.dashboard.customer.detail",
  "component": "CustomerDetailView"
}

Fält	Typ	Obligatorisk	Beskrivning
`viewport`	sträng	Ja	Dashboard-platsen där den här vyn renderas (se Viewports-referens)
`component`	sträng	Ja	Namn på React-komponenten att rendera (måste matcha det exporterade komponentnamnet)

En enda app kan deklarera flera vyer för olika viewports:

"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 kontrollerar vilka externa domäner din app kan ansluta till:

{
  "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"
  }
}

Fält	Typ	Obligatorisk	Beskrivning
`connect-src`	sträng[]	Nej	Domäner som appen kan göra nätverksbegäranden till
`image-src`	sträng[]	Nej	Domäner som appen kan ladda bilder från
`purpose`	sträng	Ja	Förklaring av varför dessa externa anslutningar behövs

Caution

Inkludera bara domäner som din app faktiskt behöver ansluta till. Överdrivna CSP-poster kan utlösa ytterligare granskningsgranskning.

PostInstallAction

Konfigurerar vad som händer omedelbart efter att en användare installerar din app:

{
  "post_install_action": {
    "type": "onboarding"
  }
}

Fält	Typ	Obligatorisk	Beskrivning
`type`	sträng	Ja	Åtgärdstypen (se nedan)
`url`	sträng	Villkorlig	URL för `external`-typåtgärder

Åtgärdstyper

Typ	Beteende
`"onboarding"`	Öppnar appens onboarding-vy i Dashboard
`"settings"`	Öppnar appens inställningsvy i Dashboard
`"external"`	Omdirigerar användaren till en extern URL (kräver fältet `url`)

Exempel:

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

Se guiden om åtgärder efter installation för detaljerade implementeringsmönster.

Konstanter

Definiera statiska nyckel-värdepar tillgängliga vid körtid i din app:

{
  "constants": {
    "API_BASE_URL": "https://api.tajo.io/v1",
    "SYNC_INTERVAL_SECONDS": "300",
    "MAX_BATCH_SIZE": "100"
  }
}

Alla värden måste vara strängar
Konstanter bäddas in i appen vid byggtid
Använd konstanter för konfiguration som varierar mellan miljöer
Lagra aldrig hemligheter eller API-nycklar som konstanter – använd Secret Store API istället

Åtkomst till konstanter i din appkod:

import { constants } from '@stripe/ui-extension-sdk/constants';

const apiUrl = constants.API_BASE_URL;

Utökat manifest för utveckling

Under lokal utveckling är ytterligare fält tillgängliga:

{
  "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
  }
}

Avsnittet dev tas bort under produktionsbyggen och app-uppladdningar. Använd det bara för inställningar för lokal utvecklingsbekvämlighet.

Validering

Validera ditt manifest innan uppladdning:

# Validate manifest syntax and schema
stripe apps validate

# Check for common issues
stripe apps check

Vanliga valideringsfel:

Fel	Orsak	Åtgärd
`Invalid permission`	Okänd behörighetsidentifierare	Kontrollera Behörighetsreferensen
`Invalid viewport`	Okänd viewport-identifierare	Kontrollera Viewports-referensen
`Missing purpose`	Behörighet utan syfte-fält	Lägg till en syftetext för varje behörighet
`Invalid version`	Icke-semver-versionssträng	Använd formatet `MAJOR.MINOR.PATCH`
`Icon not found`	Ikonsökvägen löser inte	Verifiera att ikonfilen finns på den angivna sökvägen