Connect の埋め込みコンポーネントの使用を開始する
Connect の埋め込みコンポーネントを使用して、連結アカウントのダッシュボード機能をウェブサイトに追加します。これらのライブラリとサポートする API を使用することで、ダッシュボードから Stripe 製品に直接アクセスできる許可をユーザーに付与できます。
より実践的なガイドについては、Connect の埋め込みコンポーネント導入のクイックスタートをご覧ください。こちらからサンプルの実装をダウンロードすることもできます。Connect の埋め込みコンポーネントのデザインをカスタマイズするには、StripeConnectInstance
を初期化する際に appearance
オプションを使用します。デザインパラメーターの全リストをご覧ください。
Connect.js を初期化するクライアント側サーバー側
Stripe は、AccountSession を使用して、API アクセスを連結アカウントに委任する意図を表します。
AccountSessions API は client secret を返し、連結アカウントに対する API コールを行う場合と同じように、ウェブクライアントの埋め込みコンポーネントが連結アカウントのリソースにアクセスできるようにします。
AccountSession を作成する サーバー
1 ページのアプリケーションでは、クライアントがサーバーへのリクエストを開始して、アカウントセッションを取得します。client secret をブラウザーに返す新しいエンドポイントを、サーバー側で作成できます。
Connect.js を設定する クライアント
Connect.js を読み込み初期化する クライアント
公開可能キーと、サーバー上に作成した新しいエンドポイントを呼び出してクライアントシークレットを取得する機能を指定して、loadConnectAndInitialize
を呼び出します。返された StripeConnectInstance
を使用して、埋め込みコンポーネントを作成します。Connect.js を初期化すると、DOM に対してコンポーネントのマウントとマウント解除をいつでも行うことができます。これは React や Vue ポータル内で表示されるすべての要素に適用できます。
Connect.js を設定するクライアント側
クライアントの loadConnectAndInitialize
メソッドでは、Connect.js の設定に使用できるオプションが複数存在します。
オプション | 説明 | |
---|---|---|
publishableKey | 組み込みの公開可能キー。 | 必須 |
fetchClientSecret | /v1/account_sessions によって返される client secret を取得する関数。これにより、StripeConnectInstance に対してアクセスを委任するアカウントを指定します。この関数は、セッションの有効期限が切れたときに、client secret 関数を取得してセッションを更新するためにも使用されます。 | 必須 |
appearance | Connect の埋め込みコンポーネントのデザインをカスタマイズするオブジェクト。 | 任意 |
locale | Connect の埋め込みコンポーネントが使用するロケールを指定するためのパラメーター。ロケールのデフォルトはブラウザーの言語です。直接的には対応していない言語が渡された場合、妥当な代替の言語が使用されます (たとえば、fr-be が渡された場合は fr-fr になります)。 | 任意 |
fonts | StripeConnectInstance から作成されるどの埋め込みコンポーネントでも使用できるカスタムフォントの配列。フォントは、CssFontSource オブジェクトまたは CustomFontSource オブジェクトとして指定できます。 | 任意 |
Connect の埋め込みコンポーネントのデザインをカスタマイズする
Connect の埋め込みコンポーネントのデザインをカスタマイズできるオプションセットをご用意しています。これらのカスタマイズは、Stripe デザインシステムのボタン、アイコン、その他のアクセントに作用します。
StripeConnectInstance
を初期化する際に、appearance
オブジェクトに値を渡して、これらのオプションを設定できます。Connect 埋め込みコンポーネントでスタイルを変更する際は、Connect.js オプションのみを使用できます。Connect の埋め込みコンポーネントのフォントファミリーと背景色は、CSS セレクターで上書きできますが、Stripe はその他のスタイルの上書きをサポートしていません。
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"
fonts
オブジェクト
stripeConnect.initialize
の fonts
オブジェクトの配列は、CssFontSource オブジェクトまたは CustomFontSource オブジェクトのいずれかになります。
自身のページでカスタムのフォント (.woff
または .tff
ファイル) を使用している場合、Connect の埋め込みコンポーネントを初期化する際にこれらのファイルを指定する必要があります。そうすることで、Connect 埋め込みコンポーネントはこれらのフォントを正しく表示できるようになります。ファイルは以下のように指定します。
CssFontSource
このオブジェクトを使用して、StripeConnectInstance
作成時にカスタムフォントを定義するスタイルシート URL を渡します。CssFontSource オブジェクトを使用する場合、CSP 設定で CssFontSource として CSS ファイル URL に関連付けられたドメインの取得を許可する必要があります。
名前 | タイプ | 値の例 |
cssSrc | 文字列 required | https://fonts.googleapis.com/css?family=Open+Sans |
@font-face の定義が含まれる CSS ファイルを指し示す相対または絶対 URL。コンテンツセキュリティポリシー (CSP) を使用すると、追加のディレクティブが必要になる場合があります。 |
CustomFontSource
このオブジェクトを使用して、StripeConnectInstance
の作成時にカスタムフォントを渡します。
名前 | タイプ | 値の例 |
family | 文字列 required | Avenir |
フォントに指定する名前。 | ||
src | 文字列 required | url(https://my-domain.com/assets/avenir.woff) |
カスタムフォントファイルを指し示す有効な src 値。多くの場合、これはサフィックスが .woff 、.otf 、.svg のファイルへのリンクです。 | ||
display | 文字列 optional | auto |
有効な font-display 値。 | ||
style | 文字列 optional | normal |
normal 、italic 、oblique のいずれか。 | ||
unicodeRange | 文字列 optional | U+0-7F |
有効な unicode-range 値。 | ||
weight | 文字列 optional | 400 |
有効な font-weight。これは数字ではなく、文字列であることに注意してください。 |
appearance
オブジェクト
loadConnectAndInitialize
の appearance
オブジェクトでは、以下のオプションのプロパティーを使用できます。
名前 | タイプ | 値の例 |
overlays | ‘dialog’ (デフォルト) | ‘drawer’ | dialog |
Connect.js デザインシステム全体で使用されるオーバーレイのタイプ。ダイアログまたはドロワーのいずれかに設定してください。 | ||
variables | オブジェクト | {colorPrimary: "#0074D4"} |
appearance 変数の全リストをご覧ください。 |
初期化後に Connect の埋め込みコンポーネントを更新する
update
メソッドは、初期化後の Connect の埋め込みコンポーネントの更新に対応しています。これは、実行時に (ページを再表示せずに) デザインオプションを切り替える際利用できます。これを実行するには、次のように initialize
で作成した stripeConnectInstance
オブジェクトを使用し、これに対して、update
メソッドを呼び出します。
stripeConnectInstance.update({ appearance: { variables: { colorPrimary: "#FF0000", }, }, locale: 'en-US', });
注
すべてのオプションを更新できるわけではありません (fonts
など)。このメソッドに使用可能なオプションは、initialize
に対して提供されるオプションの一部です。appearance
と locale
の更新に対応します。
幅と高さ
Connect の埋め込みコンポーネントは、通常の block
HTML 要素と同様に動作します。デフォルトでは、親 HTML 要素の width
をそのまま使用し、その中にレンダリングされるコンテンツに合わせて、高さを調整します。HTML の親の width
を指定することで、Connect の埋め込みコンポーネントの width
を制御できます。height
は、レンダリングされるコンテンツによって変わるため、直接制御できませんが、他の HTML block
要素と同様、maxHeight
と overflow: scroll
を使用して高さを制限できます。
認証
Connect の埋め込みコンポーネントではアカウントセッションとユーザー認証情報を管理する API を提供しています。
client secret を更新する
長時間実行されるセッションでは、最初に指定された client secret からのセッションが期限切れになる場合があります。期限切れになると、fetchClientSecret
を自動的に使用して新しい client secret を取得し、セッションを更新します。追加のパラメーターを渡す必要はありません。
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, });
ログアウト
ユーザーがアプリからログアウトした後、stripeConnectInstance
で logout
を呼び出し、関連するアカウントセッションオブジェクトを破棄することをお勧めします。こうすると、その stripeConnectInstance
にリンクするすべての Connect の埋め込みコンポーネントが無効になります。
// Call this when your user logs out stripeConnectInstance.logout();
CSP と HTTP ヘッダーの要件
ウェブサイトでコンテンツセキュリティポリシーを実装している場合は、以下のルールを追加してポリシーを更新する必要があります。
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)
CSS ファイルを使用して Connect の埋め込みコンポーネントで使用するウェブフォントを読み込む場合は、その URL がお客様の connect-src CSP ディレクティブで許可されている必要があります。
一定の HTTP レスポンスヘッダーを設定することで、Connect 埋め込みコンポーネントのすべての機能が有効化されます。
Cross-Origin-Opener-Policy
,unsafe-none
。注: これはヘッダーのデフォルト値であるため、このヘッダーを設定しなくても機能します。
サポートされるブラウザー
Stripe では、Stripe ダッシュボードが現在サポートしているのと同じブラウザーをサポートしています。
- Chrome と Firefox の最新の 20 のメジャーバージョン
- Safari と Edge の最新の 2 つのメジャーバージョン
- iOS のモバイル Safari の最新の 2 つのメジャーバージョン
Connect 埋め込みコンポーネントは、Webview ではサポートされていません。スタンドアロンのブラウザーでのみサポートされます。
対応している言語
Connect の埋め込みコンポーネントは、次の言語でご利用いただけるように翻訳されています。
言語 | ロケールコード |
---|---|
ブルガリア語 (ブルガリア) | bg-BG |
簡体字中国語 | zh-Hans |
繁体字中国語 (香港) | zh-Hant-HK |
繁体字中国語 (台湾) | zh-Hant-TW |
クロアチア語 (クロアチア) | hr-HR |
チェコ語 (チェコ共和国) | cs-CZ |
デンマーク語 (デンマーク) | da-DK |
オランダ語 (オランダ) | nl-NL |
英語 (オーストラリア) | en-AU |
英語 (インド) | en-IN |
英語 (アイルランド) | en-IE |
英語 (ニュージーランド) | en-NZ |
英語 (シンガポール) | en-SG |
英語 (イギリス) | en-GB |
英語 (アメリカ) | en-US |
エストニア語 (エストニア) | et-EE |
フィリピン語 (フィリピン) | fil-PH |
フィンランド語 (フィンランド) | fi-FI |
フランス語 (カナダ) | fr-CA |
フランス語 (フランス) | fr-FR |
ドイツ語 (ドイツ) | de-DE |
ギリシャ語 (ギリシャ) | el-GR |
ハンガリー語 (ハンガリー) | hu-HU |
インドネシア語 (インドネシア) | id-ID |
イタリア語 (イタリア) | it-IT |
日本語 (日本) | ja-JP |
韓国語 (韓国) | ko-KR |
ラトビア語 (ラトビア) | lv-LV |
リトアニア語 (リトアニア) | lt-LT |
マレー語 (マレーシア) | ms-MY |
マルタ語 (マルタ) | mt-MT |
ノルウェーブークモール語 (ノルウェー) | nb-NO |
ポーランド語 (ポーランド) | pl-PL |
ポルトガル語 (ブラジル) | pt-BR |
ポルトガル語 (ポルトガル) | pt-PT |
ルーマニア語 (ルーマニア) | ro-RO |
スロバキア語 (スロバキア) | sk-SK |
スロベニア語 (スロベニア) | sl-SI |
スペイン語 (アルゼンチン) | es-AR |
スペイン語 (ブラジル) | es-BR |
スペイン語 (中南米) | es-419 |
スペイン語 (メキシコ) | es-MX |
スペイン語 (スペイン) | es-ES |
スウェーデン語 (スウェーデン) | sv-SE |
タイ語 (タイ) | th-TH |
トルコ語 (テュルキエ) | tr-TR |
ベトナム語 (ベトナム) | vi-VN |
フロントエンドの npm パッケージなしで導入する
Stripe の javascript と React コンポーネントのラッパーを導入することをお勧めします。これにより、Connect の埋め込みコンポーネントを簡単に読み込み、当社がサポートするインターフェイスの TypeScript 定義を得ることができます。貴社のビルドシステムが現在、パッケージへの依存をサポートしていない場合、このパッケージなしで導入することができます。
自社サイトの各ページの <head>
に、Connect.js スクリプトタグを手動で追加します。
<!-- Somewhere in your site's <head> --> <script src="https://connect-js.stripe.com/v1.0/connect.js" async></script>
NPT なしで Connect.js を使用する
Connect.js が読み込みを完了すると、グローバル window 変数 StripeConnect
が初期化され、 定義されている場合は StripeConnect.onLoad
が呼び出されます。Connect.js を安全に初期化するには、onload
関数を設定し、loadConnectAndInitialize
と同じ Connect.js options を指定して StripeConnect.init
を呼び出します。
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"
Connect の埋め込みコンポーネントでのユーザー認証
通常、Connect の埋め込みコンポーネントはユーザー認証を必要とせず、設定された機能を直接提供します。場合によっては、Connect の埋め込みコンポーネントでは、ユーザーに Stripe アカウントへのサインインを求めます。これは、コンポーネントが必要とする機能 (アカウント登録コンポーネントで、アカウントの法人情報を記述するなど) を実行するために必要になります。
認証には、Stripe が所有するウィンドウへのポップアップが含まれます。ユーザーがポップアップで認証を完了すると、それは閉じられ、ユーザーはワークフローを続行できます。
アカウント登録とアカウント管理の各コンポーネントでは、起動時に認証が必要です。その他のコンポーネントでは、最初のレンダリング後にコンポーネント内でのユーザー認証が必要になる場合があります。これらのコンポーネントとシナリオでの認証は、Connect のすべてのアカウントタイプで必要になりますが、プラットフォームが Stripe ダッシュボード内で外部口座の収集を設定していない Custom アカウントのみ例外になります。