---
title: "App-Manifest-Referenz | Tajo"
description: "Vollständige Schema-Referenz für die Manifest-Datei stripe-app.json zur Konfiguration von Stripe Apps"
url: https://tajo.io/de/docs/stripe-apps/app-manifest/
markdown: https://tajo.io/de/docs/stripe-apps/app-manifest.md
lang: de-DE
author: "Set Noa"
author_url: https://tajo.io/de/set-noa/
robots: noindex
---

Beantrage frühzeitigen Zugang

Gib deinen Vornamen und deine geschäftliche E-Mail-Adresse ein. Wir senden dir einen Link, mit dem du deine Anfrage für den Tajo-Zugang bestätigst.

# App-Manifest-Referenz

[Set Noa](https://tajo.io/de/set-noa/)

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.

Caution

**Status: geplant, nicht gebaut.** Tajo hat keine Stripe App, daher lässt sich nichts in diesem Abschnitt heute installieren. Die App-Kennungen, URLs und Zugangsdaten auf dieser Seite sind illustrative Platzhalter, keine echten Endpunkte.

## Vollständiges Manifest-Beispiel

```json
{
  "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": "Read 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.example.com",
        "https://api.brevo.com"
      ],
      "image-src": [
        "https://cdn.example.com",
        "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.example.com/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:

```json
"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:

```json
"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:

```json
{
  "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](https://tajo.io/de/docs/stripe-apps/permissions)) |
| `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:

```json
{
  "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:

```json
{
  "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](https://tajo.io/de/docs/stripe-apps/viewports)) |
| `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:

```json
"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:

```json
{
  "content_security_policy": {
    "connect-src": [
      "https://api.example.com",
      "https://api.brevo.com"
    ],
    "image-src": [
      "https://cdn.example.com"
    ],
    "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:

```json
{
  "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:

```json
// 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](https://tajo.io/de/docs/stripe-apps/post-install).

## Konstanten

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

```json
{
  "constants": {
    "API_BASE_URL": "https://api.example.com/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:

```typescript
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:

```json
{
  "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:

```bash
# 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](https://tajo.io/de/docs/stripe-apps/permissions) |
| `Invalid viewport` | Unbekannte Viewport-Kennung | Prüfe die [Viewport-Referenz](https://tajo.io/de/docs/stripe-apps/viewports) |
| `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 |