Connect の埋め込みコンポーネントの使用を開始する
ダッシュボードの機能をウェブサイトに埋め込む方法をご紹介します。
Connect の埋め込みコンポーネントを使用して、連結アカウントのダッシュボード機能をウェブサイトに追加します。これらのライブラリ、およびそのサポート API を使用することで、ダッシュボードやモバイルアプリケーションから Stripe プロダクトに直接アクセスできる許可をユーザーに付与できます。
より実践的なガイドについては、Connect の埋め込みコンポーネント導入のクイックスタートをご覧ください。こちらからサンプルの実装をダウンロードすることもできます。Connect の埋め込みコンポーネントのデザインをカスタマイズするには、StripeConnectInstance
を初期化する際に appearance
オプションを使用します。デザインパラメーターの全リストをご覧ください。
Connect.js を初期化するクライアント側サーバー側
Stripe は AccountSession を使用して、API アクセスを連結アカウントに委任する意図を表します。
AccountSessions API は client secret を返し、連結アカウントに対して API コールを行うときと同じように、埋め込みコンポーネントが連結アカウントのリソースにアクセスできるようにします。
AccountSession を作成する サーバー
1 ページのアプリケーションでは、クライアントがサーバーへのリクエストを開始して、アカウントセッションを取得します。client secret をブラウザーに返す新しいエンドポイントを、サーバー側で作成できます。
Create Account Session API
Create Account Session API は、Connect 埋め込みコンポーネントのコンポーネントと機能へのアクセスを決定します。Stripe は、アカウントセッションに対応するすべてのコンポーネントにこれらのパラメーターを適用します。サイトが複数のユーザーの役割をサポートしている場合は、そのアカウントセッションで有効になっているコンポーネントと機能が現在のユーザーの役割に対応していることを確認してください。たとえば、返金管理はサイトの管理者に対してのみ有効にでき、他のユーザーに対しては有効にできません。ユーザーの役割によるアクセスを確実に適用するには、サイトのユーザーの役割をアカウントセッションコンポーネントにマッピングする必要があります。
Connect.js を設定する クライアント
次の例に示すように、npm を使用して Connect.js を設定することをお勧めしますが、npm を使用せずに設定することもできます。
Connect.js を読み込んで初期化する クライアント
公開可能キーと、サーバー上に作成した新しいエンドポイントを呼び出してクライアントシークレットを取得する機能を指定して、loadConnectAndInitialize
を呼び出します。返された StripeConnectInstance
を使用して、埋め込みコンポーネントを作成します。Connect.js を初期化すると、DOM に対してコンポーネントのマウントとマウント解除をいつでも行うことができます。これは React や Vue ポータル内で表示されるすべての要素に適用できます。
Configure Connect.jsクライアント側
クライアントの loadConnectAndInitialize
メソッドは、Connect.js を設定するさまざまなオプションを受け取ります。
オプション | 説明 | |
---|---|---|
publishableKey | 構築しているシステムの公開可能キー。 | 必須 |
fetchClientSecret | /v1/account_ によって返された client secret を取得する関数。これにより、アクセスを委任するアカウントを StripeConnectInstance に指示します。この関数は、有効期限が切れたときにセッションを更新する client secret 関数を取得するためにも使用されます。fetchClientSecret は常に新しいアカウントセッションを作成し、新しい client_ を返します。 | 必須 |
appearance | Connect 埋め込みコンポーネントのデザインをカスタマイズするオブジェクト。 | オプション |
locale | Connect 埋め込みコンポーネントが使用するロケールを指定するパラメーター。ロケールのデフォルトはブラウザーの言語です。指定されたロケールが直接は対応していない場合は、妥当な代替言語を使用します (たとえば、fr-be は fr-fr に戻る可能性があります)。サポートされているロケールのリストについては、各地域への適応を参照してください。 | オプション |
fonts | StripeConnectInstance から作成された埋め込みコンポーネントで使用できるカスタムフォントの配列。フォントは、CssFontSource または CustomFontSource オブジェクトとして指定できます。 | オプション |
Connect 埋め込みコンポーネントのデザインをカスタマイズする
埋め込みコンポーネント Figma UI ツールキットには、すべてのコンポーネント、一般的なパターン、サンプルアプリケーションが含まれています。これを使用して、ウェブサイトに埋め込まれた UI を可視化してデザインできます。
Stripe は、Connect 埋め込みコンポーネントのデザインをカスタマイズするための一連のオプションを提供しています。これらをカスタマイズすると、デザインシステムのボタン、アイコン、その他のアクセントに影響します。
必要なポップアップ
ユーザー認証など、埋め込みコンポーネントの一部の動作はポップアップに表示する必要があります。埋め込みコンポーネントをカスタマイズして、このようなポップアップを表示することはできません。
これらのオプションは、StripeConnectInstance
の初期化時に、Appearance を appearance
オブジェクトに渡すことで設定できます。Connect 埋め込みコンポーネントのスタイルを変更するのに使用できるのは、Connect.js のオプションのみです。Connect 埋め込みコンポーネントのフォントファミリーと背景色は、親の HTML コンテナから継承されます。他のすべてのオプションを明示的に設定する必要があります。
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.
の fonts
オブジェクトは、CssFontSource または CustomFontSource オブジェクトの配列を受け取ります。
ページでカスタムフォント (.
ファイルや .
ファイルなど) を使用する場合は、Connect 埋め込みコンポーネントの初期化時にフォントファイルを指定する必要があります。これにより、Connect 埋め込みコンポーネントでフォントを適切にレンダリングできます。ファイルは次のように指定できます。
CssFontSource
StripeConnectInstance
の作成時にカスタムフォントを定義するスタイルシートの URL を渡すには、このオブジェクトを使用します。CssFontSource
オブジェクトでは、CSP 設定 で、CssFontSource として指定された CSS ファイルの URL に関連付けられたドメインの取得を許可する必要があります。
名前 | タイプ | 値の例 |
cssSrc | 文字列 required | https://fonts. |
@font-face 定義を持つ CSS ファイルを指す相対 URL または絶対 URL。ファイルは https でホストされている必要があります。コンテンツセキュリティポリシー(CSP) を使用する場合、ファイルに追加のディレクティブが必要になることがあります。 |
CustomFontSource
StripeConnectInstance
の作成時にカスタムフォントを渡すには、このオブジェクトを使用します。
名前 | タイプ | 値の例 |
family | 文字列 required | Avenir |
フォントに付ける名前。 | ||
src | 文字列 required | url(https://my-domain. |
カスタムフォントファイルを指す有効な src 値。これは (必ずではありませんが) 通常は . 、. 、または . というサフィックスが付いたファイルへのリンクです。ファイルは https でホストされている必要があります。 | ||
display | 文字列 optional | auto |
有効な font-display 値。 | ||
style | 文字列 optional | normal |
normal 、italic 、oblique のいずれか。 | ||
unicodeRange | 文字列 optional | U+0-7F |
有効な unicode-range 値。 | ||
weight | 文字列 optional | 400 |
有効な font-weight。これは文字列であり、数値ではありません。 |
初期化後に Connect 埋め込みコンポーネントを更新する
update
メソッドは、初期化後の Connect 埋め込みコンポーネントの更新に対応しています。これを使用して、実行時に (ページを更新せずに) デザインオプションを切り替えることができます。これを行うには、initialize
で作成したのと同じ stripeConnectInstance
オブジェクトを使用し、そのオブジェクトに対して update
メソッドを呼び出します。
stripeConnectInstance.update({ appearance: { variables: { colorPrimary: "#FF0000", }, }, locale: 'en-US', });
注
すべてのオプション (fonts
など) を更新できるわけではありません。このメソッドで対応しているオプションは、initialize
で提供されているオプションのサブセットです。そうすることによって、appearance
と locale
の更新に対応しています。
幅と高さ
Connect 埋め込みコンポーネントは、通常の block
HTML 要素と同様に動作します。デフォルトでは、親 HTML 要素の width
の 100% に設定し、内部にレンダリングされるコンテンツに応じて高さを大きくします。HTML の親の width
を指定することで、Connect 埋め込みコンポーネントの width
を制御できます。height
はレンダリングされるコンテンツによって変わるため、直接制御することはできませんが、他の HTML block
要素と同じように、maxHeight
と overflow: scroll
で高さを制限できます。
認証
Stripe は、Connect 埋め込みコンポーネントでアカウントセッションとユーザー認証情報を管理するための一連の API を提供しています。
Client Secret を更新する
長時間実行されるセッションでは、最初に提供された Client Secret によるセッションが期限切れになることがあります。有効期限が切れると、Stripe は自動的に 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', { method: "POST" }); 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
。これ (unsafe-none
) はヘッダーのデフォルト値であるため、このヘッダーを設定しなくても機能します。same-origin
など他の値を設定すると、Connect 埋め込みコンポーネントのユーザー認証が機能しなくなります。
サポートされているブラウザー
Stripe では、Stripe ダッシュボードが現在対応しているブラウザーと同じ組み合わせに対応しています。
- Chrome と Firefox の最新の 20 個のメジャーバージョン
- Safari と Edge の最新の 2 つのメジャーバージョン
- iOS モバイル Safari の最新の 2 つのメジャーバージョン
Connect 埋め込みコンポーネントはウェブブラウザーにのみ対応しており、モバイルアプリケーションやデスクトップアプリケーションの中の埋め込みウェブビューでは使用できません。
各地域への適応
Connect.js を初期化するときに、locale
パラメーターを渡すことができます。埋め込みコンポーネントのロケールをウェブサイトのロケールに合わせるには、ウェブサイトでレンダリングする UI のロケールを locale
パラメーターに渡します。
locale
パラメーターのデフォルト値は、ブラウザーに設定されているロケールによって決まります。指定されたロケールが直接は対応していない場合は、妥当な代替言語が使用されます (たとえば、fr-be
は fr-fr
に戻る可能性があります)。
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 |
読み込みエラーを処理する
コンポーネントの読み込みに失敗した場合、埋め込みコンポーネントに読み込みエラーハンドラを指定することで、失敗に対応できます。失敗の原因に応じて、読み込みエラーハンドラは複数回呼び出されます。読み込みエラーハンドラによってトリガーされるロジックは、べき等でなければなりません。
load error
オブジェクト
読み込みエラーが発生するたびに、以下のプロパティを持つ error
オブジェクトが読み込みエラーハンドラに渡されます。
氏名 | タイプ | 値の例 |
type | 読み込み障害の種類を参照してください。 | authentication_ |
エラーの種類 | ||
message | string | undefined | Failed to fetch account session |
エラーの詳しい説明 |
読み込み障害の種類
コンポーネントの読み込みに失敗すると、障害のタイプが検出され、以下のいずれかのタイプにマッピングされます。読み込みエラーのタイプを特定できない場合は、api_
としてマークされます。
タイプ | 説明 |
---|---|
api_ | Stripe の API への接続の失敗 |
authentication_ | Connect 埋め込み型コンポーネント内で認証フローを実行しない |
account_ | アカウントセッションの作成に失敗しました |
invalid_ | リクエストが 4xx ステータスコードで失敗しました。これは通常、プラットフォーム設定の問題が原因で発生します |
rate_ | 異常なリクエスト率が検出されたため、リクエストが失敗しました |
api_ | Stripe のサーバーの一時的な問題など、その他のタイプの問題を対象とする API エラー |
埋め込みコンポーネントの表示を検出する
コンポーネントが作成された後は、コンポーネントの javascript がブラウザーに読み込まれて解析されるまで、UI はユーザーに表示されません。そのため、コンポーネントが読み込みの完了後にポップアップ表示されることがあります。これを回避するには、コンポーネントが作成される前に独自の読み込み UI を表示し、コンポーネントが表示された後に UI が非表示になるよう設定します。すべての埋め込みコンポーネントは、UI (読み込みインジケーターを含む) がユーザーに表示されたときに即座に呼び出されるコールバック関数を受け入れることができます。
npm を使用せずに Connect.js を使用する
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>
Connect.js は読み込みが完了すると、グローバルウィンドウ変数 StripeConnect
を初期化し、定義されている場合は StripeConnect.
を呼び出します。onload
関数を設定し、loadConnectAndInitialize
と同じ Connect.js オプションを指定して StripeConnect.
を呼び出すことで、Connect.js を安全に初期化できます。loadConnectAndInitialize
によって返されるインスタンスを使用する方法と同じように、init
によって返される Connect インスタンスを使用して、HTML + JS の実装で埋め込みコンポーネントを作成できます。
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 が更新情報を収集する責任を負う場合、認証は必須です。要件が期限切れになったときや変更されたときに最新情報を収集する責任を負う連結アカウント (Custom アカウントなど) の場合、Stripe の認証はアカウントセッション機能 (disable_stripe_user_authentication) によって制御されます。ベストプラクティスとして、2 段階認証または同等のセキュリティ対策を導入することをお勧めします。Custom など、この機能をサポートするアカウント設定では、連結アカウントがマイナス残高を返済できない場合、お客様がそのアカウントに対する責任を負うことになります。
認証が必要なコンポーネント
認証には、Stripe が所有するウィンドウへのポップアップが含まれます。連結アカウントは、ワークフローを続行する前に認証する必要があります。
以下のコンポーネントは、特定のシナリオで連結アカウントにより認証される必要があります。
パフォーマンスのベストプラクティス
Connect 埋め込みコンポーネントの読み込み時間をできるだけ短くしたい場合は、次の推奨事項をお試しください。
- フローの初期の段階で
loadConnectAndInitialize
を呼び出します。 - 単一の接続インスタンスを作成する:セッションごとに 1 回だけ
loadConnectAndInitialize
を呼び出して、単一の接続インスタンスを作成します。その後、そのインスタンスを再利用して、複数のコンポーネントを作成・管理することができます。このとき、コンポーネントごとに単一の接続インスタンスを作成したり、セッションごとに複数の接続インスタンスを作成したりするミスがよく起こります。その結果、余分なリソース消費と API リクエストが発生します。React を使用している場合は、状態管理ライブラリまたは React コンテキストを使用してこのインスタンスを管理できます。 - 最新バージョンの適切な SDK を使用する:最新バージョンの connect-js または react-connect-js npm パッケージ SDK を使用します。これらの SDK は、埋め込みコンポーネントを初期化してパフォーマンスの最大化を図ります。SDK はバージョンを重ねるごとにパフォーマンスが改善されているため、古いバージョンを使用している場合はアップグレードすることをお勧めします。
connect.
スクリプトをできるだけ早くフローに読み込みます。HTML のjs head
にこのスクリプトを含めることで、スクリプトをすぐに読み込ませることができます。npm パッケージ SDK のデフォルトの動作を応用することもできます。この場合、ページの Javascript が読み込まれたときにスクリプトの読み込みが開始します。