Dokumentation zur Extension SDK API

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:

RoleDefinition

Eine Rollendefinition hat folgende Felder:

Umgebung

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

OAuth-Kontext

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

App-Kontext

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

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.
• useStorage—Share data across different viewports of a Stripe App.

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.

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.

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.

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.

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.

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]);
}

useStorage

You can use the useStorage React hook for reading and writing shared data across different viewports of a Stripe App.

This hook synchronizes state between all active instances (viewports) of your Stripe App within the same browser. When the value updates in one instance, all other instances in the same browser reflect the change automatically. This is session-based storage that exists only while the app runs.

This hook can help you:

• Coordinate state between multiple viewports of your app.
• Avoid redundant API calls by caching fetched data and sharing it across viewports.

The hook has the following limitations:

• Values are limited to strings, so use JSON.stringify or JSON.parse for complex objects.
• Storage isn’t persistent between app sessions.
• Storage changes don’t synchronize between different browsers or devices.

The following example shows how two independently rendered instances of the same app can synchronize the value of a variable across different viewports. Try opening this app in multiple tabs to see how cross-window synchronization works.

import React from 'react';
import {Box, TextField} from '@stripe/ui-extension-sdk/ui';
import {useStorage} from '@stripe/ui-extension-sdk/data';

const [name, setName] = useStorage('name');
const greeting = name ? `Hey ${name}!` : `Hello!`;

return (
  <Box css={{stack: 'y', alignY: 'top', gap: 'medium', width: 'fill'}}>
    <TextField
      label="Full name"
      placeholder="Enter your name"
      defaultValue={name || ''}
      onChange={(e) => setName(e.target.value)}
    />
    <Box css={{font: 'title'}}>{greeting}</Box>
  </Box>
)