UI を構築する

Stripe ダッシュボードの機能を拡張するカスタム UI を構築、テスト、および編集します。

TypeScript、React、Stripe の UI Extensions SDK と UI ツールキットを使用して Stripe ダッシュボードを拡張することで、アプリをユーザーインターフェイスで使用できるようにします。このガイドでは、ビューを作成および削除することによって単純な UI を構築する方法を説明します。

技術概要については、UI Extensions の仕組みをご覧ください。

ビューを追加する

ビューを使用してアプリの UI を開発します。ビューは、React コンポーネントと指定のビューポートのペアリングです。React コンポーネントは、Stripe の UI ツールキットの UI コンポーネントで構成されています。ビューポートは、その UI を表示する Stripe ダッシュボードのページまたはセクションです。

次のように、プロジェクトのルートディレクトリーで add コマンドを使用します。
Command Line
```
stripe apps add view
```
指示に従います。
- ビューが表示されるビューポートを選択します。使用できるビューポートのリストをご覧ください。
- ビューに名前を指定します (MyComponentName など)。CLI は、ビューポートの選択に従って名前を提案します。
Stripe は、自動的にアプリマニフェストの views 配列にビューを追加し、src/views ディレクトリーに新しい React コンポーネントファイルを作成し、それと同時にユニットテストファイルを作成します。

アプリケーションをプレビューする

アプリをローカルで実行し、更新し、変更内容をダッシュボードでプレビューできます。

プロジェクトのルートディレクトリーから、開発サーバーを起動します。
Command Line
```
stripe apps start
```
Enter を押してブラウザーを開きます。
続行をクリックして、Stripe アカウントでアプリをプレビューします。
開発サーバーを停止するには、コマンドラインから Ctrl+C と入力します。

開発者サーバーが実行されているときは、アプリに変更を加えると、ページを更新することなくそれがダッシュボードに自動的に表示されます。エラーは、解決されるまで、Stripe ダッシュボード、ブラウザーの開発者ツール、Stripe CLI に自動的に表示されます。

プレビューの切り替え

アプリのローカルバージョンのプレビューを無効にして、最近テスト環境でインストールしたアプリのバージョンをプレビューできます。テスト環境にアプリのバージョンをインストールしたことがない場合は、プレビューを切り替えることができません。

テスト環境で最近インストールしたアプリのバージョンをプレビューするには、開発サーバーを実行して、以下のステップを実行します。

アプリで、アプリの右上にあるオーバーフローメニューをクリックします。
アプリのプレビューを無効化をクリックし、続行をクリックします。

ダッシュボードで Stripe オブジェクトにアクセスする

ビューポートにコンポーネントを割り当てると、コンポーネントは environment.objectContext オブジェクトを使用して、そのページの Stripe オブジェクトに関するコンテキストを受け取ることができます。

たとえば、stripe.dashboard.customer.detail ビューポートを使用するビューを作成する場合、environment.objectContext オブジェクトは customer オブジェクトタイプと、現在のユーザーの ID を返します。次に、それらの値を使用して、Customer (顧客) オブジェクトに関する詳細情報を取得し、住所、説明などの属性を変更できます。

ビューポートが提供するオブジェクトのインデックスについては、ビューポートのリファレンスドキュメントをご覧ください。

例: 顧客名を更新する

次のコードでは、Stripe Node.js API クライアントと、ビューポートの environment.objectContext ID を使用して、顧客名を更新します。

アプリに customer_write 権限を追加します。

Command Line
stripe apps grant permission "customer_write" "Allows the app to update the name of the customer."

アプリで Stripe API を使用し、顧客名を更新します。

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

// Initiate communication with the stripe client.
const stripe = new Stripe(STRIPE_API_KEY, {
  httpClient: createHttpClient(),
  apiVersion: '2022-08-01',
})

const App = ({environment, userContext}) => {
  // Call the Stripe API to make updates to customer details.
  const updateCurrentCustomer = async (newCustomerName) => {
    try {
      // If the user has permission to update customers, this should succeed.
      const updatedCustomer = await stripe.customers.update(
        // We can use the current objectContext to get the customer ID.
        environment.objectContext.id,
        {name: newCustomerName}
      );

      console.log(updatedCustomer.name);
    } catch (error) {}
  };
}

例: ダッシュボードのデータを更新する

アプリがダッシュボードのデータを変更する場合は、useRefreshDashboardData 関数を使用して、データを更新するコールバックを生成します。

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

