Extension SDK API リファレンス

Extension SDK API の、すべてのフィールド、タイプ、説明のインデックス。

UI 拡張機能は、アプリのユーザーと Stripe ダッシュボードのエコシステムと対話するための context プロパティーとユーティリティ関数にアクセスできます。このページでは、これらの値と関数について説明します。

プロパティー

ビューには、拡張機能が表示される場所のコンテキストに使用できるプロパティが渡されます。ビューは、これらのプロパティのすべてまたは一部を引数として使用できます。これらのタイプは、ExtensionContextValue です。

import type {ExtensionContextValue} from '@stripe/ui-extension-sdk/context';

const ExampleApp = ({ userContext, environment, oauthContext, appContext}: ExtensionContextValue) => {
  ...
}

ユーザーコンテキスト

userContext プロパティーには、アプリを使用するエンドユーザーに関するデータが示され、以下のフィールドが含まれます。

フィールド	タイプ	例
name	文字列	Jenny Rosen
アプリユーザーの名前
account.country	文字列	UK
アプリユーザーの国
account.id	文字列	acct_1032D82eZvKYlo2C
アプリユーザーのアカウント ID
account.name	文字列	Jenny’s Llama Emporium
Stripe アカウントの名前
職種	配列<RoleDefinition>	none
アクティブユーザーのユーザーの役割のリスト。
locale	文字列	en-GB
アプリユーザーのシステム言語 ID

RoleDefinition

役割の定義には以下のフィールドがあります。

フィールド名	タイプ	例
タイプ	‘builtIn’ \| ‘custom’	builtIn
役割の種類を指定します。カスタム役割はプライベートアプリにのみ使用できます。
name	文字列	開発者
ユーザーの役割の名前です。

環境

environment プロパティーには、ユーザーが表示しているページに関するデータが示され、以下のフィールドが含まれます。

フィールド	タイプ	例
viewportID	文字列	stripe.dashboard.payment.list
ビューを表示する現在のビューポート
mode	‘live’ \| ‘test’	live
現在のページの Stripe API モード
objectContext.id	文字列	ch_3L0pjB2eZvKYlo2C1u1vZ7aK
`ObjectView` オブジェクトでは、これはダッシュボードでユーザーが表示する現在のオブジェクトの ID です。
objectContext.object	文字列	charge
`ObjectView` オブジェクトでは、これはダッシュボードでユーザーが表示する現在のオブジェクトのタイプです。
定数	オブジェクト	`{"API_BASE": "https://api.example.com/v1"}`
CLI マニフェストフラグを使用してローカル開発用に上書き可能な、アプリマニフェストから渡される任意の定数を持つオブジェクト。

OAuth コンテキスト

oauthContext プロパティには、現在の OAuth ワークフローに関する情報が含まれます (このワークフローが進行中の場合)。

フィールド	タイプ	例
error	文字列	none
OAuth エラーコード
code	文字列	none
OAuth 認証コード
state	文字列	none
アプリで使用される OAuth の状態
verifier	文字列	none
OAuth コード検証

アプリのコンテキスト

appContext プロパティには、ユーザーのアプリのインストールに関する情報が格納され、次のフィールドが含まれます。

フィールド	タイプ	例
authorizedPermissions	Array<string>	`['event_read', 'charge_write']`
アプリの現在承認済みの権限
authorizedCSP.connectSrc	Array<string>	`['http://o.ingest.sentry.io/api/']`
許可されたサードパーティー API の URL。URL がスラッシュで終わる場合には、その子もすべて許可されます。
authorizedCSP.imageSrc	Array<string>	`['https://images.example.com/'、'https://images.example.org']`
Img コンポーネントの読み込み元となる URL。URL がスラッシュで終わる場合には、その子もすべて許可されます。

ユーティリティ関数

UI 拡張機能 SDK はこれらの機能を提供し、アプリが Stripe API やダッシュボードユーザーとやり取りできるようにします。

clipboardWriteText: エンドユーザーのクリップボードにテキストを書き込みます。
createHttpClient: 認証済みの Stripe API クライアントを取得します。
createOAuthState: OAuth ワークフローで認証リンクを作成する際に使用する値を取得します。
fetchStripeSignature: Stripe のサーバーから署名を取得します。
getDashboardUserEmail: エンドユーザーのメールアドレスを取得します。
getUserAuthorizedPermissions: アプリの承認済みの権限とダッシュボードの現在のユーザーの権限の共通部分を取得します。
isPermissionAuthorized: 権限が現在アプリの承認済みの権限に含まれるかどうかを示します。
isSourceInAuthorizedCSP: URL が現在アプリの承認済みのコンテンツセキュリティポリシーに含まれるかどうかを示します。
showToast: ユーザにトーストメッセージを表示します。
useRefreshDashboardData: ダッシュボードでデータを更新するビューを有効にします。

