Extension SDK API リファレンス

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

プロパティー

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

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

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

ユーザーコンテキスト

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

RoleDefinition

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

環境

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

OAuth コンテキスト

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

アプリのコンテキスト

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

ユーティリティ関数

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

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

clipboardWriteText

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

この機能を使用するには、まず 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 コマンドを使用して追加するか、アプリマニフェストファイルを直接編集します。

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

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

この機能を使用するには、まず 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 がアプリの承認済みの連結ソースまたは画像ソースであるかを示します。

この機能を使用するには、まず 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 の場合を除き、トーストは自動的に消えます。

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]);
}

useStorage

useStorage React フックを使用して、Stripe アプリの複数のビューポート間で共有されたデータの読み取りと書き込みを行うことができます。

このフックは、同じブラウザー内の Stripe アプリのすべてのアクティブなインスタンス (ビューポート) 間で状態を同期します。1 つのインスタンスで値が更新されると、同じブラウザー内の他のすべてのインスタンスに、変更が自動的に反映されます。これは、アプリの実行中にのみ存在するセッションベースのストレージです。

このフックは、次の場合に役立ちます。

• アプリの複数のビューポート間で状態を調整します。
• 取得したデータをキャッシュしてビューポート間で共有することで、重複した API コールを回避します。

フックには以下の制限があります。

• 値は文字列に限定されるため、複雑なオブジェクトには JSON.stringify または JSON.parse を使用します。
• ストレージはアプリセッション間で永続的ではありません。
• 保存容量の変更は、異なるブラウザーやデバイス間で同期されません。

次の例は、独立してレンダリングされた同じアプリの 2 つのインスタンスが、異なるビューポート間で変数の値を同期する方法を示したものです。このアプリを複数のタブで開いてみて、ウィンドウ間の同期がどのように機能するかをご確認ください。

import React from 'react';
import {Box, TextField} from '@stripe/ui-extension-sdk/ui';
import {useStorage} from '@stripe/ui-extension-sdk/data';

const [name, setName] = useStorage('name');
const greeting = name ? `Hey ${name}!` : `Hello!`;

return (
  <Box css={{stack: 'y', alignY: 'top', gap: 'medium', width: 'fill'}}>
    <TextField
      label="Full name"
      placeholder="Enter your name"
      defaultValue={name || ''}
      onChange={(e) => setName(e.target.value)}
    />
    <Box css={{font: 'title'}}>{greeting}</Box>
  </Box>
)