知っていると便利なStripe Apps用ユーティリティ関数とその使い所

この記事は、Stripe Apps を25日間紹介し続ける Advent Calendar 2022 25日目の記事です。

知っていると便利なStripe Appsヘルパー関数

Stripe Appsのアプリを開発していると、クリップボードへのアクセスやAPI呼び出し結果の通知画面など、どの案件でも使うことの多い機能が出てきます。

このようなユーティリティ機能について、Stripe AppsではSDK内にヘルパー関数を用意しています。

ここでは、ヘルパー関数のうち、利用することの多い関数を４つ紹介します。

clipboardWriteText: アプリ内のテキストを、クリップボードにコピーする

この関数を実行すると、引数内のテキストがクリップボードにコピーされます。

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

const App = () => {
  return (
    <Button
      onPress={async () => {
        await clipboardWriteText('Hello, world!');
      }}
    >
      Copy to clipboard
    </Button>
  );
};

リソースのIDや、連携先のサービスから取得した顧客の情報など、アプリに表示されているデータをコピーアンドペーストしたいデータに利用します。

showToast: ダッシュボード下部に、トーストでメッセージを表示する

データの更新や外部のAPIを呼び出した際、その実行結果をユーザーに通知する必要があります。

その際、showToastを利用することで、通知画面を実装する工数を減らせます。

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

const App = () => {
  return (
    <Button
      onPress={async () => {
        await fetch("https://example.com/api");
        await showToast("completed", { type: "success" });
      }}
    >
      Update Customer
    </Button>
  );
};

showToastはdismissとupdate関数を返します。

複数のAPIを呼び出したり、エラーのハンドリングを行いたい場合に利用できます。

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

const App = () => {
  return (
    <Button
      onPress={async () => {
        const { update } =  await showToast("processing", { type: "pending" });
        try {
          await fetch("https://example.com/api");
          await update("completed", { type: "success" });
        } catch (e) {
          await update("Failed", { type: "caution" });
        }
      }}
    >
      Update Customer
    </Button>
  );
};

getDashboardUserEmail: 操作中のユーザーのログインメールアドレスを取得する

外部のサービスを利用してメールを送信したい場合などで、ログイン中のユーザーのメールアドレスを簡単に取得できます。

const { email } = await getDashboardUserEmail();

この関数を利用するには、アプリの権限設定を更新する必要がありますのでご注意ください。

$ stripe apps grant permission user_email_read "EXPLANATION"

useRefreshDashboardData: ダッシュボードの画面を再読み込みするためのHook

アプリ内でStripeのデータを更新する場合、「アプリを表示しているダッシュボード」のデータも更新する必要があります。

useRefreshDashboardDataを利用することで、任意のタイミングでダッシュボードを再読み込みできます。

import { Button } from '@stripe/ui-extension-sdk/ui';
-import { showToast } from '@stripe/ui-extension-sdk/utils';
+import { showToast, refreshDashboardData } from '@stripe/ui-extension-sdk/utils';

const App = () => {
+  const refreshDashboardData = useRefreshDashboardData();
  return (
    <Button
      onPress={async () => {
        const { update } =  await showToast("processing", { type: "pending" });
        try {
          await fetch("https://example.com/api");
+          await refreshDashboardData();
          await update("completed", { type: "success" });
        } catch (e) {
          await update("Failed", { type: "caution" });
        }
      }}
    >
      Update Customer
    </Button>
  );
};

フックとして提供されているため、一度useRefreshDashboardData関数を実行して、再読み込みするための関数を取得する必要がある点にご注意ください。

Documents

Stripe Appsひとりアドベントカレンダー 2022

今年ベータリリースされたばかりのStripe Appsは、まだ日本語の情報が多くありません。

そこでQiita Advent Calendar 2022にて、毎日Stripe Appsについての情報を投稿してきました。

2023年は、この25日間のコンテンツをもとに、実際にサービスと連携させる方法などを紹介できればと思います。