Referenz für das App-Manifest

Informationen zum App-Manifest, ein Index mit allen Feldern, Typen und Beschreibungen für Ihre App-Manifest-Datei.

Das Anwendungsmanifest beschreibt, wie Anwendungen in die Stripe-Plattform integriert werden. Jede Stripe-App benötigt eine stripe-app.json-Manifestdatei, die sich im Stamm der Projektverzeichnisstruktur befindet.

Das App-Manifest können Sie mithilfe der CLI von Stripe-Apps oder auch direkt bearbeiten. So können Sie mit dem Befehl stripe apps grant permission beispielsweise eine Berechtigung hinzufügen oder aber eine permissionRequest direkt in das App-Manifest aufnehmen.

Anwendungsmanifestdateien folgen immer einem bestimmten Schema, das auf dieser Seite beschrieben wird.

Beispiel

stripe-app.json
{
  "id": "com.invoicing.[YOUR_APP]",
  "version": "1.2.3",
  "name": "[YOUR APP] Shipment Invoicing",
  "icon": "./[YOUR_APP]_icon_32.png",
  "distribution_type": "public",
  "permissions": [
    {
      "permission": "invoice_write",
      "purpose": "Allows [YOUR APP] to add shipping line items to an invoice."
    },
    {
      "permission": "product_read",
      "purpose": "Allows [YOUR APP] to use product sizes for calculating shipping."
    }
  ],
  "ui_extension": {
    "views": [
      {
        "viewport": "stripe.dashboard.invoice.detail",
        "component": "AddShipping"
      }
    ],
    "content_security_policy": {
      "connect-src": [
        "https://api.example.com/a_specific_endpoint",
        "https://api.example.com/a_whole_subdirectory/"
      ],
      "image-src": [
        "https://images.example.com/one_image.jpg",
        "https://images.example.com/a_whole_subdirectory/"
      ],
      "purpose": "These URLs allow the app to contact [YOUR APP] for creating shipping details and loading images of shipping partner logos"
    }
  },
  "post_install_action": {
    "type": "external",
    "url": "https://example.com"
  },
  "constants": {
    "API_BASE": "https://api.example.com"
  }
}

Schema

Bei Anwendungsmanifestdateien handelt es sich stets um JSON-Dateien mit den Feldern:

Name des Felds	Typ	Beispiele
ID	slug	com.invoicing.myapp
Eine von Ihnen definierte, global eindeutige Kennung für die App. Stripe validiert diese nach der ersten Übermittlung.
Version	Zeichenfolge	1.2.4
Eine von Ihnen festgelegte App-Version, für deren Bezeichnung Sie ein beliebiges Format wählen können.
Name	Zeichenfolge	Meine App
Der Name, der in der Nutzeroberfläche wird, wenn auf Ihre App verwiesen wird. Öffentlich vertriebene Apps sollten nicht die Wörter „Stripe“, „App“, „kostenlos“ oder „kostenpflichtig“ enthalten.
Symbol	Zeichenfolge	./favicon.png
Der relative Pfad innerhalb des App-Pakets zu einem 300x300 Pixel großen PNG-Icon, das neben der Zuordnung angezeigt werden soll.
distribution_type	„öffentlich“ \| „privat“	„öffentlich“
Der Verteilungstyp der App.
stripe_api_access_type	„Plattform“ \| „oauth“ \| „restricted_api_key“	oauth
Die API-Authentifizierungsmethode Ihrer App.
allowed_redirect_uris	Array<String>	none
Die URLs, auf die Nutzer/innen nach der Installation Ihrer App mit OAuth oder mit einem Installationslink umgeleitet werden.
Berechtigungen	Array<PermissionRequest>	none
Die für das Funktionieren der App erforderlichen Berechtigungen.
ui_extension	UIExtensionManifest	none
Spezielle Konfiguration für die Funktion „UI Extension”.
post_install_action	PostInstallAction	none
Eine optionale Konfiguration, um Nutzer/innen nach der Installation einer App an einen benutzerdefinierten Standort weiterzuleiten.
Konstanten	Objekt	`{"API_BASE": "https://api.example.com/v1"}`
Ein Objekt mit willkürlichen konstanten Werten, auf das Sie in den Kontexteigenschaften der Nutzeroberflächenerweiterung zugreifen für die lokale Entwicklung mit dem CLI-Manifest-Flag außer Kraft setzen können.

PermissionRequest

Berechtigungsanfragen enthalten die folgenden Felder:

Name des Felds	Typ	Beispiel
Berechtigung	Zeichenfolge	customer_write
Berechtigungen, die die App anfordert. Erfahren Sie mehr über Berechtigungen.
Zweck	Zeichenfolge \| Map<locale, string>	„Diese App lädt Bilder von images.example.com.“
Ein Hinweis für die Nutzer/innen, mit dem während der Installation über den Zweck der erforderlichen Berechtigungen informiert wird.
Name	Zeichenfolge	“Wird von [YOUR APP] benötigt, um Rechnungen anhand der ausgewählten Versandkosten anzupassen.”
Ein Hinweis für Stripe, mit dem bei der App-Prüfung über den Zweck der erforderlichen Berechtigungen informiert wird.

UiExtensionManifest