clipboardWriteText

アプリユーザーのクリップボードにテキストを書き込みます。ユーザーは、ユーザー自身がコピーした場合と同様に、それを貼り付けることができます。

引数	タイプ	例
text	文字列	Hello, world!
コピーするテキスト

この機能を使用するには、まず SDK からインポートする必要があります。

import {clipboardWriteText} from '@stripe/ui-extension-sdk/utils';

たとえば、ボタンを押すと Hello, world! をクリップボードにコピーするボタンを提供します。実際のアプリでは、これを使用して住所、請求書番号、またはその他の重要な情報をコピーできます。

import {useCallback} from 'react';
import {Button} from '@stripe/ui-extension-sdk/ui';
import {clipboardWriteText} from '@stripe/ui-extension-sdk/utils';

const App = () => {
  const writeToClipboard = useCallback(async () => {
    try {
      await clipboardWriteText('Hello, world!');
      // Writing to the clipboard succeeded
    } catch (e) {
      // Writing to the clipboard failed
    }
  }, []);
  return (
    <Button
      onPress={writeToClipboard}
    >
      Copy to clipboard
    </Button>
  );
};

createHttpClient

インストールしているユーザーのアカウント用に、認証済みの Stripe API クライアントを取得します。SDK が提供する STRIPE_API_KEY を使用して、クライアントにアプリのマニフェストで定義されている権限を付与します。

この機能を使用するには、まず SDK からインポートして、stripe-node から Stripe コンストラクターに値を指定します。

import {createHttpClient, STRIPE_API_KEY} from '@stripe/ui-extension-sdk/http_client';
import Stripe from 'stripe';

const stripe = new Stripe(
  STRIPE_API_KEY,
  {
    httpClient: createHttpClient(),
    apiVersion: '2022-11-15'
  }
)

このコンテキストでの例については、UI を構築するをご覧ください。

createOAuthState

OAuth ワークフローでオーソリリンクを作成する際に使用する、state と challenge の値を取得します。

この機能を使用するには、まず SDK からインポートする必要があります。

import {createOAuthState} from '@stripe/ui-extension-sdk/utils';

コンテキストでの例については、オーソリワークフローを追加するをご覧ください。

fetchStripeSignature

Stripe のサーバーから署名を取得します。UI 拡張機能は、この署名を使用してアプリのバックエンドに署名付きのリクエストを送信できます。

この機能を使用するには、まず SDK からインポートする必要があります。

import {fetchStripeSignature} from '@stripe/ui-extension-sdk/utils';

この詳細やコンテキストでの例については、サーバー側のロジックのドキュメントをご覧ください。

getDashboardUserEmail

アプリユーザーのメールアドレスを取得します。

この機能を使用するには、まず SDK からインポートする必要があります。

import {getDashboardUserEmail} from '@stripe/ui-extension-sdk/utils';

アプリマニフェストに user_email_read 権限を追加する必要もあります。CLI コマンドを使用して追加するか、アプリマニフェストファイルを直接編集します。

Command Line

CLI コマンド

stripe apps grant permission user_email_read "EXPLANATION"

たとえば、getDashboardUserEmail 関数を使用してアプリユーザーのメールアドレスを取得し、それを React ステート変数に格納することで、ビューでエンドユーザーのメールアドレスにアクセスします。

import {useEffect, useState} from 'react';
import {getDashboardUserEmail} from '@stripe/ui-extension-sdk/utils';

export const useDashboardUserEmail = () => {
  const [email, setEmail] = useState<string | null>(null);

  const fetchEmail = async () => {
    try {
      const {email} = await getDashboardUserEmail();
      setEmail(email);
    } catch(e) {
      console.error(e);
    }
  };

  useEffect(() => {
    fetchEmail();
  }, []);

  return email;
};

const App = () => {
  const dashboardUserEmail = useDashboardUserEmail();
  ...
};

getUserAuthorizedPermissions

アプリの承認済みの権限とダッシュボードの現在のユーザーの権限の共通部分を取得します。

たとえば、アプリの現在の承認済みの権限が event_read と charge_write であっても、ダッシュボードの現在のユーザーの役割が view_only である (つまり、編集権限を持っていない) 場合、この関数を呼び出すと ['event_read'] 配列が返されます。

この機能を使用するには、まず SDK からインポートする必要があります。

import {getUserAuthorizedPermissions} from '@stripe/ui-extension-sdk/utils';

isPermissionAuthorized

権限がアプリの承認済みの権限に含まれているかを示します。権限がアプリのマニフェストに基づいていない場合、エラーが返されます。

引数	タイプ	例
権限	文字列	charge_read
確認する権限

この機能を使用するには、まず SDK からインポートする必要があります。

import {isPermissionAuthorized} from '@stripe/ui-extension-sdk/utils';

