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

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 を設定するクライアント

npm パッケージをインストールして、Connect.js をモジュールとして使用します。

Command Line
npm install --save @stripe/connect-js

Connect.js を読み込み初期化するクライアント

公開可能キーと、サーバー上に作成した新しいエンドポイントを呼び出してクライアントシークレットを取得する機能を指定して、loadConnectAndInitialize を呼び出します。返された StripeConnectInstance を使用して、埋め込みコンポーネントを作成します。Connect.js を初期化すると、DOM に対してコンポーネントのマウントとマウント解除をいつでも行うことができます。これは React や Vue ポータル内で表示されるすべての要素に適用できます。

コンポーネントを作成するには、上記で作成した StripeConnectInstance で create を呼び出します。これにより、Connect.js が登録して DOM を自動的に Stripe に接続するために使用するカスタム要素が作成されます。その後、この要素を DOM に append できます。

payments を指定して create を呼び出したら、結果を DOM に追加して、決済 UI を表示します。

サポートされている埋め込みコンポーネントの一覧をご覧ください →

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 はその他のスタイルの上書きをサポートしていません。

index.js
const fetchClientSecret = async () => {
  const response = await fetch('/account_session');
  const {client_secret: clientSecret} = await response.json();
  return clientSecret;
}

const stripeConnectInstance = loadConnectAndInitialize({
  publishableKey: "pk_test_TYooMQauvdEDq54NiTphI7jx"
,
  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",
    },
  },
});

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 メソッドを呼び出します。

index.js
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 を取得し、セッションを更新します。追加のパラメーターを渡す必要はありません。

index.js
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 の埋め込みコンポーネントが無効になります。

index.js
// 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`

読み込みエラーを処理する

コンポーネントの読み込みに失敗した場合、埋め込みコンポーネントに読み込みエラーハンドラを指定することで、失敗に対応できます。失敗の原因に応じて、読み込みエラーハンドラは複数回呼び出されます。読み込みエラーハンドラによってトリガーされるロジックは、べき等でなければなりません。

Method	Description	Variables
`setOnLoadError`	The component executes this callback function when a load failure occurs.	`loadError.error`: See the load error object `loadError.elementTagName`: The name of HTML tag used to render the component in the browser

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`	See types of load failures	`authentication_error`
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_error.

Type	Description
`api_connection_error`	Failure to connect to Stripe’s API
`authentication_error`	Failure to perform the authentication flow within Connect embedded components
`account_session_create_error`	Account session creation failed
`invalid_request_error`	Request failed with an 4xx status code, typically caused by platform configuration issues
`rate_limit_error`	Request failed because an abnormal request rate was detected
`api_error`	API errors covering any other type of problem, such as a temporary problem with Stripe’s servers

埋め込みコンポーネントの表示を検出する

コンポーネントが作成された後は、コンポーネントの Javascript がブラウザーに読み込まれ、解析されるまで、UI はユーザーに表示されません。これにより、コンポーネントが読み込みの完了後にポップアップ表示される場合があります。これを回避するには、コンポーネントが作成される前に独自の読み込み UI を表示し、コンポーネントが表示された後に UI を非表示にします。埋め込みコンポーネントはすべて、ユーザーに UI が表示される直前に呼び出されるコールバック関数を受け入れることができます。

Method	Description	Variables
`setOnLoaderStart`	The component executes this callback function before any UI is displayed to the user.	`event.elementTagName`: The name of HTML tag used to render the component in the browser

フロントエンドの 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 を呼び出します。

index.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: "pk_test_TYooMQauvdEDq54NiTphI7jx"
,
      fetchClientSecret: fetchClientSecret,
    });

  const payments = stripeConnectInstance.create('payments');
  document.body.appendChild(payments);
};

Connect の埋め込みコンポーネントでのユーザー認証

Connect の埋め込みコンポーネントでは通常、ユーザー認証を必要としません。場合によっては、Connect の埋め込みコンポーネントでは、必要な機能 (アカウント登録コンポーネントで、アカウントの法人情報を記述するなど) を提供するために、連結アカウントが Stripe アカウントでサインインする必要があります。

認証には、Stripe が所有するウィンドウへのポップアップが含まれます。連結アカウントは、ワークフローを続行する前に認証する必要があります。

以下のコンポーネントは、特定のシナリオで連結アカウントにより認証される必要があります。

他のコンポーネントでは、最初にレンダリングされた後にコンポーネント内での認証が必要になることがあります。これらのコンポーネントとシナリオの認証は、要件が変更されたときに Stripe が更新情報を収集する責任を負う、連結アカウントに必要です。要件が期限に達したか変更された場合に、更新情報を収集する責任を負う連結アカウントの場合、Stripe 認証は、disable_stripe_user_authentication アカウントセッション機能によって制御されます。ベストプラクティスとして、2 段階認証または同等のセキュリティ対策を導入することをお勧めします。Custom など、この機能をサポートするアカウント設定では、連結アカウントがマイナス残高を返済できない場合、お客様は連結アカウントの責任を負うものとします。

注