Mit den in Connect eingebetteten Komponenten loslegen
Erfahren Sie, wie Sie Dashboard-Funktionen in Ihre Website einbetten.
Verwenden Sie die in Connect eingebetteten Komponenten, um Dashboard-Funktionen für verbundene Konten zu Ihrer Website hinzuzufügen. Mit diesen Bibliotheken und der unterstützenden API können Sie Ihren Nutzer/innen direkt in Ihrem Dashboard Zugriff auf Stripe Produkte gewähren.
Eine umfassende Version dieses Handbuchs finden Sie im Schnellstart zur Integration eingebetteter Connect-Komponenten. Dort können Sie auch eine Beispielintegration herunterladen. Um das Erscheinungsbild der in Connect eingebetteten Komponenten anzupassen, verwenden Sie die Option appearance
bei der Initialisierung von StripeConnectInstance
. Siehe die vollständige Liste der Darstellungsparameter.
Connect.js initialisierenClientseitigServerseitig
Stripe verwendet eine AccountSession, um Ihre Absicht zum Ausdruck zu bringen, den API -Zugriff auf Ihr verbundenes Konto zu delegieren.
Die AccountSessions API gibt ein Client-Geheimnis zurück, das es einer eingebetteten Komponente im Web-Client ermöglicht, so auf die Ressourcen eines verbundenen Kontos zuzugreifen, als ob Sie die API -Aufrufe für sie durchführen würden.
AccountSession erstellen Server
In einer einseitigen Anwendung initiiert Ihr Client eine Anfrage an Ihren Server, um die Kontositzung zu erhalten. Sie können einen neuen Endpoint auf Ihrem Server erstellen, der das Client-Geheimnis an den Browser zurückgibt:
Create Account Session API
The Create Account Session API determines component and feature access for Connect embedded components. Stripe enforces these parameters for any components that correspond to the account session. If your site supports multiple user roles, make sure components and features that are enabled for that account session correspond to the current user’s role. For example, you can enable refund management only for administrators of your site, but not for other users. To ensure user role access are enforced, your backend must host the logic that maps your site’s user role to account session components.
Connect.js einrichten Client
Connect.js laden und initialisieren Client
Rufen Sie loadConnectAndInitialize
mit Ihrem veröffentlichbaren Schlüssel und einer Funktionalität auf, die ein Client-Geheimnis durch Aufrufen des neuen Endpoints abruft, den Sie auf Ihrem Server erstellt haben. Verwenden Sie die zurückgegebene StripeConnectInstance
, um eingebettete Komponenten zu erstellen. Nachdem Sie Connect.js initialisiert haben, können Sie jederzeit Komponenten im DOM bereitstellen oder ihre Bereitstellung aufheben. Dies umfasst alle Elemente, die in React- oder Vue-Portalen gerendert werden.
Eine vollständige Liste der unterstützten eingebetteten Komponenten anzeigen →
Connect.js konfigurierenClientseitig
Die Methode loadConnectAndInitialize
auf dem Client benötigt mehrere Optionen, um Connect.js zu konfigurieren.
Option | Beschreibung | |
---|---|---|
publishableKey | Der veröffentlichbare Schlüssel für Ihre Integration. | erforderlich |
fetchClientSecret | Die Funktion, die das von /v1/account_ zurückgegebene Client-Geheimnis abruft. Dadurch wird StripeConnectInstance mitgeteilt, an welches Konto der Zugriff delegiert werden soll. Diese Funktion wird auch verwendet, um eine geheime Client-Funktion abzurufen, um die Sitzung zu aktualisieren, wenn sie abläuft. | erforderlich |
appearance | Ein Objekt zum Anpassen des Erscheinungsbilds der in Connect eingebetteten Komponenten. | optional |
locale | Ein Parameter zum Angeben des Gebietsschemas, das eingebettete Connect-Komponenten nutzen. Das Gebietsschema ist standardmäßig auf die Browser-Sprache eingestellt. Wenn das angegebene Gebietsschema nicht direkt unterstützt wird, wird eine passende Alternative verwendet (so würde fr-be z. B. wahrscheinlich auf fr-fr zurückgreifen). Siehe Lokalisierung, um die Liste der unterstützten Gebietsschemen anzuzeigen. | optional |
fonts | Ein Array mit benutzerdefinierten Schriftarten, die von allen eingebetteten Komponenten verwendet werden können, die aus einer StripeConnectInstance erstellt werden. Schriftarten können als CssFontSource oder CustomFontSource angegeben werden. | optional |
Erscheinungsbild der in Connect eingebetteten Komponenten anpassen
Wir bieten eine Reihe von Optionen an, um das Erscheinungsbild von in Connect eingebetteten Komponenten anzupassen. Diese Anpassungen betreffen Schaltflächen, Symbole und andere Akzentuierungen in unserem Designsystem.
Sie können diese Optionen bei der Initialisierung von StripeConnectInstance
festlegen, indem Sie Werte an das appearance
-Objekt übergeben. Sie können diese Connect.js-Optionen nur zum Ändern der Formate in den in Connect eingebetteten Komponenten verwenden. Die Schriftfamilie und die Hintergrundfarbe eingebetteter Connect-Komponenten können mit CSS-Selektoren überschrieben werden. Stripe unterstützt das Überschreiben anderer Stile jedoch nicht.
const fetchClientSecret = async () => { const response = await fetch('/account_session'); const {client_secret: clientSecret} = await response.json(); return clientSecret; } const stripeConnectInstance = loadConnectAndInitialize({ publishableKey:
, fetchClientSecret: fetchClientSecret, fonts: [ { cssSrc: "https://myfonts.example.com/mycssfile.css", }, { src: `url(https://my-domain.com/assets/my-font-2.woff)`, family: 'My Font' } ], appearance: { // See all possible variables below overlays: "dialog", variables: { fontFamily: 'My Font', colorPrimary: "#FF0000", }, }, });"pk_test_TYooMQauvdEDq54NiTphI7jx"
Das Schriftarten-Objekt
Das fonts
-Objekt in stripeConnect.
akzeptiert ein Array von CssFontSource- oder CustomFontSource-Objekten.
Wenn Sie auf Ihrer Seite nutzerdefinierte Schriftarten verwenden (d. h. .
- oder .
-Dateien), müssen Sie diese Dateien bei der Initialisierung der in Connect eingebetteten Komponenten angeben. Auf diese Weise können die in Connect eingebetteten Komponenten diese Schriftarten ordnungsgemäß rendern. Sie können diese wie folgt angeben:
CssFontSource
Verwenden Sie dieses Objekt, um eine Stylesheet-URL zu übergeben, die Ihre nutzerdefinierten Schriftarten definiert, wenn Sie eine StripeConnectInstance
erstellen. Bei einem CssFontSource-Objekt muss Ihre CSP-Konfiguration das Abrufen der Domains, die mit den als CssFontSource angegebenen CSS-Datei-URLs verbunden sind, gestatten.
Name | Typ | Beispielwert |
cssSrc | Zeichenfolge required | https://fonts. |
Eine relative oder absolute URL, die auf eine CSS-Datei mit @font-face-Definitionen verweist. Die Verwendung einer Sicherheitsrichtlinie für Inhalte (CSP) könnte zusätzliche Richtlinien auferlegen. |
CustomFontSource
Verwenden Sie dieses Objekt, um Ihre nutzerdefinierten Schriftarten beim Erstellen einer StripeConnectInstance
zu übergeben.
Name | Typ | Beispielwert |
family | Zeichenfolge required | Avenir |
Der Name, der der Schriftart gegeben werden soll. | ||
src | Zeichenfolge required | url(https://my-domain. |
Ein gültiger src-Wert, der auf Ihre nutzerdefinierte Schriftartdatei verweist. Dies ist in der Regel (jedoch nicht immer) ein Link zu einer Datei mit dem Suffix . , . oder . . | ||
display | Zeichenfolge optional | auto |
Ein gültiger font-display-Wert. | ||
style | Zeichenfolge optional | normal |
normal , italic oder oblique . | ||
unicodeRange | Zeichenfolge optional | U+0-7F |
Ein gültiger unicode-range-Wert. | ||
weight | Zeichenfolge optional | 400 |
Ein gültiges font-weight. Beachten Sie, dass dies eine Zeichenfolge ist, keine Zahl. |
Das Erscheinungsbild-Objekt
Das appearance
-Objekt in loadConnectAndInitialize
akzeptiert die folgenden optionalen Eigenschaften:
Name | Typ | Beispielwert |
overlays | ‘dialog’ (Standard) | ‘drawer’ | dialog |
Der im Connect.js-Designsystem verwendete Overlay-Typ. Legen Sie dies entweder als Dialogfeld oder als Drawer fest. | ||
variables | Objekt | {colorPrimary: "#0074D4"} |
Siehe die vollständige Liste der Darstellungsvariablen. |
In Connect eingebettete Komponenten nach der Initialisierung aktualisieren
Die Methode update
unterstützt die Aktualisierung von in Connect eingebetteten Komponenten nach der Initialisierung. Dies ist nützlich, um die Darstellungsoptionen zur Laufzeit zu wechseln (ohne die Seite zu aktualisieren). Verwenden Sie dazu dasselbe stripeConnectInstance
-Objekt, das Sie mit initialize
erstellt haben, und rufen Sie die Methode update
dafür auf:
stripeConnectInstance.update({ appearance: { variables: { colorPrimary: "#FF0000", }, }, locale: 'en-US', });
Notiz
Nicht alle Optionen (z. B. fonts
) lassen sich aktualisieren. Die unterstützten Optionen für diese Methode sind eine Teilmenge der in initialize
angebotenen Optionen. Dadurch wird die Aktualisierung von appearance
und locale
unterstützt.
Breite und Höhe
Die in Connect eingebetteten Komponenten verhalten sich wie normale block
-HTML-Elemente. Standardmäßig nehmen sie 100 % der width
ihres übergeordneten HTML-Elements ein und wachsen entsprechend dem darin gerenderten Inhalt in die Höhe. Sie können die width
der in Connect eingebetteten Komponenten steuern, indem Sie die width
des übergeordneten HTML-Objekts angeben. Sie können die height
nicht direkt steuern, da diese vom gerenderten Inhalt abhängt. Sie können die Höhe jedoch mit maxHeight
und overflow: scroll
begrenzen, genau wie bei anderen HTML-block
-Elementen.
Authentifizierung
Wir bieten eine Reihe von APIs zur Verwaltung von Kontositzungen und Nutzeranmeldedaten in den in Connect eingebetteten Komponenten.
Client-Geheimnis aktualisieren
Bei Sitzungen mit langer Laufzeit kann die Sitzung aus dem ursprünglich angegebenen Client-Geheimnis ablaufen. Wenn sie abläuft, verwenden wir automatisch fetchClientSecret
, um ein neues Client-Geheimnis abzurufen und die Sitzung zu aktualisieren. Sie müssen keine zusätzlichen Parameter übergeben.
import { loadConnectAndInitialize } from "@stripe/connect-js"; // Example method to retrieve the client secret from your server const fetchClientSecret = async () => { const response = await fetch('/account_session'); const {client_secret: clientSecret} = await response.json(); return clientSecret; } const stripeConnectInstance = loadConnectAndInitialize({ publishableKey: "{{PUBLISHABLE_KEY}}", fetchClientSecret: fetchClientSecret, });
Abmelden
Wir empfehlen, dass Sie logout
für die stripeConnectInstance
abrufen, um das zugehörige Kontositzungs-Objekt zu löschen, nachdem sich eine Nutzerin/ein Nutzer von Ihrer App abgemeldet hat. Dadurch werden alle in Connect eingebetteten Komponenten deaktiviert, die zu dieser stripeConnectInstance
verlinken.
// Call this when your user logs out stripeConnectInstance.logout();
CSP- und HTTP-Header-Anforderungen
Wenn Ihre Website eine Sicherheitsrichtlinie für Inhalte implementiert, müssen Sie die Richtlinie aktualisieren, indem Sie die folgenden Regeln hinzufügen:
frame-src
https://connect-js.
stripe. com https://js.
stripe. com img-src
https://*.
stripe. com script-src
https://connect-js.
stripe. com https://js.
stripe. com style-src
sha256-0hAheEzaMe6uXIKV4EehS9pu1am1lj/KnnzrOYqckXk=
(SHA eines leeren Style-Elements)
Wenn Sie eine CSS-Datei zum Laden von Web-Fonts zur Nutzung mit in Connect eingebetteten Komponenten verwenden, muss die entsprechende URL durch Ihre CSP-Direktive connect-src zugelassen sein.
Durch Festlegen bestimmter HTTP-Antwort-Header wird die volle Funktionalität der in Connect eingebetteten Komponenten aktiviert:
- Cross-Origin-Opener-Policy,
unsafe-none
. Dies (unsafe-none
) ist der Standardwert der Kopfzeile, daher funktioniert es, auch ohne die Kopfzeile festzulegen. Andere Werte wiesame-origin
unterbrechen die Nutzerauthentifizierung in eingebetteten Connect-Komponenten.
Unterstützte Browser
Wir unterstützen dieselben Browser, die derzeit vom Stripe-Dashboard unterstützt werden:
- Die letzten 20 Hauptversionen von Chrome und Firefox
- Die letzten beiden Hauptversionen von Safari und Edge
- Die letzten beiden Hauptversionen von Mobile Safari für iOS
Eingebettete Connect-Komponenten werden nur in Webbrowsern unterstützt und können nicht in eingebetteten Webansichten in mobilen oder Desktop-Anwendungen verwendet werden.
Lokalisierung
Beim Initialisieren von Connect.js können Sie einen locale
-Parameter übergeben. Um das Gebietsschema einer eingebetteten Komponente an das Gebietsschema Ihrer Website anzupassen, übergeben Sie den Parameter locale
mit dem Gebietsschema der Nutzeroberfläche, die Ihre Website rendert.
Der Standardwert des Parameters locale
wird durch das vom Browser konfigurierte Gebietsschema bestimmt. Wenn das angegebene Gebietsschema nicht direkt unterstützt wird, wird eine passende Alternative verwendet (so würde fr-be
z. B. wahrscheinlich auf fr-fr
zurückgreifen).
Eingebettete Connect-Komponenten unterstützen die folgenden Gebietsschemen:
Sprache | Gebietsschema-Code |
---|---|
Bulgarisch (Bulgarien) | bg-BG |
Chinesisch (Vereinfacht) | zh-Hans |
Chinesisch (Traditionell – Hongkong) | zh-Hant-HK |
Chinesisch (Traditionell – Taiwan) | zh-Hant-TW |
Kroatisch (Kroatien) | hr-HR |
Tschechisch (Tschechien) | cs-CZ |
Dänisch (Dänemark) | da-DK |
Niederländisch (Niederlande) | nl-NL |
Englisch (Australien) | en-AU |
Englisch (Indien) | en-IN |
Englisch (Irland) | en-IE |
Englisch (Neuseeland) | en-NZ |
Englisch (Singapur) | en-SG |
Englisch (Vereinigtes Königreich) | en-GB |
Englisch (USA) | en-US |
Estnisch (Estland) | et-EE |
Philippinisch (Philippinen) | fil-PH |
Finnisch (Finnland) | fi-FI |
Französisch (Kanada) | fr-CA |
Französisch (Frankreich) | fr-FR |
Deutsch (Deutschland) | de-DE |
Griechisch (Griechenland) | el-GR |
Ungarisch (Ungarn) | hu-HU |
Indonesisch (Indonesien) | id-ID |
Italienisch (Italien) | it-IT |
Japanisch (Japan) | ja-JP |
Koreanisch (Südkorea) | ko-KR |
Lettisch (Lettland) | lv-LV |
Litauisch (Litauen) | lt-LT |
Malaiisch (Malaysia) | ms-MY |
Maltesisch (Malta) | mt-MT |
Norwegisch, Bokmål (Norwegen) | nb-NO |
Polnisch (Polen) | pl-PL |
Portugiesisch (Brasilien) | pt-BR |
Portugiesisch (Portugal) | pt-PT |
Rumänisch (Rumänien) | ro-RO |
Slowakisch (Slowakei) | sk-SK |
Slowenisch (Slowenien) | sl-SI |
Spanisch (Argentinien) | es-AR |
Spanisch (Brasilien) | es-BR |
Spanisch (Lateinamerika) | es-419 |
Spanisch (Mexiko) | es-MX |
Spanisch (Spanien) | es-ES |
Schwedisch (Schweden) | sv-SE |
Thai (Thailand) | th-TH |
Türkisch (Türkiye) | tr-TR |
Vietnamesisch (Vietnam) | vi-VN |
Umgang mit Fehlern beim Laden
Wenn eine Komponente nicht geladen werden kann, können Sie auf den Fehler reagieren, indem Sie einer eingebetteten Komponente einen Load Error Handler zur Verfügung stellen. Je nach Fehlerursache kann der Load Error Handler mehrfach aufgerufen werden. Jede Logik, die durch einen Load Error Handler ausgelöst wird, muss idempotent sein.
The load error
object
Every time there’s a load failure, an error
object is passed to the load error handler with the following properties.
Name | Type | Example value |
type | authentication_ | |
The type of error | ||
message | string | undefined | Failed to fetch account session |
Further description about the error |
Types of load failures
When a component fails to load, we detect the type of failure and map it to one of the types below. If the load error type can’t be determined it is marked as an api_
.
Type | Description |
---|---|
api_ | Failure to connect to Stripe’s API |
authentication_ | Failure to perform the authentication flow within Connect embedded components |
account_ | Account session creation failed |
invalid_ | Request failed with an 4xx status code, typically caused by platform configuration issues |
rate_ | Request failed because an abnormal request rate was detected |
api_ | API errors covering any other type of problem, such as a temporary problem with Stripe’s servers |
Anzeige eingebetteter Komponenten erkennen
Nachdem eine Komponente erstellt wurde, wird auf Nutzerseite erst dann eine Nutzeroberfläche angezeigt, wenn das Javascript für die Komponente geladen und im Browser analysiert wurde. Dies kann dazu führen, dass Komponenten nach Abschluss des Ladevorgangs angezeigt werden. Um dies zu vermeiden, zeigen Sie Ihre eigene Ladenutzeroberfläche an, bevor die Komponente erstellt wird, und blenden die Nutzeroberfläche aus, nachdem die Komponente angezeigt wurde. Alle eingebetteten Komponenten können eine Rückruf-Funktion akzeptieren, die unmittelbar vor der Anzeige einer Nutzeroberfläche aufgerufen wird.
Integration ohne Frontend-NPM-Pakete durchführen
Wir empfehlen die Integration mit unseren Javascript- und React-Komponenten-Wrappern, die das Laden der in Connect eingebetteten Komponenten vereinfachen und TypeScript-Definitionen für unsere unterstützten Schnittstellen bereitstellen. Wenn Ihr Build-System derzeit keine Abhängigkeiten von Paketen unterstützt, können Sie die Integration auch ohne diese Pakete durchführen.
Fügen Sie das Connect.js-Skript-Tag manuell zum <head>
jeder Seite Ihrer Website hinzu.
<!-- Somewhere in your site's <head> --> <script src="https://connect-js.stripe.com/v1.0/connect.js" async></script>
Connect.js ohne NPM verwenden
Nachdem Connect.js geladen wurde, wird die globale Fenstervariable StripeConnect
initialisiert und StripeConnect.
aufgerufen, sofern von Ihnen definiert. Sie können Connect.js sicher initialisieren, indem Sie eine onload
-Funktion einrichten und StripeConnect.
mit denselben Connect.js-Optionen wie loadConnectAndInitialize
aufrufen.
window.StripeConnect = window.StripeConnect || {}; StripeConnect.onLoad = () => { const stripeConnectInstance = StripeConnect.init({ // This is a placeholder - it should be replaced with your publishable API key. // Sign in to see your own test API key embedded in code samples. // Don’t submit any personally identifiable information in requests made with this key. publishableKey:
, fetchClientSecret: fetchClientSecret, }); const payments = stripeConnectInstance.create('payments'); document.body.appendChild(payments); };"pk_test_TYooMQauvdEDq54NiTphI7jx"
Nutzerauthentifizierung in eingebetteten Connect-Komponenten
Für eingebettete Connect-Komponenten ist in der Regel keine Nutzerauthentifizierung erforderlich. In einigen Fällen müssen sich die verbundenen Konten im Rahmen der eingebetteten Connect-Komponenten jedoch mit ihrem Stripe-Konto anmelden, um die erforderlichen Funktionen bereitzustellen (so müssen z. B. den juristischen Personen im Fall einer Komponente des Konto-Onboardings Informationen zugeschrieben werden.
Bei der Authentifizierung wird ein Pop-up-Fenster in einem Stripe-Fenster angezeigt. Das verbundene Konto muss sich authentifizieren, bevor es seinen Workflow fortsetzen kann.
Die folgenden Komponenten erfordern die Authentifizierung verbundener Konten in bestimmten Szenarien:
- Konto-Onboarding
- Kontoverwaltung
- Salden
- Auszahlungen
- Benachrichtigungsbanner
- Finanzkonto
- Liste von Issuing-Karten
Andere Komponenten erfordern möglicherweise eine Authentifizierung innerhalb der Komponente, nachdem sie ursprünglich gerendert wurden. Die Authentifizierung für diese Komponenten und Szenarien ist für verbundene Konten erforderlich, bei denen Stripe für die Erfassung aktualisierter Informationen verantwortlich ist, wenn sich die Anforderungen ändern. Für verbundene Konten, bei denen Sie dafür verantwortlich sind, aktualisierte Informationen zu erfassen, wenn Anforderungen fällig sind oder sich ändern, wird die Stripe-Authentifizierung von der Account-Session-Funktion disable_stripe_user_authentication gesteuert. Wir empfehlen die Implementierung von 2FA oder gleichwertigen Sicherheitsmaßnahmen als Best Practice. Bei Kontokonfigurationen, die diese Funktion unterstützen, wie zum Beispiel „Nutzerspezifisch“, übernehmen Sie die Haftung für verbundene Konten, wenn diese keine negativen Guthaben begleichen können.