アプリのマニフェストリファレンス

アプリのマニフェスト、すなわちアプリのマニフェストファイルのすべてのフィールドのインデックス、タイプ、記述についてご紹介します。

アプリのマニフェストは、アプリケーションの Stripe プラットフォームへの組み込み方法を説明します。各 Stripe アプリには、プロジェクトのディレクトリー構造のルートに stripe-app.json マニフェストファイルが必要です。

アプリのマニフェストは、Stripe Apps CLI を使用して更新するか、直接編集することができます。たとえば、stripe apps grant permission コマンドを使用するか、またはアプリのマニフェストに直接 permissionRequest を追加して権限を追加できます。

アプリのマニフェストファイルは、このページで説明されているスキーマに従います。

例

stripe-app.json
{
  "id": "com.invoicing.[YOUR_APP]",
  "version": "1.2.3",
  "name": "[YOUR APP] Shipment Invoicing",
  "icon": "./[YOUR_APP]_icon_32.png",
  "distribution_type": "public",
  "permissions": [
    {
      "permission": "invoice_write",
      "purpose": "Allows [YOUR APP] to add shipping line items to an invoice."
    },
    {
      "permission": "product_read",
      "purpose": "Allows [YOUR APP] to use product sizes for calculating shipping."
    }
  ],
  "ui_extension": {
    "views": [
      {
        "viewport": "stripe.dashboard.invoice.detail",
        "component": "AddShipping"
      }
    ],
    "content_security_policy": {
      "connect-src": [
        "https://api.example.com/a_specific_endpoint",
        "https://api.example.com/a_whole_subdirectory/"
      ],
      "image-src": [
        "https://images.example.com/one_image.jpg",
        "https://images.example.com/a_whole_subdirectory/"
      ],
      "purpose": "These URLs allow the app to contact [YOUR APP] for creating shipping details and loading images of shipping partner logos"
    }
  },
  "post_install_action": {
    "type": "external",
    "url": "https://example.com"
  },
  "constants": {
    "API_BASE": "https://api.example.com"
  }
}

スキーマ

アプリのマニフェストファイルは、次のフィールドを含む JSON ファイルです。

フィールド名	タイプ	例
id	スラグ	com.invoicing.myapp
作成者が定義する、アプリのグローバルで一意の識別子です。初回提出時に Stripe で検証します。
バージョン	文字列	1.2.4
定義するアプリのバージョン。バージョン ID の形式は自由に決めることができます。
名前	文字列	自分のアプリ
アプリを指す名称として、UI に表示される名前。一般公開アプリには、「Stripe」、「app (アプリ)」、「free (無料)」、「paid (有料)」の語句を含めないでください。
アイコン	文字列	./favicon.png
属性の横に表示する 300x300 ピクセルの PNG アイコンへの、アプリバンドル内の相対パス。
distribution_type	“public” \| “private”	“public”
アプリの配布タイプ。
sandbox_install_compatible	true \| false	true
アプリのサンドボックスへのインストールを有効にします。
stripe_api_access_type	“platform” \| “oauth” \| “restricted_api_key”	oauth
アプリの API 認証方法。
allowed_redirect_uris	Array<String>	none
ユーザーが OAuth またはインストールリンクを使用してアプリをインストールした後にリダイレクトされる URL です。
権限	Array<PermissionRequest>	none
The permissions required by the app to function.
ui_extension	UIExtensionManifest	none
「UI 拡張機能」ケイパビリティ特有の設定。
post_install_action	PostInstallAction	none
アプリのインストール後にユーザーをカスタムの場所に誘導するためのオプションの設定。
定数	オブジェクト	`{"API_BASE": "https://api.example.com/v1"}`
CLI マニフェストフラグを使用してローカル開発用に上書き可能な、UI 拡張機能コンテキストプロパティでアクセスできる任意の定数値を持つオブジェクト。

PermissionRequest

権限のリクエストには、次のフィールドがあります。

フィールド名	タイプ	例
権限	文字列	customer_write
アプリが要求している権限。詳細は権限をご覧ください。
目的	文字列 \| Map<locale, string>	「このアプリは、images.example.com から画像を読み込みます。」
アプリをインストールする人に、アプリがこれらの権限を必要とする理由を説明する、ユーザー向けの説明。
名前	文字列	「選択された配送料金で請求書を更新するために、[お客様のアプリ] で必要とされます」
アプリの審査担当者に、アプリがこれらの権限を必要とする理由について説明する、Stripe 向けの説明。

UiExtensionManifest

UI 拡張機能のマニフェストには、次のフィールドがあります。

