# Erstellen Sie eine Nutzeroberfläche Erstellen, testen und bearbeiten Sie eine eigene Nutzeroberfläche, die die Funktionen des Stripe-Dashboards erweitert. Konfigurieren Sie für Ihre App mithilfe von TypeScript, React sowie des [UI Extensions SDK](https://docs.stripe.com/stripe-apps/reference/extensions-sdk-api.md) und des [UI-Toolkits](https://docs.stripe.com/stripe-apps/design.md) von Stripe eine Nutzeroberfläche, die über das Stripe-Dashboard hinausgeht. In diesem Leitfaden erfahren Sie, wie Sie durch das Erstellen und Löschen von Ansichten eine einfache Nutzeroberfläche erstellen können. Technische Informationen zu diesem Thema finden Sie in dem Artikel [Funktionsweise von Erweiterungen der Nutzeroberfläche](https://docs.stripe.com/stripe-apps/how-ui-extensions-work.md). ## Eine Ansicht hinzufügen Verwenden Sie Ansichten, um die Nutzeroberfläche Ihrer App zu entwickeln. Eine Ansicht ist eine Kombination aus einer React-Komponente und einem bestimmten Darstellungsfeld. Die React-Komponente besteht aus UI-Komponenten aus unserem UI-Toolkit. Das Darstellungsfeld ist die Seite bzw. der Abschnitt des Stripe-Dashboards, wo Sie es anzeigen möchten. 1. Verwenden Sie den Befehl `add` aus dem Stammverzeichnis Ihres Projekts: ```bash stripe apps add view ``` 1. Folgen Sie der Eingabeaufforderung: - Wählen Sie das Darstellungsfeld aus, in dem Ihre Ansicht angezeigt wird. Dies ist eine Liste der [verfügbaren Darstellungsfelder](https://docs.stripe.com/stripe-apps/reference/viewports.md). - Benennen Sie Ihre Ansicht (z. B. MeinKomponentenname). Die CLI schlägt Namen anhand Ihrer Darstellungsfeldauswahl vor. Stripe fügt Ihre Ansicht automatisch dem Array `views` im *Manifest Ihrer App* (In a Stripe App, the app manifest is a stripe-app.json file in your app's root directory. It defines your app's ID, views, permissions, and other essential properties) hinzu, erzeugt eine neue React-Komponenten-Datei im Verzeichnis `src/views` und erstellt daneben eine Testdatei für die Komponenten. ## App in der Vorschau anzeigen Sie können Ihre App lokal ausführen, Aktualisierungen vornehmen und Ihre Änderungen im Dashboard in der Vorschau anzeigen. 1. Starten Sie den Entwicklungsserver im Stammverzeichnis Ihres Projekts: ```bash stripe apps start ``` 1. Drücken Sie **Enter**, um den Browser zu öffnen. 1. Klicken Sie zur Vorschau Ihrer App in Ihrem Stripe-Konto auf **Weiter**. [Aktivieren Sie den lokalen Netzwerkzugriff](https://docs.stripe.com/stripe-apps/enable-local-network-access.md), bevor Sie eine Vorschau Ihrer App anzeigen. 1. Um den Entwicklungsserver zu deaktivieren, geben Sie in der Betreffzeile **Ctrl+C** ein. Wenn der Entwicklungsserver aktiv ist, können Sie Änderungen an Ihrer App vornehmen und automatisch im Dashboard anzeigen, ohne die Seite aktualisieren zu müssen. Bis Fehler behoben sind, werden diese automatisch im Stripe-Dashboard, den Entwicklungstools Ihres Browsers und der Stripe-CLI angezeigt. ### Vorschauen wechseln Sie können die Vorschau der lokalen Version Ihrer App deaktivieren, um eine Vorschau einer kürzlich [installierten Version Ihrer App im Test-Modus](https://docs.stripe.com/stripe-apps/upload-install-app.md) oder einer *Sandbox* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes)-Umgebung anzuzeigen. Wenn Sie noch nie eine Version Ihrer App im Test-Modus oder in einer Sandbox-Umgebung installiert haben, ist ein Wechsel der Vorschau nicht möglich. Um eine Vorschau der zuletzt installierten Version Ihrer App im Test-Modus oder in einer Sandbox-Umgebung anzuzeigen, führen Sie Ihren Entwicklungsserver aus und befolgen Sie diese Schritte: 1. Klicken Sie oben rechts in Ihrer App auf das Überlaufmenü ⋯. 1. Klicken Sie auf **App-Vorschau deaktivieren** und dann auf **Weiter**. ## Auf Stripe-Objekte im Dashboard zugreifen Wenn Sie einem Darstellungsfeld eine Komponente zuweisen, kann diese mithilfe des Objekts `environment.objectContext` Kontext über das Stripe-Objekt auf dieser Seite erhalten. Wenn Sie beispielsweise eine Ansicht erstellen, die das Darstellungsfeld `stripe.dashboard.customer.detail` verwendet, gibt das Objekt `environment.objectContext` einen `customer`-Objekttyp und die ID des aktuellen Kunden/der aktuellen Kundin zurück. Sie können diese Werte dann verwenden, um weitere Informationen über das [Customer](https://docs.stripe.com/api/customers.md?lang=node)-Objekt zu erhalten und Attribute wie Adresse, Beschreibung usw. zu ändern. Einen Index der Objekte, die ein Darstellungsfeld bereitstellt, finden Sie in der [Dokumentation zu Darstellungsfeldern](https://docs.stripe.com/stripe-apps/reference/viewports.md). ### Beispiel: Kundenname aktualisieren Mit dem folgenden Code werden die Kundennamen mithilfe des [Stripe Node.js-API-Clients](https://docs.stripe.com/api.md?lang=node) und der `environment.objectContext`-ID im Darstellungsfeld aktualisiert: 1. Fügen Sie die Berechtigung `customer_write` zu Ihrer App hinzu: ```bash stripe apps grant permission "customer_write" "Allows the app to update the name of the customer." ``` 1. Verwenden Sie die Stripe-API in Ihrer App, um den Namen des/der Kund/in zu aktualisieren: ```js import {createHttpClient, STRIPE_API_KEY} from '@stripe/ui-extension-sdk/http_client'; import Stripe from 'stripe'; // Initiate communication with the stripe client. const stripe = new Stripe(STRIPE_API_KEY, { httpClient: createHttpClient(), apiVersion: '2022-08-01', }) const App = ({environment, userContext}) => { // Call the Stripe API to make updates to customer details. const updateCurrentCustomer = async (newCustomerName) => { try { // If the user has permission to update customers, this should succeed. const updatedCustomer = await stripe.customers.update( // We can use the current objectContext to get the customer ID. environment.objectContext.id, {name: newCustomerName} ); console.log(updatedCustomer.name); } catch (error) {} }; } ``` ### Beispiel: Daten im Dashboard aktualisieren Wenn Ihre App Daten im Dashboard ändert, verwenden Sie die Funktion [useRefreshDashboardData](https://docs.stripe.com/stripe-apps/reference/extensions-sdk-api.md#useRefreshDashboardData), um einen Rückruf zu generieren und die Daten zu aktualisieren: ```js import {useCallback} from 'react'; import {useRefreshDashboardData} from '@stripe/ui-extension-sdk/context'; const App = () => { // Get the callback used to refresh the dashboard data const refreshDashboardData = useRefreshDashboardData(); // Stripe API call const updateCustomer = useCallback(async () => { try { await updateCurrentCustomer(); // Call to refresh the data in the Dashboard refreshDashboardData(); } catch (error) {} }, [refreshDashboardData]); } ``` ## Drittanbieter-APIs nutzen Ihre Nutzeroberflächen-Erweiterung kann APIs von Drittanbietern (Ihre eigene API oder eine beliebige öffentliche API) aufrufen, so fordert Ihre App Daten an bzw. sendet diese. 1. Fügen Sie mit dem Befehl `grant url` die URL der Drittanbieter-API hinzu: ```bash stripe apps grant url "https://*.api.example.com/path/" "Send data to example service..." ``` Die URL **connect-src** muss die folgenden Anforderungen erfüllen: | Anforderung | Beispiel | | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | Verwenden Sie das sichere HTTPS-Protokoll. | **https://www.example.com/api/users/** | | Ein Pfad enthalten. | - Gültiges Beispiel: **https://www.example.com/api/users/** - Ungültiges Beispiel: **https://www.example.com/** | | Verwenden Sie einen Basispfad mit einem nachgestellten Schrägstrich, um alle Pfade danach zuzulassen. | **https://www.example.com/api/** ermöglicht Aufrufe von **https://www.example.com/api/users/abc123/address**. | | Es darf sich dabei nicht um einen Aufruf einer Stripe-API handeln. | | | Wenn Sie einen Platzhalter (`*`) verwenden, muss dieser im DNS-Label ganz links stehen. | **https://\*.example.com/api/users/** | > Wenn Sie mit CSP-Problemen im Browser zu kämpfen haben, stellen Sie sicher, dass Sie einen nachgestellten Schrägstrich an Ihre `connect-src`-URL angehängt haben. Mit Stripe Apps wird die URL im Array `connect-src` des *App-Manifests* (In a Stripe App, the app manifest is a stripe-app.json file in your app's root directory. It defines your app's ID, views, permissions, and other essential properties) Ihres Projekts hinzugefügt: ```js "ui_extension": { "views": [], "actions": [], "content_security_policy": { "connect-src": [ "https://*.api.example.com/", "https://o0.ingest.example.io/api/", ], "purpose": "Send data to example service. The Example app sends data to the Example service to provide its functionality and sends anonymous error reports to our partner Example for debugging purposes" } } ``` Um eine connect-src-URL zu entfernen, können Sie auch die Stripe-CLI verwenden: ```bash stripe apps revoke connect-src "https://*.api.example.com/path/" ``` 1. Um eine Vorschau Ihrer App im Browser anzuzeigen, starten Sie Ihren Entwicklungsserver und folgen Sie den Eingabeaufforderungen der CLI: ```bash stripe apps start ``` 1. Fügen Sie den `fetch`-Aufruf mit der URL Ihrer Drittanbieter-API in Ihre App ein. Wenn Sie zum Beispiel die connect-src-URL `https://www.example.com/api/users` zu Ihrem *App-Manifest* (In a Stripe App, the app manifest is a stripe-app.json file in your app's root directory. It defines your app's ID, views, permissions, and other essential properties) hinzufügen, können Sie folgenden Fetch-Aufruf verwenden: ```js const makeRequestToService = (endpoint, requestData) => { return fetch(`https://www.example.com/api/${endpoint}/`, { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: requestData, }); }; ``` 1. [Laden Sie eine erweiterte Manifest-Datei](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#extended-manifest) um verschiedene *App-Manifestwerte* (In a Stripe App, the app manifest is a stripe-app.json file in your app's root directory. It defines your app's ID, views, permissions, and other essential properties) in der lokalen Entwicklung und Produktion zu verwenden. 1. Wenn die Drittanbieter-API über eine JavaScript-Client-Bibliothek verfügt, können Sie die Abhängigkeit mit dem Befehl `npm add` zu Ihrer App hinzufügen. ## Fehlerbehebung der App Während Sie Ihre App entwickeln, können Sie die Entwickler-Tools-Konsole Ihres Browsers als Fehlerbehebungs-Tool verwenden. So isolieren Sie die Nachrichten bezüglich Ihrer App: 1. Finden Sie Ihre App-ID im *App-Manifest* (In a Stripe App, the app manifest is a stripe-app.json file in your app's root directory. It defines your app's ID, views, permissions, and other essential properties). 1. Geben Sie im Bereich **Konsole** Ihres Entwickler-Tools-Browsers `[Stripe App ]` in das Feld **Filter** ein. Es sollte in etwa folgendermaßen aussehen: `[Stripe App com.example.helloworld]`. ## Tests für Ihre Ansicht schreiben Wir empfehlen, Tests für Ihre Ansichten zu erstellen. Mit Komponententests können Sie nicht nur überprüfen, ob sich Ihre Ansicht erwartungsgemäß verhält, sondern sie sorgen auch für mehr Sicherheit bei der zukünftigen Durchführung von Änderungen am Code. Wenn Sie Ihre Ansicht erstellen, enthält die auf `.test.tsx` endende Testdatei ein Muster der Standardansicht: ```ts import {render, getMockContextProps} from "@stripe/ui-extension-sdk/testing"; import {ContextView} from "@stripe/ui-extension-sdk/ui"; import App from "./App"; describe("App", () => { it("renders ContextView", () => { const {wrapper} = render(); expect(wrapper.find(ContextView)).toContainText("save to reload this view"); }); }); ``` Sie können alle Tests mit dem enthaltenen [Jest](https://jestjs.io/)-Test-Runner mit dem Befehl `npm run test` oder `yarn test` ausführen. Wenn Sie beliebte React-Testwerkzeuge wie [Testing Library](https://testing-library.com/docs/react-testing-library/intro) und [Enzyme](https://enzymejs.github.io/enzyme) verwendet haben, ist Ihnen das in `@stripe/ui-extension-sdk/testing` enthaltene Testpaket bereits vertraut. Ein typischer Test verläuft nach diesem Muster: - Geben Sie Ihre Ansicht wieder. - Stellen Sie eine Behauptung über den Ausgangszustand auf, z. B. dass ein Text vorhanden ist. - Interagieren Sie mit der Ansicht. - Stellen Sie eine Behauptung über den neuen Zustand auf, z. B. dass ein neuer Text angezeigt wird. Weitere Methoden und Funktionen des Testpakets finden Sie in unserem Hilfeartikel zu [Nutzeroberflächentests](https://docs.stripe.com/stripe-apps/ui-testing.md). ## Optional: Ansicht entfernen Sie können eine Ansicht im Stammverzeichnis Ihres Projekts entfernen: ```bash stripe apps remove view VIEW_NAME ``` Ersetzen Sie `VIEW_NAME` durch den Namen der Ansicht, die Sie entfernen möchten. ## See also - [Komponenten der Nutzeroberfläche](https://docs.stripe.com/stripe-apps/components.md) - [Seite mit App-Einstellungen hinzufügen](https://docs.stripe.com/stripe-apps/app-settings.md)