Beantrage frühzeitigen Zugang

Gib deinen Vornamen und eine E-Mail-Adresse oder Telefonnummer an. Wir melden uns mit den Details zum Tajo-Zugang bei dir.

Auf dieser Seite

App-Manifest-Referenz

Die Manifest-Datei stripe-app.json ist die zentrale Konfiguration deiner Stripe App. Sie deklariert die Identität deiner App, ihre Berechtigungen, UI-Ansichten, Sicherheitsrichtlinien und das Verhalten nach der Installation.

Vollständiges Manifest-Beispiel

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

Felder auf oberster Ebene

Feld	Typ	Erforderlich	Beschreibung
`id`	string	Ja	Eindeutige App-Kennung in umgekehrter Domain-Notation (Slug-Format)
`version`	string	Ja	Semantische Versionsangabe (z. B. `"1.2.0"`)
`name`	string	Ja	Anzeigename im Marketplace (max. 35 Zeichen)
`icon`	string	Ja	Relativer Pfad zur Icon-Datei der App (300x300 PNG oder SVG)
`distribution_type`	string	Ja	`"public"` für den Marketplace oder `"private"` für interne Nutzung
`sandbox_install_compatible`	boolean	Nein	Ob die App im Sandbox- oder Testmodus installiert werden kann
`stripe_api_access_type`	string	Nein	Zugriffsmethode für die API: `"oauth"` oder `"api_key"`
`allowed_redirect_uris`	string[]	Nein	Erlaubte OAuth-Redirect-URIs für den Installationsablauf
`permissions`	PermissionRequest[]	Ja	Array mit Berechtigungsanfragen
`ui_extension`	UIExtensionManifest	Nein	Konfiguration der UI-Erweiterung
`post_install_action`	PostInstallAction	Nein	Aktion, die nach der Installation der App ausgeführt wird
`constants`	object	Nein	Schlüssel-Wert-Paare, die zur Laufzeit in der App verfügbar sind

id

Die App-Kennung ist eine Zeichenkette im Slug-Format, üblicherweise in umgekehrter Domain-Notation:

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

Muss über alle Stripe Apps hinweg global eindeutig sein
Verwende ausschließlich Kleinbuchstaben, Ziffern, Bindestriche und Punkte
Kann nach dem Anlegen der App nicht mehr geändert werden
Bestimmt die URL der App im Marketplace

version

Folgt der semantischen Versionierung:

"version": "1.2.0"

MAJOR: Breaking Changes oder größere neue Funktionen
MINOR: Neue Funktionen, abwärtskompatibel
PATCH: Fehlerbehebungen und kleinere Verbesserungen
Muss bei jedem Upload erhöht werden

distribution_type

Steuert, wer deine App installieren kann:

Wert	Beschreibung
`"public"`	Im Stripe App Marketplace für alle Nutzer:innen verfügbar
`"private"`	Nur über dein eigenes Stripe-Konto installierbar

stripe_api_access_type

Legt fest, wie sich deine App gegenüber der Stripe API authentifiziert:

Wert	Beschreibung
`"oauth"`	Nutzt den OAuth-2.0-Ablauf zur Authentifizierung (empfohlen für öffentliche Apps)
`"api_key"`	Nutzt eingeschränkte API-Schlüssel (geeignet für private Apps)

PermissionRequest

Jede Berechtigungsanfrage deklariert eine bestimmte Berechtigung der Stripe API, die deine App benötigt:

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

Feld	Typ	Erforderlich	Beschreibung
`permission`	string	Ja	Die Kennung der Berechtigung (siehe Berechtigungsreferenz)
`purpose`	string	Ja	Verständliche Erklärung, warum diese Berechtigung nötig ist

Leitlinien für den Zweck:

Schreibe klare, konkrete Erklärungen, die Händler:innen verstehen
Erkläre, wofür die Berechtigung genutzt wird, nicht nur, was sie erlaubt
Halte die Beschreibungen knapp (ein Satz)
Vermeide Fachjargon

UIExtensionManifest

Konfiguriert die UI-Komponenten deiner App:

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