フィールド名	タイプ	例
ビュー	Array<ViewManifest>	none
特定の場所で、ダッシュボードに表示される React コンポーネント。もっと知る。
content_security_policy	CSPRequest	none
UI 拡張機能が特定の目的で、特定の URL にアクセスできるように許可を求めるリクエスト。

ViewManifest

ビューのマニフェストには、次のフィールドがあります。

フィールド名	タイプ	例
ビューポート	文字列	stripe.dashboard.invoice.detail
ダッシュボード内のどこに UI 拡張機能が表示されるかを示す ID。使用できるビューポートのリストをご覧ください。
コンポーネント	文字列	AddShippingSelector
いずれかの view コンポーネントを使用する、エクスポートされた React コンポーネント。

CSPRequest

コンテンツセキュリティーポリシーのリクエストには、以下のフィールドがあります。

フィールド名	タイプ	例
connect-src	Array<string>	https://o0.ingest.sentry.io/api/
許可されたサードパーティー API の URL。URL がスラッシュで終わる場合には、その子もすべて許可されます。詳細については、サードパーティー API を使用するをご覧ください。
image-src	Array<string>	https://images.example.com/
Img コンポーネントの読み込み元となる URL。URL がスラッシュで終わる場合には、その子もすべて許可されます。
目的	文字列 \| Map<locale, string>	「このアプリは、https://images.example.com から画像を読み込みます。また、デバッグを目的として当社のパートナーである Sentry に匿名のエラーレポートを送信します。」
アプリのインストール時にユーザーに表示する説明。プラグインがこれらの URL と直接通信する必要がある理由を説明します。

URL は CSP 仕様に準拠している必要があります。HTTPS スキームのみが許可されます。使用方法とトラブルシューティングについては、サードパーティー API を使用するをご覧ください。

PostInstallAction

インストール後のアクションには以下のフィールドがあります。

フィールド名	タイプ	例
タイプ	文字列	`external`、`settings`
ユーザーが Stripe ダッシュボードでアプリをインストールした後の追加アクション。詳細については、インストール後の設定を有効にするをご覧ください。
url	文字列	https://example.com
アプリをインストールした後にユーザーをリダイレクトする外部 URL。これはインストール後のアクションタイプが `external` の場合にのみ必要とされます。

開発用の拡張マニフェストファイルを使用する

ローカル開発では、本番環境と異なるアプリマニフェスト値を使用する必要がある場合があります。例えば、アプリのバックエンドは https://api.example.com/v1 に配置される可能性がありますが、ローカル開発のバックエンドは http://localhost:8888/v1 で実行されます。

マニフェストファイルのこの例を考慮すると:

stripe-app.json
{
  "id": "com.invoicing.[YOUR_APP]",
  "version": "1.2.3",
  "name": "[YOUR APP] Shipment Invoicing",
  "icon": "./[YOUR_APP]_icon_32.png",
  "permissions": [],
  "ui_extension": {
    "views": [
      {
        "viewport": "stripe.dashboard.invoice.detail",
        "component": "InvoiceDetail"
      }
    ],
    "content_security_policy": {
      "connect-src": ["https://api.example.com/v1"],
      "purpose": "Allow the app to retrieve example data"
    }
  },
  "constants": {
    "API_BASE": "https://api.example.com/v1"
  }
}

stripe-app.[anything].json という別のマニフェストファイルを作成します。これは、メインのマニフェストを拡張し、ローカル値でそれを上書きします。以下に例を示します。

stripe-app.dev.json
{
  "extends": "stripe-app.json",
  "ui_extension": {
    "content_security_policy": {
      "connect-src": ["http://localhost:8888/v1"]
    }
  },
  "constants": {
    "API_BASE": "http://localhost:8888/v1"
  }
}

開発中にローカルマニフェストファイルを使用するには、--manifest flag を使用して読み込みます。以下に例を示します。

Command Line
stripe apps start --manifest stripe-app.dev.json

コンテキストプロパティーを使用してビューで constants 値にアクセスします。以下に例を示します。

import {useEffect, useState} from 'react';
import type {ExtensionContextValue} from '@stripe/ui-extension-sdk/context';
import {Box} from '@stripe/ui-extension-sdk/ui';

const InvoiceDetail = ({environment}: ExtensionContextValue) => {
  const [data, setData] = useState(null);

  useEffect(() => {
    fetch(`${environment.constants.API_BASE}/some-endpoint`)
      .then(response => response.json())
      .then(json => setData(json));
  }, []);

  return data ? <Box>Here is your message: {data.message}</Box> : 'Loading...';
};

注