# UI Extension SDK API リファレンス

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

*UI 拡張機能* (A set of APIs that allow you to inject user interface elements into the Stripe Dashboard using TypeScript and React)は、アプリのユーザーと Stripe ダッシュボードのエコシステムと対話するための [context プロパティー](https://docs.stripe.com/stripe-apps/reference/extensions-sdk-api.md#props)と[ユーティリティ関数](https://docs.stripe.com/stripe-apps/reference/extensions-sdk-api.md#functions)にアクセスできます。このページでは、これらの値と関数について説明します。

## プロパティー

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

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

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

### ユーザーコンテキスト

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

| フィールド | タイプ | 例 | **Description** |
| --- | --- | --- | --- |
| name | 文字列 | Jenny Rosen | アプリユーザーの名前 |
| account.country | 文字列 | UK | アプリユーザーの国 |
| account.id | 文字列 | acct_1032D82eZvKYlo2C | アプリユーザーのアカウント ID |
| account.name | 文字列 | Jenny’s Llama Emporium | Stripe アカウントの名前 |
| account.org_id | 文字列 | org_1032D82eZvKYlo2C | アプリのユーザーが所属する Stripe Organizations の ID |
| account.isSandbox | ブール値 | true | Stripe アカウントがサンドボックスであるかどうか |
| 職種 | 配列<[RoleDefinition](https://docs.stripe.com/stripe-apps/reference/extensions-sdk-api.md#roledefinition)\> |  | アクティブユーザーの[ユーザーの役割](https://docs.stripe.com/get-started/account/teams/roles.md)のリスト。 |
| locale | 文字列 | en-GB | アプリユーザーのシステム言語 ID |

### RoleDefinition

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

| フィールド名 | タイプ | 例 | **Description** |
| --- | --- | --- | --- |
| ID | 文字列 | 開発者 | ユーザーの役割を表す、安定した機械可読の識別子です。`name` とは異なり、役割の表示名が更新されても変更されないため、比較用途に使用しても安全です。 |
| タイプ | ‘builtIn’ | ‘custom’ | builtIn | 役割の種類を指定します。カスタム役割は[プライベートアプリ](https://docs.stripe.com/stripe-apps/distribution-options.md#share-with-team-members)にのみ使用できます。 |
| name | 文字列 | 開発者 | ユーザーの役割を表すわかりやすい名称です。プログラムによる比較には `id` を使用してください。`name` は変更される可能性があります。 |

### 環境

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

| フィールド | タイプ | 例 | **Description** |
| --- | --- | --- | --- |
| 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 マニフェストフラグを使用してローカル開発用に上書き](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#extended-manifest)可能な、*アプリマニフェスト* (In a Stripe App, the app manifest is a stripe-app.json file in your app's root directory. It defines your app's ID, views, permissions, and other essential properties)から渡される任意の定数を持つオブジェクト。 |
| queryParams | オブジェクト | `{"task": "onboardingStart", "source": "email"}` | [ルート記述子](https://docs.stripe.com/stripe-apps/route-descriptors.md#passing-parameters-to-the-destination-view)または[ディープリンク](https://docs.stripe.com/stripe-apps/deep-links.md)の URL を介してアプリに渡されるクエリパラメーターです。`queryParams` プロパティを使用して渡される場合、`app_` プレフィックスは削除されます。 |

### OAuth コンテキスト

`oauthContext` プロパティには、現在の [OAuth ワークフロー](https://docs.stripe.com/stripe-apps/pkce-oauth-flow.md)に関する情報が含まれます (このワークフローが進行中の場合)。

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

### アプリのコンテキスト

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

| フィールド | タイプ | 例 | **Description** |
| --- | --- | --- | --- |
| 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](https://stripe.com/stripe-apps/ui-toolkit/components/img) コンポーネントの読み込み元となる URL。URL がスラッシュで終わる場合には、その子もすべて許可されます。 |

## ユーティリティ関数

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

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

### clipboardWriteText

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

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

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

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

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

```ts
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` を使用して、クライアントに[アプリのマニフェスト](https://docs.stripe.com/stripe-apps/reference/app-manifest.md)で定義されている権限を付与します。

この機能を使用するには、まず SDK からインポートして、[stripe-node](https://github.com/stripe/stripe-node) から Stripe コンストラクターに値を指定します。

```ts
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 を構築する](https://docs.stripe.com/stripe-apps/build-ui.md#code-sample-update-customer-name)をご覧ください。

### createOAuthState

OAuth ワークフローで[オーソリリンクを作成](https://docs.stripe.com/stripe-apps/pkce-oauth-flow.md#create-authorization-link)する際に使用する、`state` と `challenge` の値を取得します。

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

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

コンテキストでの例については、[オーソリワークフローを追加する](https://docs.stripe.com/stripe-apps/pkce-oauth-flow.md)をご覧ください。

### fetchStripeSignature

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

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

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

> プレビューモードでは、初めてアプリをアップロードするまで、`fetchStripeSignature` 関数でエラーが発生します。設定手順については、[サーバー側のロジック](https://docs.stripe.com/stripe-apps/build-backend.md#authenticate-ui-to-backend)をご覧ください。

この詳細やコンテキストでの例については、[サーバー側のロジック](https://docs.stripe.com/stripe-apps/build-backend.md)のドキュメントをご覧ください。

### getDashboardUserEmail

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

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

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

[アプリマニフェスト](https://docs.stripe.com/stripe-apps/reference/app-manifest.md)に `user_email_read` 権限を追加する必要もあります。CLI コマンドを使用して追加するか、アプリマニフェストファイルを直接編集します。

#### CLI コマンド

```bash
stripe apps grant permission user_email_read "EXPLANATION" # これらの権限が必要とされる理由の説明。管理者は、権限を承認するかどうかを決定する際にこれを確認します。
```

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

```ts
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

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

たとえば、アプリの現在の[承認済みの権限](https://docs.stripe.com/stripe-apps/reference/extensions-sdk-api.md#appContext)が `event_read` と `charge_write` であっても、ダッシュボードの現在のユーザーの役割が `view_only` である (つまり、編集権限を持っていない) 場合、この関数を呼び出すと `['event_read']` 配列が返されます。

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

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

### isPermissionAuthorized

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

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

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

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

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

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

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

```ts
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 がアプリの承認済みの連結ソースまたは画像ソースであるかを示します。

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

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

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

### navigateToDashboardRoute

Stripe アプリからプログラムで別のダッシュボードルートに移動します。アプリ内アクションに応じて関連するダッシュボードページにユーザーを誘導する際に役立ちます。

> `navigateToDashboardRoute` は SDK バージョン 9.2.0 以降でのみ使用できます。

| 引数 | タイプ | 例 | **Description** |
| --- | --- | --- | --- |
| descriptor | [RouteDescriptor](https://docs.stripe.com/stripe-apps/route-descriptors.md) | `{name: 'customers'}` | 対象のダッシュボードルートを指定する descriptor オブジェクト。 |

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

```ts
import {navigateToDashboardRoute} from '@stripe/ui-extension-sdk/navigation';
```

たとえば、ボタンが押されたときに特定の顧客の詳細ページに移動します。

```ts
import {useCallback} from 'react';
import {Button} from '@stripe/ui-extension-sdk/ui';
import {navigateToDashboardRoute} from '@stripe/ui-extension-sdk/navigation';

const App = ({customerId}: {customerId: string}) => {
  const goToCustomer = useCallback(() => {
    navigateToDashboardRoute({
      name: 'customerDetails',
      params: {customerId},
    });
  }, [customerId]);

  return (
    <Button onPress={goToCustomer}>
      View customer
    </Button>
  );
};
```

`fullPage` ルートディスクリプターを使用して、アプリ独自のフルページビューに移動することもできます。

```ts
import {useCallback} from 'react';
import {Button} from '@stripe/ui-extension-sdk/ui';
import {navigateToDashboardRoute} from '@stripe/ui-extension-sdk/navigation';

const App = ({appId}: {appId: string}) => {
  const goToFullPage = useCallback(() => {
    navigateToDashboardRoute({
      name: 'fullPage',
      params: {appId, tabId: 'overview'},
    });
  }, [appId]);

  return (
    <Button onPress={goToFullPage}>
      Open full-page view
    </Button>
  );
};
```

### showToast

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

```ts
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 つの引数を使用します。この関数は次のように定義されます。

```ts
type ToastType = "success" | "caution" | "pending" | undefined;
type ToastOptions = { type?: ToastType; action?: string; onAction: () => void; }
const showToast: (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` | なし |

```ts
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`...
}
```

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

```ts
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 からインポートする必要があります。

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

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

```ts
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 フックは、SDK バージョン 9.x でのみ使用できます。

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

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

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

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

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

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

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

## See also

- [UI Extensions の仕組み](https://docs.stripe.com/stripe-apps/how-ui-extensions-work.md)
- [ビューポートリファレンス](https://docs.stripe.com/stripe-apps/reference/viewports.md)
- [UI Extensions で役割を使用する](https://docs.stripe.com/stripe-apps/using-roles-in-ui-extensions.md)