Weiter zum Inhalt
Konto erstellen
oder
anmelden
Das Logo der Stripe-Dokumentation
/
KI fragen
Konto erstellen
Anmelden
Jetzt starten
Zahlungen
Finanzautomatisierung
Plattformen und Marktplätze
Geldmanagement
Entwickler-Tools
Jetzt starten
Zahlungen
Finanzautomatisierung
Jetzt starten
Zahlungen
Finanzautomatisierung
Plattformen und Marktplätze
Geldmanagement
Übersicht
Versionierung
Änderungsprotokoll
Aktualisieren Sie Ihre API-Version
Ihre SDK-Version aktualisieren
Entwickler-Tools
SDKs
API
Tests
Workbench
Ereignisziele
Arbeitsabläufe
Stripe-CLI
Stripe Shell
Entwickler-Dashboard
Agent-Toolkit
Mit LLMs entwickelnStripe für Visual Studio CodeStripe-StatuswarnungenHochgeladene Dateien
Sicherheit und Datenschutz
Sicherheit
Datenschutz
Extend Stripe
Stripe-Apps
    Übersicht
    Jetzt starten
    Eine App erstellen
    Funktionsweise von Stripe-Apps
    Beispiel-Apps
    App erstellen
    Shop-Geheimnisse
    API-Authentifizierungsmethoden
    Autorisierungsabläufe
    Serverseitige Logik
    Ereignisse überwachen
    Umgang mit verschiedenen Modi
    Sandbox-Unterstützung aktivieren
    App-Einstellungsseite
    Erstellen Sie eine Nutzeroberfläche
    Onboarding
    Ihre App verbreiten
    Vertriebsmöglichkeiten
    App hochladen
    Versionen und Releases
    Ihre App testen
    Ihre App veröffentlichen
    Ihre App bewerben
    Deep-Links hinzufügen
    Installationslinks erstellen
    Rollen in Erweiterungen der Nutzeroberfläche zuweisen
    Aktionen nach der Installation
    App-Analytik
    Eingebettete Komponenten für Apps
    Stripe-Apps von Drittanbietern einbetten
    Umstellung auf Stripe Apps
    Migrieren oder Erweiterung erstellen
    Ein Plugin zu Stripe Apps oder Stripe Connect migrieren
    Verwendungszweck
    App-Manifest
    CLI
    Erweiterungs-SDK
    Berechtigungen
    Darstellungsfelder
    Entwurfsmuster
    Komponenten
Stripe Connectors
Partner
Partner-Ecosystem
Partner-Zertifizierung
StartseiteEntwickler-ToolsStripe Apps

Dokumentation zur Extension SDK API

Ein Index mit allen Feldern, Typen und Beschreibungen für die Extension SDK API.

Seite kopieren

UI-Erweiterungen haben Zugriff auf Kontexteigenschaften und Utility-Funktionen für die Interaktion mit den App-Nutzer/innen und dem Stripe-Dashboard. Auf dieser Seite werden diese Werte und Funktionen aufgeführt.

Eigenschaften

Bei Ansichten handelt es sich um übergebene Eigenschaften, mit deren Hilfe die Erweiterung ihren Anzeigekontext ermitteln kann. Bei Ansichten können diese Eigenschaften als Argumente verwendet werden. Es handelt sich dabei um den Typ ExtensionContextValue.

import type {ExtensionContextValue} from '@stripe/ui-extension-sdk/context'; const ExampleApp = ({ userContext, environment, oauthContext, appContext}: ExtensionContextValue) => { ... }

Nutzungszusammenhang

Die Eigenschaft userContext enthält Angaben zum Endnutzer/zur Endnutzerin Ihrer App und insbesondere die folgenden Felder:

Feld
Typ
Beispiel
Name
Zeichenfolge
Jenny Rosen
Name des/der App-Nutzer/in
account.country
Zeichenfolge
Vereinigtes Königreich
Land des/der App-Nutzer/in
account.id
Zeichenfolge
acct_1032D82eZvKYlo2C
Konto-ID des/der App-Nutzer/in
account.name
Zeichenfolge
Jenny’s Llama Emporium
Der Name des Stripe-Kontos
account.isSandbox
Boolesch
wahr
Ob das Stripe-Konto eine Sandbox ist oder nicht
Rollen
Array<RoleDefinition>
none
Eine Liste der Nutzerrollen des aktiven Nutzers/der aktiven Nutzerin.
Gebietsschema
Zeichenfolge
en-GB
Systemsprachen-ID des/der App-Nutzer/in

RoleDefinition

Eine Rollendefinition hat folgende Felder:

Name des Felds
Typ
Beispiel
Typ
‘builtIn’ | ‘custom’
builtIn
Gibt den Rollentyp an. Benutzerdefinierte Rollen sind nur für private Apps verfügbar.
Name
Zeichenfolge
Entwickler/in
Der Name der Nutzerrolle.