権限によって機能を制限する

この関数は、ユーザーの承認済みの権限でアプリの機能を制限できます。

たとえば、顧客の詳細ページでは、アプリのユーザーが customer_write 権限を承認した場合にのみ顧客の詳細を更新します。

import {isPermissionAuthorized} from '@stripe/ui-extension-sdk/utils';

const App = () => {

  const updateCustomer = useCallback(async () => {

    const customerWriteEnabled = await isPermissionAuthorized('customer_write');
    if (customerWriteEnabled){
      await updateCurrentCustomer()
    }
    ...
  })
}

isSourceInAuthorizedCSP

URL がアプリの承認済みの連結ソースまたは画像ソースであるかを示します。

引数	タイプ	例
source	文字列	https://images.example.org/
確認する URL

この機能を使用するには、まず SDK からインポートする必要があります。

import {isSourceInAuthorizedCSP} from '@stripe/ui-extension-sdk/utils';

showToast

ビューの下部にトーストをレンダリングしてアクションのステータスをユーザーに通知します。たとえば、トーストで、API コールの成功または失敗をユーザーに表示できます。

import {showToast} from '@stripe/ui-extension-sdk/utils';

const App = () => {
  const handleClick = () => {
    fetch(...)
      .then((response) => {
        showToast("Invoice updated", {type: "success"})
        return response.json()
      })
      .catch(() => {
        showToast("Invoice could not be updated", {type: "caution"})
      })
  }

  // Use the `handleClick`...
}

showToast() 関数は、message と options の 2 つの引数を使用します。この関数は次のように定義されます。

type ToastType = "success" | "caution" | "pending" | undefined;
type ToastOptions = { type?: ToastType; action?: string; onAction: () => void; }
(message: string, options?: ToastOptions) => Promise<{
    update: (updateMessage: string, updateOptions?: ToastOptions) => void;
    dismiss: () => void;
}>;

トーストのメッセージは 30 文字を超えたり、空にすることはできません。メッセージが長すぎる場合や空の場合は、コンソールにエラーが記録されます。

タイプが pending の場合を除き、トーストは自動的に消えます。

Pending の場合	アクションあり	タイムアウト
`false`	`false`	4 秒
`false`	`true`	6 秒
`true`	`false`	なし
`true`	`true`	なし

import {showToast} from '@stripe/ui-extension-sdk/utils';

const App = () => {
  const handleClick = async () => {
    const { dismiss, update } = await showToast("Refreshing data", {
      type: "pending",
    });
    try {
      await refreshData();
      dismiss();
    } catch (error) {
      update("Data could not be refreshed", { type: "caution" });
    }
  }

  // Use the `handleClick`...
}

トーストでユーザーにアクションを促すこともできます。アクションボタンがクリックされると、トーストは自動的に消えます。

import {showToast} from '@stripe/ui-extension-sdk/utils';

const App = () => {
  const handleClick = async () => {
    let timeout;
    const { dismiss } = await showToast('Message "sent"', {
      action: "Undo",
      onAction: () => {
        clearTimeout(timeout);
        showToast('Message "unsent"');
      },
    });
    timeout = setTimeout(() => {
      sendMessage();
      dismiss();
    }, 3000);
  }

  // Use the `handleClick`...
}

useRefreshDashboardData

ダッシュボードでビューがデータを更新できるようにします。この関数は別のコールバック関数を返します。そのコールバックを保存し、Stripe のデータが変化したらそれを呼び出します。呼び出すと、新しい値を反映してダッシュボードが更新されます。

この機能を使用するには、まず SDK からインポートする必要があります。

import {useRefreshDashboardData} from '@stripe/ui-extension-sdk/utils';

たとえば顧客の詳細ページで、ダッシュボードのデータを更新するコールバック関数を取得し、次に現在の顧客の更新後にそれを呼び出します。

import {useCallback} from 'react';
import {useRefreshDashboardData} from '@stripe/ui-extension-sdk/utils';

const App = () => {
  const refreshDashboardData = useRefreshDashboardData();

  const updateCustomer = useCallback(async () => {
    try {
      await updateCurrentCustomer();
      await refreshDashboardData();
    } catch (error) {}
  }, [refreshDashboardData]);
}

Extension SDK API リファレンス

Extension SDK API の、すべてのフィールド、タイプ、説明のインデックス。

プロパティー

ユーザーコンテキスト

RoleDefinition

環境

OAuth コンテキスト

アプリのコンテキスト

ユーティリティ関数

clipboardWriteText

createHttpClient

createOAuthState

fetchStripeSignature

getDashboardUserEmail

getUserAuthorizedPermissions

isPermissionAuthorized

権限によって機能を制限する

isSourceInAuthorizedCSP

showToast

useRefreshDashboardData

参照情報