# ディープリンクを追加する

Stripe アプリにユーザーを誘導するディープリンクを作成します。

> ディープリンクは、メールや外部ウェブサイトなどの外部リンクにのみ使用してください。Stripe アプリ内でレンダリングされるリンクには、代わりに[ルート記述子](https://docs.stripe.com/stripe-apps/route-descriptors.md)を使用してください。これにより、アプリ内のナビゲーションに[いくつかの利点](https://docs.stripe.com/stripe-apps/route-descriptors.md#benefits-of-route-descriptors)がもたらされます。

ディープリンクは、ユーザーがダッシュボードでアプリを開くために必要なナビゲーションの手順を減らす URL です。ディープリンクは、メールやウェブサイトなどの外部コンテキスト、または[ OAuth 認証ワークフローを作成](https://docs.stripe.com/stripe-apps/pkce-oauth-flow.md)する場合にのみ使用してください。アプリ内のページ間を移動するには、代わりに[ルート記述子](https://docs.stripe.com/stripe-apps/route-descriptors.md)を使用してください。

## Before you begin

アプリを表示するダッシュボードページにユーザーを誘導するには、[UI 機能](https://docs.stripe.com/stripe-apps/build-ui.md)を備えたアプリが必要です。

## ディープリンク URL を作成する

ディープリンクの URL を作成するには、以下を使用する必要があります。

- アプリがインストールされている Stripe アカウント ID です。詳細については、[ユーザーコンテキスト](https://docs.stripe.com/stripe-apps/reference/extensions-sdk-api.md#user-context)をご覧ください。
- *ビュー* (A view is a React component that creates UI extensions in the Stripe Dashboard)を定義した Dashboard ページの URL です。
- アプリと、アプリを開く場所を指定する `apps` パラメーターです。
- アプリケーション ID です。[`stripe-app.json` マニフェストファイルの `id` フィールド](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#schema)で指定されます。

> 下位互換性のため、`open_drawer_app` パラメーターを使用するレガシー形式も引き続き利用できますが、最新の `apps` パラメーター形式を推奨します。

### ディープリンクの形式

ディープリンク URL の構造は次のとおりです。

```
https://dashboard.stripe.com/<ACCOUNT_ID>/<MODE>/<PAGE>?apps[<APP_ID>][TARGET]=VIEWPORT_ID
```

各項目は次のとおりです:

- **ACCOUNT\_ID**: Stripe アカウント ID (`acct_` で始まる)
- **MODE**: *sandboxes* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes)(*test mode sandbox* (Every Stripe account includes the test mode sandbox. It shares some settings with live mode, has characteristics that differ from other sandboxes you create, but you can't delete it) を含む)には `test` を使用するか、本番環境では値を省略します
- **PAGE**: 表示する Dashboard ページ (`customers`、`invoices`、`dashboard` など)
- **APP\_ID**: マニフェストファイルに記載されたアプリケーション ID
- **ターゲット** : `ドロワー` (ドロワーを使用する場合) や`モーダル` (アカウント登録を開く場合) など、アプリを開く場所
- **VIEWPORT\_ID**: マニフェストファイルで設定したビューポート ID (`stripe.dashboard.payment.list` など)

### 例

Dashboard (`https://dashboard.stripe.com/test/customers?`) の Customers ページで*ビュー* (A view is a React component that creates UI extensions in the Stripe Dashboard)を定義し、アプリケーション ID が `com.example.my-app` の場合:

- *サンドボックス* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes)またはテスト環境のサンドボックスのディープリンクは次のとおりです。

  ```
    <a href="https://dashboard.stripe.com/acct_id/test/customers?apps[com.example.my-app][drawer]=">Deep Link</a>
  ```

- 本番環境のディープリンクは次のようになります。

  ```
  <a href="https://dashboard.stripe.com/acct_id/customers?apps[com.example.my-app][drawer]=">Deep Link</a>
  ```

ビューを定義した Dashboard ページでアプリを開くことができます。たとえば、Dashboard のホームで開くには次のようにします。

```
 <a href="https://dashboard.stripe.com/acct_id/test/dashboard?apps[com.example.my-app][drawer]=">Deep Link</a>
```

アカウント登録モーダルへのディープリンクを作成するには、`drawer` ではなく `modal` を使用します。

```
<a href="https://dashboard.stripe.com/acct_id/dashboard?apps[com.example.my-app][modal]=">Open in Modal</a>
```

## ディープリンクを共有する

ディープリンクをユーザーと共有する際は、必ず本番環境の URL を使用してください。アプリをインストールしたユーザー向けに、メールやウェブサイトなどの外部チャネルでリンクを共有できます。ディープリンクをクリックする前にユーザーがアプリをインストールしていない場合、Stripe により、ダッシュボードで開くことができないクローズドアプリへ誘導されます。

## ディープリンクをテストする

1. アプリをインストールしたユーザーとしてダッシュボードにログインします。

2. ディープリンクをクリックします。

   開けないアプリに移動する場合は、以下を確認してください。

   - `apps` パラメーターが、マニフェストの正しいアプリケーション ID を使用していること
   - URL パスのアカウント ID が正しいこと (形式: `acct_` の後に英数字が続く)
   - ユーザーがそのアカウントにアプリをインストールしていること
   - URL の Dashboard ページに、アプリ用のビューが定義されていること

## See also

- [アプリのマニフェストリファレンス](https://docs.stripe.com/stripe-apps/reference/app-manifest.md)
- [バージョンとリリース](https://docs.stripe.com/stripe-apps/versions-and-releases.md)