Umgebung

Die Eigenschaft environment enthält Angaben zur angezeigten Seite und insbesondere die folgenden Felder:

Feld
Typ
Beispiel
viewportID
Zeichenfolge
stripe.dashboard.payment.list
Das aktuelle Darstellungsfeld, das Ihre Ansicht rendert
Modus
‘live’ | ‘test’
Live
Der Stripe-API-Modus, in dem sich die aktuelle Seite befindet
objectContext.id
Zeichenfolge
ch_3L0pjB2eZvKYlo2C1u1vZ7aK
Bei ObjectView-Objekten ist dies die Kennung des aktuell im Dashboard angezeigten Objekts.
objectContext.object
Zeichenfolge
Zahlung
Bei ObjectView-Objekten ist dies der Typ des aktuell im Dashboard angezeigten Objekts.
Konstanten
Objekt
{"API_BASE": "https://api.example.com/v1"}
Ein Objekt mit willkürlichen konstanten Werten, die aus dem App-Manifest übergeben werden und das für die lokale Entwicklung mit dem CLI-Manifest-Flag überschrieben werden können.

OAuth-Kontext

Die Eigenschaft oauthContext enthält Angaben zum aktuellen OAuth-Workflow (sofern zutreffend).

Feld
Typ
Beispiel
Fehler
Zeichenfolge
none
OAuth-Fehlercode
Code
Zeichenfolge
none
OAuth-Autorisierungscode
Bundesland
Zeichenfolge
none
Von Ihrer App verwendeter OAuth-Status
Verifizierung
Zeichenfolge
none
OAuth-Code-Verifizierung

App-Kontext

Die Eigenschaft appContext enthält Informationen über die App-Installation des Nutzers/der Nutzerin und verfügt über die folgenden Felder:

Feld
Typ
Beispiel
authorizedPermissions
Array<string>
['event_read', 'charge_write']
Aktuelle autorisierte Berechtigungen der App
authorizedCSP.connectSrc
Array<string>
['http://o.ingest.sentry.io/api/']
URLs zulässiger Drittanbieter-APIs. Wenn die URL mit einem Schrägstrich endet, sind auch alle untergeordneten URLs zulässig.
authorizedCSP.imageSrc
Array<string>
['https://images.example.com/', 'https://images.example.org']
URLs, von denen die Img-Komponente geladen werden kann. Wenn die URL mit einem Schrägstrich endet, sind auch alle untergeordneten URLs zulässig.

Utility-Funktionen

Nutzeroberflächen-Erweiterungs-SDK bietet diese Funktionen, damit Apps mit der Stripe-API und dem/der Dashboard-Benutzer/in interagieren können.

  • clipboardWriteText schreibt Text in die Zwischenablage der Nutzer/innen.
  • createHttpClient – Holen Sie sich einen authentifizierten Stripe API-Client.
  • createOAuthState erfasst Werte für die weitere Verwendung bei der Erstellung von Autorisierungslinks in OAuth-Workflows.
  • fetchStripeSignature ruft eine Signatur von den Stripe-Servern ab.
  • getDashboardUserEmail erfasst die E-Mail-Adresse des Endnutzers/der Endnutzerin.
  • getUserAuthorizedPermissions: Ruft die Schnittmenge zwischen den autorisierten Berechtigungen der App und denen des aktuellen Dashboard-Nutzers bzw. der Dashboard-Nutzerin ab.
  • isPermissionAuthorized: Gibt an, ob sich eine Berechtigung derzeit in den autorisierten Berechtigungen einer App befindet.
  • isSourceInAuthorizedCSP: Gibt an, ob eine URL derzeit in der Sicherheitsrichtlinie für autorisierte Inhalte einer App enthalten ist.
  • showToast – Zeigt dem/der Nutzer/in eine Toast-Nachricht an.
  • useRefreshDashboardData ermöglicht der Ansicht die Aktualisierung von Daten im Dashboard.

clipboardWriteText

Schreiben Sie Text in die Zwischenablage des/der App-Nutzer/in. Der/die Nutzer/in kann diesen dann so einfügen, als ob er/sie ihn selbst kopiert hätte.

Argument
Typ
Beispiel
Text
Zeichenfolge
Hallo, Welt!
Zu kopierender Text

Um diese Funktion zu verwenden, importieren Sie sie zuerst aus dem SDK:

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

Bieten Sie zum Beispiel eine Schaltfläche an, die Hello, world! in die Zwischenablage kopiert, wenn darauf geklickt wird. In einer realen App könnten Sie diese Schaltfläche verwenden, um eine Adresse, eine Rechnungsnummer oder ein anderes wichtiges Detail zu kopieren.

