# 公開アプリのサンドボックス対応を有効にする

公開アプリでサンドボックスへのインストールを有効にできます。

[サンドボックス](https://docs.stripe.com/sandboxes.md)は、Stripe のテスト環境です。ユーザーは、サンドボックスにアプリをインストールして、アプリの特長と機能を評価できます。

## 一般的なサンドボックスとテスト環境のサンドボックスへの対応

Stripe は本番環境とサンドボックスという 2 つの環境に対応しています。すべての Stripe アカウントには、テストモードのサンドボックスを含むサンドボックスがあります。テストモードのサンドボックスは、[一般的なサンドボックスとは異なる特性を持つ](https://docs.stripe.com/testing-use-cases.md#compare)固有の種類のサンドボックスであるため、アプリは一般的なサンドボックスとテストモードのサンドボックスの両方に明示的に対応する必要があります。

両方の種類のサンドボックスに対応すると、より多くの企業が本番環境に移行する前にアプリを評価できるようになります。

### アプリの一般的なサンドボックス対応を有効にする

デフォルトでは、公開アプリをサンドボックスにインストールするにはユーザーによる追加作業が必要です。

サンドボックスへのインストールを有効にするには、[アプリマニフェスト](https://docs.stripe.com/stripe-apps/reference/app-manifest.md)を更新します。サンドボックス対応を有効にしたら、[アプリを審査に提出](https://docs.stripe.com/stripe-apps/publish-app.md)します。サンドボックス対応は、[アプリの審査プロセス](https://docs.stripe.com/stripe-apps/review-requirements.md)の一環として確認されます。

### マネージドサンドボックス

_「管理対象サンドボックス」_とは、公開 Stripe アプリに対応するために Stripe がお客様のアカウントに自動的に作成するサンドボックスです。

- 初めて公開アプリをアップロードするときに、Stripe がマネージドサンドボックスを自動で作成します。

- ユーザーがアプリをサンドボックスにインストールすると、マネージドサンドボックスへの接続が確立されます。

- マネージドサンドボックス内のユーザーのインストール環境のイベントを[デバッグおよび監視](https://docs.stripe.com/workbench/guides.md)できます。

- 管理対象サンドボックスへの変更は、本番環境またはテスト環境のサンドボックスにアプリケーションをインストールするユーザーには影響しません。

- マネージドサンドボックスは削除できません。

### マネージドサンドボックスを作成する

アカウントに初めて[公開 Stripe アプリをアップロード](https://docs.stripe.com/stripe-apps/upload-install-app.md)するときに、Stripe がマネージドサンドボックスを自動で作成します。

2025 年 2 月 3 日より前にアップロードされた公開アプリの場合、Stripe はアカウントにマネージドサンドボックスを自動で作成します。

## 公開アプリで一般的なサンドボックスへのインストールを有効にする

1. `stripe apps -v` を実行して、最新バージョンの [Stripe CLI](https://docs.stripe.com/stripe-cli/upgrade.md) と [Stripe Apps プラグイン](https://docs.stripe.com/stripe-apps/create-app.md#install-stripe-apps-cli) を使用していることを確認します。アプリをアップロードする前に、バージョン 1.5.23 以降を使用する必要があります。
   ```bash
   $ stripe plugin upgrade apps
   ✔ upgrade to v1.7.0 complete.
   $ stripe -v
   stripe version 1.25.1
   $ stripe apps -v
   apps version 1.7.0
   ```
2. アプリマニフェストを更新して、サンドボックスへのインストールをサポートできるようにします。
3. *(オプション)* マネージドサンドボックス内にサンドボックス固有のイベントフックを作成します。サーバー側のロジックを更新して、これらの新しいエンドポイントをリッスンします。
4. *(オプション)* サーバー側のロジックを更新して、サンドボックスへのインストールで Stripe API コールを行うときに[マネージドサンドボックス API キー](https://docs.stripe.com/sandboxes/dashboard/manage-access.md)を使用します。
5. アプリの新しいバージョンをメインアカウント (マネージドサンドボックス**ではありません**) にアップロードします。
6. メインアカウントで、アップロードしたサンドボックスに対応する[外部テストリンクを作成](https://docs.stripe.com/stripe-apps/test-app.md)します。 for the sandbox-enabled version you just uploaded.
7. 新しいサンドボックスを作成して開き、更新したアプリをテストします。
8. ブラウザーウィンドウで、以前作成した外部テストリンクにアクセスし、アプリをインストールします。
9. サンドボックスにインストールしたアプリが想定どおりに動作するかどうかをテストします。
10. 新しいバージョンを送信してマーケットプレイスの審査を受けます。

### アプリマニフェストを更新する

> 2025 年 2 月 3 日以降、マーケットプレイスに公開するアプリのアプリマニフェストでサンドボックスのサポートを true または false として宣言する必要があります。

サンドボックスへのアプリインストールをサポートするには、`sandbox_install_compatible` を使用して[アプリマニフェスト](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#schema)でサンドボックスのサポートを宣言する必要があります。

次のサンプルコードは、サンドボックスのサポートを宣言しています。

```json
{
  "id": "com.invoicing.[YOUR_APP]",
  "version": "1.2.3",
  "name": "[YOUR APP] Shipment Invoicing",
  "icon": "./[YOUR_APP]_icon_32.png",
  "distribution_type": "public",
  "sandbox_install_compatible": true
}
```

### サンドボックス接続について

ユーザーが公開アプリをサンドボックスにインストールすると、管理対象のサンドボックスに接続されます。これは、本番環境またはテスト環境のサンドボックスにアプリをインストールした場合の動作とは異なります。

- ユーザーがサンドボックスにアプリをインストールすると、マネージドサンドボックスへの接続が確立されます。

- ユーザーが本番環境にアプリをインストールすると、本番環境とテスト環境のサンドボックスに接続されます。

- ユーザーがテスト環境サンドボックスにアプリをインストールすると、テスト環境サンドボックスに接続されます。

### Webhook イベントの設定

アプリがユーザーのインストールのイベントをリッスンする場合は、サンドボックスにインストールされたアプリを処理するための追加設定が必要です。

- マネージドサンドボックス内で、サンドボックスイベント用の新しい Webhook を作成します。

- ユーザーがアプリをサンドボックスにインストールした場合、Stripe は該当するイベントをマネージドサンドボックスのエンドポイントにのみ送信します。

- サンドボックス固有のイベントを処理するように、サーバー側のロジックを更新します。

> インストール環境がイベントの動作に与える影響については、[イベントの動作](https://docs.stripe.com/stripe-apps/build-backend.md#event-behavior-depends-on-install-mode)で詳細をご確認ください。

### 署名シークレットの取得

Webhook の場合、マネージドサンドボックス内から[署名シークレットを取得](https://docs.stripe.com/webhooks/signature.md#check-the-endpoint-secret)しなければならない場合もあります。

### API キーの設定

管理対象サンドボックスには、サンドボックスでのインストール用の呼び出しに使用する独自の [API キー](https://docs.stripe.com/keys.md)セットがあります。サンドボックス固有の Webhook やイベントに応答する場合は、これらの[管理対象サンドボックスキー](https://docs.stripe.com/sandboxes/dashboard/manage-access.md)を使用する必要があります。

マネージドサンドボックス内に、サンドボックスへのインストールに使用する正規の API キーがあります。

### OAuth サンドボックスリンクの確認

本番環境、テスト環境サンドボックス、および一般的なサンドボックスの OAuth URL は、アプリ設定の[外部テスト](https://docs.stripe.com/stripe-apps/test-app.md)タブで確認できます。

アプリで RAK 認証またはプラットフォーム認証を使用する場合、変更は必要ありません。

## サンドボックスでのアプリのテスト

サンドボックスへのインストールを処理するようにアプリを更新したら、独自のサンドボックスでアプリをテストできます。

1. メインアカウントで、アップロードしたサンドボックスに対応する[外部テストリンクを作成](https://docs.stripe.com/stripe-apps/test-app.md)します。 for the sandbox-enabled version you just uploaded.

2. 新しいサンドボックスを作成して、更新したアプリをテストします。その後、新しいサンドボックスを開きます。

3. 新しいブラウザウィンドウで、先ほど作成した外部テスト用のリンクにアクセスして、アプリをインストールします。

4. サンドボックスにインストールしたアプリが想定どおりに動作するかどうかをテストします。

### サンドボックス API キーと Webhook の動作の検証

[Workbench](https://docs.stripe.com/workbench.md) を使用して、サンドボックスへのインストールが正しく機能しているかどうかを検証できます。

- _テストサンドボックス_内でいくつかのサンプルアクションを実行します。

- 次に、_マネージドサンドボックス_内で Workbench を開きます。

ワークベンチを使用して、[API ログの確認](https://docs.stripe.com/workbench/guides.md#view-logs-by-source)や[イベントのフィルタリング](https://docs.stripe.com/workbench/guides.md#filter-events)など、アプリの動作を検査します。アプリが正しく更新されていれば、サンプルアクションのすべての API コールと Webhook イベントを確認できます。

想定されているイベントやレスポンスが表示されない場合は、管理対象のサンドボックス内にいるかどうかを再確認してください。また、サンドボックス固有の Webhook エンドポイントを設定していること、およびアプリが適切なサンドボックス API キーを使用しているかどうかも確認してください。

### アプリを提出して審査を受ける

サンドボックスのサポートを有効にし、サンドボックス内でアプリが想定どおりに動作することを確認したら、[アプリを審査に提出する](https://docs.stripe.com/stripe-apps/publish-app.md)ことができます。アプリのサンドボックスのサポートは、[アプリの審査プロセス](https://docs.stripe.com/stripe-apps/review-requirements.md)の一環として確認され、アプリ一覧の詳細ページに表示されます。