Feld	Typ	Erforderlich	Beschreibung
`views`	ViewManifest[]	Ja	Array mit Ansichtsdeklarationen
`content_security_policy`	CSPRequest	Nein	Content Security Policy für externe Ressourcen

ViewManifest

Jede Ansicht ordnet eine React-Komponente einem Viewport im Stripe Dashboard zu:

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

Feld	Typ	Erforderlich	Beschreibung
`viewport`	string	Ja	Der Ort im Dashboard, an dem diese Ansicht gerendert wird (siehe Viewport-Referenz)
`component`	string	Ja	Name der React-Komponente, die gerendert wird (muss dem Namen der exportierten Komponente entsprechen)

Eine einzelne App kann mehrere Ansichten für verschiedene Viewports deklarieren:

"views": [
  {
    "viewport": "stripe.dashboard.customer.detail",
    "component": "CustomerDetailView"
  },
  {
    "viewport": "stripe.dashboard.payment.detail",
    "component": "PaymentDetailView"
  },
  {
    "viewport": "stripe.dashboard.home.overview",
    "component": "OverviewView"
  }
]

CSPRequest

Die Content Security Policy steuert, mit welchen externen Domains deine App eine Verbindung aufbauen darf:

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

Feld	Typ	Erforderlich	Beschreibung
`connect-src`	string[]	Nein	Domains, an die die App Netzwerkanfragen senden darf
`image-src`	string[]	Nein	Domains, von denen die App Bilder laden darf
`purpose`	string	Ja	Erklärung, warum diese externen Verbindungen nötig sind

Caution

Nimm nur Domains auf, zu denen deine App tatsächlich eine Verbindung braucht. Zu viele CSP-Einträge können eine genauere Prüfung auslösen.

PostInstallAction

Konfiguriert, was unmittelbar nach der Installation deiner App passiert:

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

Feld	Typ	Erforderlich	Beschreibung
`type`	string	Ja	Der Aktionstyp (siehe unten)
`url`	string	Bedingt	URL für Aktionen vom Typ `external`

Aktionstypen

Typ	Verhalten
`"onboarding"`	Öffnet die Onboarding-Ansicht der App im Dashboard
`"settings"`	Öffnet die Einstellungsansicht der App im Dashboard
`"external"`	Leitet die Nutzer:innen zu einer externen URL weiter (benötigt das Feld `url`)

Beispiele:

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

Ausführliche Umsetzungsmuster findest du im Leitfaden zu Post-Install-Aktionen.

Konstanten

Lege statische Schlüssel-Wert-Paare fest, die zur Laufzeit in deiner App verfügbar sind:

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

Alle Werte müssen Strings sein
Konstanten werden beim Build in die App eingebettet
Nutze Konstanten für Konfiguration, die sich zwischen Umgebungen unterscheidet
Speichere niemals Geheimnisse oder API-Schlüssel als Konstanten, nutze stattdessen die Secret Store API

So greifst du im Code deiner App auf Konstanten zu:

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

const apiUrl = constants.API_BASE_URL;

Erweitertes Manifest für die Entwicklung

Während der lokalen Entwicklung stehen zusätzliche Felder zur Verfügung:

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

Der Abschnitt dev wird bei Produktions-Builds und beim Upload der App entfernt. Nutze ihn nur für Komfort-Einstellungen der lokalen Entwicklung.

Validierung

Validiere dein Manifest vor dem Upload:

# Validate manifest syntax and schema
stripe apps validate

# Check for common issues
stripe apps check

Häufige Validierungsfehler:

Fehler	Ursache	Lösung
`Invalid permission`	Unbekannte Kennung einer Berechtigung	Prüfe die Berechtigungsreferenz
`Invalid viewport`	Unbekannte Viewport-Kennung	Prüfe die Viewport-Referenz
`Missing purpose`	Berechtigung ohne Feld `purpose`	Ergänze für jede Berechtigung einen Zweck als String
`Invalid version`	Versionsangabe ohne Semver-Format	Verwende das Format `MAJOR.MINOR.PATCH`
`Icon not found`	Der Icon-Pfad lässt sich nicht auflösen	Prüfe, ob die Icon-Datei unter dem angegebenen Pfad existiert