import {useCallback} from 'react'; import {Button} from '@stripe/ui-extension-sdk/ui'; import {clipboardWriteText} from '@stripe/ui-extension-sdk/utils'; const App = () => { const writeToClipboard = useCallback(async () => { try { await clipboardWriteText('Hello, world!'); // Writing to the clipboard succeeded } catch (e) { // Writing to the clipboard failed } }, []); return ( <Button onPress={writeToClipboard} > Copy to clipboard </Button> ); };

createHttpClient

Fordern Sie einen authentifizierten Stripe API-Client für das Konto des/der installierten Nutzers/Nutzerin an. Sie müssen den vom SDK bereitgestellten STRIPE_API_KEY verwenden, um Ihrem Client die im App-Manifest definierten Berechtigungen zu erteilen.

Um diese Funktion zu verwenden, importieren Sie sie zuerst aus dem SDK und geben Sie dann ihre Werte an den Stripe-Konstruktor von stripe-node an.

import {createHttpClient, STRIPE_API_KEY} from '@stripe/ui-extension-sdk/http_client'; import Stripe from 'stripe'; const stripe = new Stripe( STRIPE_API_KEY, { httpClient: createHttpClient(), apiVersion: '2022-11-15' } )

Ein Beispiel im Kontext finden Sie unter Erstellen einer Nutzeroberfläche.

createOAuthState

Beziehen Sie die Werte für state und challenge, die Sie beim Erstellen eines Autorisierungslinks in einem OAuth-Workflow verwenden.

Um diese Funktion zu verwenden, importieren Sie sie zuerst aus dem SDK.

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

Ein Beispiel im Kontext finden Sie unter Autorisierungs-Workflows hinzufügen.

fetchStripeSignature

Beziehen Sie eine Signatur von den Servern von Stripe. Ihre Nutzeroberflächenerweiterung kann diese Signatur verwenden, um signierte Anfragen an das Backend Ihrer Anwendung zu senden.

Um diese Funktion zu verwenden, importieren Sie sie zuerst aus dem SDK.

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

Weitere Informationen und ein Beispiel im Kontext finden Sie in der Dokumentation zur Serverlogik.

getDashboardUserEmail

Fordern Sie die E-Mail-Adresse des/der App-Nutzer/in an.

Um diese Funktion zu verwenden, importieren Sie sie zuerst aus dem SDK.

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

Sie müssen auch die Berechtigung user_email_read in Ihr App-Manifest aufnehmen. Fügen Sie es mit einem CLI-Befehl hinzu oder bearbeiten Sie die App-Manifest-Datei direkt.

Command Line
CLI-Befehl
stripe apps grant permission user_email_read
"EXPLANATION"

Beispielsweise können Sie in einer Ansicht auf die E-Mail-Adresse des/der App-Nutzer/in zugreifen, indem Sie sie mit der Funktion getDashboardUserEmail abrufen und in einer React-Zustandsvariablen speichern.

import {useEffect, useState} from 'react'; import {getDashboardUserEmail} from '@stripe/ui-extension-sdk/utils'; export const useDashboardUserEmail = () => { const [email, setEmail] = useState<string | null>(null); const fetchEmail = async () => { try { const {email} = await getDashboardUserEmail(); setEmail(email); } catch(e) { console.error(e); } }; useEffect(() => { fetchEmail(); }, []); return email; }; const App = () => { const dashboardUserEmail = useDashboardUserEmail(); ... };

getUserAuthorizedPermissions

Ruft die Schnittmenge zwischen den autorisierten Berechtigungen der App und denen des aktuellen Dashboard-Nutzers bzw. der Dashboard-Nutzerin ab.

Wenn die aktuellen autorisierten Berechtigungen der App beispielsweise event_read und charge_write sind, der/die aktuelle Dashboard-Nutzer/in jedoch die Rolle view_only hat (d. h. keine Bearbeitungsberechtigungen), wird durch Aufruf der Funktion das Array ['event_read'] zurückgegeben.

Um diese Funktion zu verwenden, importieren Sie sie zuerst aus dem SDK.

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

isPermissionAuthorized

Geben Sie an, ob eine Berechtigung in den autorisierten Berechtigungen der App enthalten ist. Wenn die Berechtigung nicht im App-Manifest enthalten ist, wird ein Fehler ausgegeben.

Argument
Typ
Beispiel
Berechtigung
Zeichenfolge
charge_read
Berechtigung zur Prüfung

Um diese Funktion zu verwenden, importieren Sie sie zuerst aus dem SDK.

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

Gating-Funktionalität nach Berechtigung

Mit dieser Funktion kann die App-Funktionalität durch von dem/der Nutzer/in autorisierte Berechtigungen eingeschränkt werden.

Aktualisieren Sie beispielsweise auf der Seite mit Kundendetails nur dann die Kundendaten, wenn der/die App-Nutzer/in die Berechtigung customer_write autorisiert hat.

import {isPermissionAuthorized} from '@stripe/ui-extension-sdk/utils'; const App = () => { const updateCustomer = useCallback(async () => { const customerWriteEnabled = await isPermissionAuthorized('customer_write'); if (customerWriteEnabled){ await updateCurrentCustomer() } ... }) }

isSourceInAuthorizedCSP

Geben Sie an, ob eine URL in den autorisierten Verbindungsquellen oder Bildquellen der App enthalten ist.

Argument
Typ
Beispiel
Quelle
Zeichenfolge
https://images.example.org/
Zu prüfende URL

Um diese Funktion zu verwenden, importieren Sie sie zuerst aus dem SDK.

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

showToast

Machen Sie einen Toast am Ende Ihrer Ansicht, um die Nutzer/innen über den Status einer Aktion zu informieren. Beispielsweise kann ein Toast einem Nutzer/einer Nutzerin anzeigen, ob ein API-Aufruf erfolgreich war oder fehlgeschlagen ist.

import {showToast} from '@stripe/ui-extension-sdk/utils'; const App = () => { const handleClick = () => { fetch(...) .then((response) => { showToast("Invoice updated", {type: "success"}) return response.json() }) .catch(() => { showToast("Invoice could not be updated", {type: "caution"}) }) } // Use the `handleClick`... }

Die Funktion showToast() akzeptiert die zwei Argumente message und options. Die Funktion ist wie folgt definiert:

type ToastType = "success" | "caution" | "pending" | undefined; type ToastOptions = { type?: ToastType; action?: string; onAction: () => void; } (message: string, options?: ToastOptions) => Promise<{ update: (updateMessage: string, updateOptions?: ToastOptions) => void; dismiss: () => void; }>;

Toastnachrichten dürfen nicht länger als 30 Zeichen sein und nicht leer sein. Wenn eine Nachricht zu lang oder leer ist, protokolliert die Konsole einen Fehler.

Toasts werden, außer sie sind vom Typ pending, automatisch geschlossen.

Ist ausstehendHat AktionTimeout
falsefalse4s
falsetrue6s
truefalseKeine
truetrueKeine
import {showToast} from '@stripe/ui-extension-sdk/utils'; const App = () => { const handleClick = async () => { const { dismiss, update } = await showToast("Refreshing data", { type: "pending", }); try { await refreshData(); dismiss(); } catch (error) { update("Data could not be refreshed", { type: "caution" }); } } // Use the `handleClick`... }

Toasts können den/die Nutzer/in auch auffordern, eine Aktion durchzuführen. Durch Klicken auf die Aktionsschaltfläche wird der Toast automatisch geschlossen.

import {showToast} from '@stripe/ui-extension-sdk/utils'; const App = () => { const handleClick = async () => { let timeout; const { dismiss } = await showToast('Message "sent"', { action: "Undo", onAction: () => { clearTimeout(timeout); showToast('Message "unsent"'); }, }); timeout = setTimeout(() => { sendMessage(); dismiss(); }, 3000); } // Use the `handleClick`... }

useRefreshDashboardData

Aktivieren Sie Ihre Ansicht, um Daten im Dashboard zu aktualisieren. Diese Funktion gibt eine weitere Callback-Funktion zurück. Speichern Sie diesen Callback und rufen Sie ihn auf, wenn sich Stripe-Daten ändern. Wenn Sie ihn aufrufen, wird das Dashboard mit den neuen Werten aktualisiert.

Um diese Funktion zu verwenden, importieren Sie sie zuerst aus dem SDK.

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

Fordern Sie zum Beispiel auf einer Kundendetailseite die Callback-Funktion an, die die Dashboard-Daten aktualisiert, und rufen Sie sie dann nach der Aktualisierung des aktuellen Kunden bzw. der aktuellen Kundin auf.

import {useCallback} from 'react'; import {useRefreshDashboardData} from '@stripe/ui-extension-sdk/utils'; const App = () => { const refreshDashboardData = useRefreshDashboardData(); const updateCustomer = useCallback(async () => { try { await updateCurrentCustomer(); await refreshDashboardData(); } catch (error) {} }, [refreshDashboardData]); }

Siehe auch

  • Funktionsweise von Nutzeroberflächen-Erweiterungen
  • Dokumentation zu Viewports
  • Rollen in Erweiterungen der Nutzeroberfläche verwenden
War diese Seite hilfreich?
JaNein
Benötigen Sie Hilfe? Kontaktieren Sie den Kundensupport.
Nehmen Sie an unserem Programm für frühzeitigen Zugriff teil.
Schauen Sie sich unser Änderungsprotokoll an.
Fragen? Sales-Team kontaktieren.
LLM? Lesen Sie llms.txt.
Unterstützt von Markdoc