const App = () => {
  // Get the callback used to refresh the dashboard data
  const refreshDashboardData = useRefreshDashboardData();

  // Stripe API call
  const updateCustomer = useCallback(async () => {
    try {
      await updateCurrentCustomer();

      // Call to refresh the data in the Dashboard
      refreshDashboardData();
    } catch (error) {}
  }, [refreshDashboardData]);
}

サードパーティー API を使用する

UI 拡張機能は、サードパーティー API (独自の API またはパブリック API) を呼び出して、アプリでデータのリクエストや送信を行うことができます。

次のように grant url コマンドを使用して、サードパーティー API の URL を追加します。
Command Line
```
stripe apps grant url "https://*.api.example.com/path/" "Send data to example service..."
```
Connect-src URL は、以下の要件を満たしている必要があります。
- 安全な HTTPS プロトコル (例: https://www.example.com/api/users/) を使用します。
- パスを含みます (例: https://www.example.com/api/users/ URL は有効ですが、https://www.example.com/ は無効です)。ベースパスの末尾にスラッシュを追加することにより、その後のあらゆるパスがカバーされます (例: https://www.example.com/api/ により、 https://www.example.com/api/users/abc123/address へのコールが可能になります)。
- Stripe API へのコールにすることはできません。
- ワイルドカード (*) を使用する場合は、DNS ラベルの一番左で使用する必要があります (例: https://*.example.com/api/users/)。
Stripe Apps によって、プロジェクトのアプリマニフェストの connect-src 配列に URL が追加されます。
```
"ui_extension": {
    "views": [],
    "actions": [],
    "content_security_policy": {
      "connect-src": [
        "https://*.api.example.com/",
        "https://o0.ingest.example.io/api/",
      ],
      "purpose": "Send data to example service. The Example app sends data to the Example service to provide its functionality and sends anonymous error reports to our partner Example for debugging purposes"
    }
  }
```
connect-src URL の削除には、Stripe CLI を使用することもできます。
Command Line
```
stripe apps revoke connect-src "https://*.api.example.com/path/"
```
ブラウザーでアプリをプレビューするには、開発サーバーを起動して、CLI のプロンプトに従います。
Command Line
```
stripe apps start
```

アプリで、サードパーティー API の URL を指定した fetch コールを追加します。

たとえば、アプリマニフェストに https://www.example.com/api/users connect-src URL を追加する場合は、次の fetch コールを使用できます。

const makeRequestToService = (endpoint, requestData) => {
  return fetch(`https://www.example.com/api/${endpoint}/`, {
    'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: requestData,
  });
};

ローカルの開発環境と本番環境で異なるアプリマニフェスト値を使用するには、拡張マニフェストファイルを読み込みます。
サードパーティー API に JavaScript クライアントライブラリがある場合には、npm add コマンドを使用してアプリに依存関係を追加できます。

アプリケーションのデバッグ

アプリの開発中は、ブラウザーの開発者ツールのコンソールをデバッグツールとして使用できます。

アプリに関連するメッセージを分離するには、以下のようにします。

アプリマニフェストでアプリ ID を見つけます。
開発者ツールのブラウザーのコンソールパネルで、絞り込みボックスに [Stripe App <your app ID>] と入力します。[Stripe App com.example.helloworld] のように表示されます。

ビューのテストを作成する

ビューのテストを作成することをお勧めします。単体テストにより、ビューが意図したとおりに動作することを検証できるだけでなく、今後のコード変更がより安全になります。

ビューを作成すると、末尾が .test.tsx のテストファイルにデフォルトのビューのテストが組み込まれます。

import {render, getMockContextProps} from "@stripe/ui-extension-sdk/testing";
import {ContextView} from "@stripe/ui-extension-sdk/ui";

import App from "./App";

describe("App", () => {
  it("renders ContextView", () => {
    const {wrapper} = render(<App {...getMockContextProps()} />);

    expect(wrapper.find(ContextView)).toContainText("save to reload this view");
  });
});

npm run test コマンドまたは yarn test コマンドで付属の Jest テストランナーを使用して、すべてのテストを実行できます。Testing Library や Enzyme などの一般的な React テストツールを使用したことがある方には、@stripe/ui-extension-sdk/testing に含まれているテストパッケージの操作感はなじみのあるものです。

典型的なテストは次のように行われます。

ビューを表示する。
テキストの存在などの、初期状態に関するアサーションを行う。
ビューと対話する。
新しいテキストの表示などの、新しい状態に関するアサーションを行う。

テストパッケージの手法と機能の詳細は、UI テストのリファレンスをご覧ください。