Mit den in Connect eingebetteten Komponenten loslegen
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:
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_sessions 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 von eingebetteten Connect-Komponenten verwendet wird. Das Gebietsschema ist standardmäßig auf die Browser-Sprache eingestellt. Wenn die übergebene Sprache nicht direkt unterstützt wird, wird eine passende Alternative verwendet (zum Beispiel könnte fr-be auf fr-fr zurückgreifen). | 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 fonts
-Objekt
Das fonts
-Objekt in stripeConnect.initialize
akzeptiert ein Array von CssFontSource- oder CustomFontSource-Objekten.
Wenn Sie auf Ihrer Seite nutzerdefinierte Schriftarten verwenden (d. h. .woff
- oder .tff
-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.googleapis.com/css?family=Open+Sans |
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.com/assets/avenir.woff) |
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 .woff , .otf oder .svg . | ||
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 appearance
-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
. Hinweis: Dies ist der Standardwert der Kopfzeile, daher funktioniert es, auch ohne die Kopfzeile festzulegen.
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 in Webansichten nicht unterstützt, sondern nur in eigenständigen Browsern.
Unterstützte Sprachen
Wir haben eingebettete Connect-Komponenten für die folgenden Sprachen lokalisiert:
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 |
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.onLoad
aufgerufen, sofern von Ihnen definiert. Sie können Connect.js sicher initialisieren, indem Sie eine onload
-Funktion einrichten und StripeConnect.init
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. Die konfigurierten Funktionen sind direkt verfügbar. In einigen Fällen müssen sich Nutzer/innen im Rahmen der eingebetteten Connect-Komponenten jedoch mit ihrem Stripe-Konto anmelden, um die für diese Komponente erforderlichen Funktionen auszuführen (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. Wenn Nutzer/innen die Authentifizierung in diesem Pop-up-Fenster abgeschlossen haben, wird dieses geschlossen und der Ablauf kann fortgesetzt werden.
Um die Komponenten für das Konto-Onboarding und die Kontoverwaltung zu starten, ist eine Authentifizierung erforderlich. Andere Komponenten erfordern möglicherweise nach der ersten Anzeige eine Nutzerauthentifizierung innerhalb der Komponente. Die Authentifizierung in diesen Komponenten und Szenarien ist für alle Connect-Kontotypen erforderlich, mit Ausnahme von Custom-Konten, bei denen die Plattform die externe Kontoerfassung nicht im Stripe-Dashboard konfiguriert hat.