Manifeste zu Erweiterungen der Nutzeroberfläche weisen stets diese Felder auf:

Name des Felds	Typ	Beispiel
Ansichten	Array<ViewManifest>	none
React-Komponenten, die an einer bestimmten Stelle im Dashboard angezeigt werden. Mehr erfahren.
content_security_policy	CSPRequest	none
Anfrage Ihrer Benutzeroberflächenerweiterung auf Zugang zu bestimmten URLs für einen bestimmten Zweck.

ViewManifest

Ansichtsmanifeste enthalten diese Felder:

Name des Felds	Typ	Beispiel
Darstellungsfeld	Zeichenfolge	stripe.dashboard.invoice.detail
Eine Kennung, die angibt, wo eine Erweiterung der Nutzeroberfläche im Dashboard angezeigt werden kann. Siehe die Liste der verfügbaren Darstellungsbereiche.
Komponente	Zeichenfolge	AddShippingSelector
Eine exportierte React-Komponente, die eine unserer Ansichtskomponenten nutzt.

CSPRequest

Anfragen zu Content-Sicherheitsrichtlinien weisen diese Felder auf:

Name des Felds	Typ	Beispiel
connect-src	Array<string>	https://o0.ingest.sentry.io/api/
URLs zulässiger Drittanbieter-APIs. Endet die URL mit einem Schrägstrich, erhalten auch alle untergeordneten URLs die Berechtigung. Siehe auch Nutzung von Drittanbieter-APIs.
image-src	Array<string>	https://images.example.com/
URLs the Img component can load from. If the URL ends in a slash, all of its children also receive permission.
Zweck	Zeichenfolge \| Map<locale, string>	„Diese App lädt Bilder von https://images.example.com und sendet für die Fehlerbehebung anonyme Fehlerberichte an unseren Partner Sentry.“
Eine Erklärung, die Nutzer/innen nach Installation der App angezeigt wird und erläutert, warum das Plugin mit diesen URLs direkt kommunizieren muss.

URLs müssen die CSP-Anforderungen erfüllen. Zulässig sind ausschließlich HTTPS-Schemata.

PostInstallAction

Eine Aktion nach der Installation umfasst die folgenden Felder:

Name des Felds	Typ	Beispiel
Typ	Zeichenfolge	`external`, `settings`
Zusätzliche Aktion, nachdem Nutzer/innen Ihre App auf dem Stripe-Dashboard installiert haben. Weitere Informationen finden Sie unter Konfiguration nach der Installation aktivieren.
url	Zeichenfolge	https://example.com
Externe URL, an die Nutzer/innen nach der Installation Ihrer App weitergeleitet werden. Dies ist nur erforderlich, wenn der Aktionstyp nach der Installation `external` ist.

Verwenden Sie eine erweiterte Manifest-Datei für die Entwicklung

Während der lokalen Entwicklung müssen Sie möglicherweise andere App-Manifestwerte verwenden, als in der Produktion. Das Backend Ihrer App könnte sich beispielsweise unter https://api.example.com/v1 befinden, Ihr lokales Entwicklungs-Backend wird jedoch unter http://localhost:8888/v1 ausgeführt.

Folgendes Beispiel für eine Manifest-Datei:

stripe-app.json
{
  "id": "com.invoicing.[YOUR_APP]",
  "version": "1.2.3",
  "name": "[YOUR APP] Shipment Invoicing",
  "icon": "./[YOUR_APP]_icon_32.png",
  "permissions": [],
  "ui_extension": {
    "views": [
      {
        "viewport": "stripe.dashboard.invoice.detail",
        "component": "InvoiceDetail"
      }
    ],
    "content_security_policy": {
      "connect-src": ["https://api.example.com/v1"],
      "purpose": "Allow the app to retrieve example data"
    }
  },
  "constants": {
    "API_BASE": "https://api.example.com/v1"
  }
}

Erstellen Sie eine weitere Manifestdatei mit dem Namen stripe-app.[anything].json, die Ihr Hauptmanifest erweitert und mit lokalen Werten überschreibt. Zum Beispiel:

stripe-app.dev.json
{
  "extends": "stripe-app.json",
  "ui_extension": {
    "content_security_policy": {
      "connect-src": ["http://localhost:8888/v1"]
    }
  },
  "constants": {
    "API_BASE": "http://localhost:8888/v1"
  }
}

Um die lokale Manifestdatei während der Entwicklung zu verwenden, laden Sie sie mit dem Flag --manifest. Zum Beispiel:

Command Line
stripe apps start --manifest stripe-app.dev.json

Greifen Sie mithilfe von Kontext-Props auf die constants-Werte in Ihren Ansichten zu. Zum Beispiel:

import {useEffect, useState} from 'react';
import type {ExtensionContextValue} from '@stripe/ui-extension-sdk/context';
import {Box} from '@stripe/ui-extension-sdk/ui';

const InvoiceDetail = ({environment}: ExtensionContextValue) => {
  const [data, setData] = useState(null);

  useEffect(() => {
    fetch(`${environment.constants.API_BASE}/some-endpoint`)
      .then(response => response.json())
      .then(json => setData(json));
  }, []);

  return data ? <Box>Here is your message: {data.message}</Box> : 'Loading...';
};