---
title: "インストールリンクとディープリンク | Tajo"
description: "アプリ配布用のインストール URL と、特定のアプリ画面へ遷移させるディープリンクを生成します"
url: https://tajo.io/jp/docs/stripe-apps/install-links/
markdown: https://tajo.io/jp/docs/stripe-apps/install-links.md
lang: ja-JP
author: "Set Noa"
author_url: https://tajo.io/jp/set-noa/
robots: noindex
---

先行利用を申し込む

お名前と会社のメールアドレスを入力してください。Tajoへのアクセス申請を確認するためのリンクをメールでお送りします。

# インストールリンクとディープリンク

[Set Noa](https://tajo.io/jp/set-noa/)

インストールリンクを使うと、マーケットプレイス以外の経路で Stripe App を配布できます。一方、ディープリンクはインストール済みアプリの特定の画面へ直接ユーザーを案内します。どちらも、スムーズなオンボーディングと連携フローに欠かせません。

Caution

**ステータス: 予定、未構築です。** Tajo には Stripe App がないため、このセクションの内容は現時点で何もインストールできません。このページに登場するアプリ識別子、URL、認証情報はすべて説明用のプレースホルダーであり、実際に動作するエンドポイントではありません。

## インストールリンク

インストールリンクは、加盟店がアプリをインストールするための直接 URL です。ユーザーがインストールリンクをクリックすると、Stripe がインストールフローを処理し、指定した URI にリダイレクトします。

### 前提条件

インストールリンクを使う前に、アプリのマニフェストで `allowed_redirect_uris` を設定します。

```json
{
  "id": "com.tajo.brevo-integration",
  "allowed_redirect_uris": [
    "https://tajo.io/stripe/callback",
    "https://tajo.io/stripe/oauth/complete"
  ]
}
```

### インストールリンクの形式

```
https://marketplace.stripe.com/oauth/v2/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&state=STATE_VALUE
```

| パラメーター | 必須 | 説明 |
| --- | --- | --- |
| `client_id` | はい | アプリの ID（例: `com.tajo.brevo-integration`） |
| `redirect_uri` | はい | `allowed_redirect_uris` のいずれかと一致する必要があります |
| `state` | 推奨 | CSRF 対策用のランダムな文字列 |

### リダイレクトパラメーター

インストールが成功すると、Stripe は次のクエリパラメーターを付けて `redirect_uri` にユーザーをリダイレクトします。

| パラメーター | 説明 |
| --- | --- |
| `user_id` | インストールを行ったアカウントの Stripe ユーザー ID |
| `account_id` | Stripe のアカウント ID（例: `acct_xxxxx`） |
| `state` | 指定した `state` の値（CSRF 検証用） |
| `install_signature` | インストールが正当であることを検証する HMAC 署名 |

リダイレクト URL の例:

```
https://tajo.io/stripe/callback
  ?user_id=usr_xxxxx
  &account_id=acct_xxxxx
  &state=abc123random
  &install_signature=sig_xxxxx
```

### CSRF 対策

クロスサイトリクエストフォージェリ攻撃を防ぐため、必ず `state` パラメーターを使用してください。

```javascript
import crypto from 'crypto';

// Generate a random state value and store it in the session
const generateInstallLink = (req, res) => {
  const state = crypto.randomBytes(32).toString('hex');

  // Store state in session for later verification
  req.session.stripeInstallState = state;

  const installUrl = new URL('https://marketplace.stripe.com/oauth/v2/authorize');
  installUrl.searchParams.set('client_id', 'com.tajo.brevo-integration');
  installUrl.searchParams.set('redirect_uri', 'https://tajo.io/stripe/callback');
  installUrl.searchParams.set('state', state);

  res.redirect(installUrl.toString());
};

// Handle the redirect callback
const handleInstallCallback = async (req, res) => {
  const { state, user_id, account_id, install_signature } = req.query;

  // Verify state matches what we stored
  if (state !== req.session.stripeInstallState) {
    return res.status(403).json({ error: 'Invalid state parameter' });
  }

  // Clear the stored state
  delete req.session.stripeInstallState;

  // Verify the install signature
  if (!verifyInstallSignature(install_signature, account_id)) {
    return res.status(403).json({ error: 'Invalid install signature' });
  }

  // Process the successful installation
  await processInstallation(user_id, account_id);

  res.redirect('/dashboard/stripe-connected');
};
```

### 署名の検証

アプリの署名シークレットを使って `install_signature` を検証します。

```javascript
import crypto from 'crypto';

const verifyInstallSignature = (signature, accountId) => {
  const signingSecret = process.env.STRIPE_APP_SIGNING_SECRET;

  const expectedSignature = crypto
    .createHmac('sha256', signingSecret)
    .update(accountId)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
};
```

Caution

タイミング攻撃を防ぐため、署名の比較には必ず `crypto.timingSafeEqual` を使用してください。単純な文字列比較（`===`）は使わないでください。

### 署名シークレット

アプリの署名シークレットは、Stripe ダッシュボードのアプリ設定から取得できます。次の用途に使用します。

- リダイレクトコールバックのインストール署名を検証する
- Stripe から届く Webhook のペイロードを検証する
- 自社バックエンドと Stripe の間のリクエストを認証する

署名シークレットは安全に保管してください。

```bash
# Set as environment variable
export STRIPE_APP_SIGNING_SECRET="whsec_xxxxx"
```

署名シークレットをソースコードに直接書き込んだり、バージョン管理にコミットしたりしないでください。

## ディープリンク

ディープリンクは、インストール済みの Stripe App 内の特定の画面へ直接ユーザーを案内します。メール、通知、サポートページといった外部からの導線で、目的のアプリ画面にユーザーを誘導する際に使用します。

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

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

| 構成要素 | 説明 | 例 |
| --- | --- | --- |
| `MODE` | `live` または `test` | `live` |
| `acct_ID` | 対象の Stripe アカウント ID | `acct_1234567890` |
| `PAGE` | ダッシュボードのページパス | `customers/cus_xxxxx` |
| `APP_ID` | アプリの ID | `com.tajo.brevo-integration` |
| `TARGET` | `drawer` または `modal` | `drawer` |
| `VIEWPORT_ID` | 開くビューポート | `stripe.dashboard.customer.detail` |

### drawer と modal の使い分け

| ターゲット | 挙動 | ユースケース |
| --- | --- | --- |
| `drawer` | アプリをサイドパネル（ドロワー）で開きます | 通常のアプリ操作、ページと並べて文脈を確認する場合 |
| `modal` | アプリを全画面のモーダルで開きます | 集中して進めるワークフロー、オンボーディング、入力項目の多いフォーム |

### ディープリンクの例

#### 顧客詳細画面をドロワーで開く

```
https://dashboard.stripe.com/live/acct_xxxxx/customers/cus_xxxxx
  ?apps[com.tajo.brevo-integration][drawer]=stripe.dashboard.customer.detail
```

#### 設定画面をモーダルで開く

```
https://dashboard.stripe.com/live/acct_xxxxx/settings
  ?apps[com.tajo.brevo-integration][modal]=stripe.dashboard.settings
```

#### オンボーディングフローを開く

```
https://dashboard.stripe.com/live/acct_xxxxx/dashboard
  ?apps[com.tajo.brevo-integration][modal]=stripe.dashboard.onboarding
```

#### テストモードで決済詳細画面を開く

```
https://dashboard.stripe.com/test/acct_xxxxx/payments/pi_xxxxx
  ?apps[com.tajo.brevo-integration][drawer]=stripe.dashboard.payment.detail
```

### ディープリンクをプログラムから生成する

```javascript
const generateDeepLink = ({
  accountId,
  mode = 'live',
  page,
  appId = 'com.tajo.brevo-integration',
  target = 'drawer',
  viewport,
}) => {
  const baseUrl = `https://dashboard.stripe.com/${mode}/${accountId}/${page}`;
  const params = new URLSearchParams();
  params.set(`apps[${appId}][${target}]`, viewport);

  return `${baseUrl}?${params.toString()}`;
};

// Generate a link to view a customer's Brevo profile
const customerLink = generateDeepLink({
  accountId: 'acct_xxxxx',
  page: 'customers/cus_xxxxx',
  viewport: 'stripe.dashboard.customer.detail',
});

// Generate a link to app settings
const settingsLink = generateDeepLink({
  accountId: 'acct_xxxxx',
  page: 'settings',
  viewport: 'stripe.dashboard.settings',
  target: 'modal',
});
```

### 各種コミュニケーションでディープリンクを使う

ディープリンクは、特に次のような場面で役立ちます。

- **メール通知**: 「この顧客の Brevo 同期状況を確認する」
- **サポートからの返信**: 「こちらから連携設定を確認できます」
- **オンボーディングメール**: 「Brevo の設定を完了しましょう」
- **エラー通知**: 「顧客 X の同期エラーを確認する」

```html
<!-- Example in an email template -->
<a href="https://dashboard.stripe.com/live/acct_xxxxx/customers/cus_xxxxx?apps[com.tajo.brevo-integration][drawer]=stripe.dashboard.customer.detail">
  View Brevo Profile in Stripe
</a>
```

## インストールリンクとディープリンクを組み合わせる

オンボーディング体験を最適にするには、インストールリンクとインストール後のディープリンクを組み合わせます。

1. ユーザーが自社サイトやメールから **インストールリンク** をクリックします
2. ユーザーがアプリをインストールし、コールバック URL にリダイレクトされます
3. コールバックでインストール処理を行い、オンボーディング用のビューポートを開く **ディープリンク** にユーザーをリダイレクトします

```javascript
const handleInstallCallback = async (req, res) => {
  const { account_id, install_signature, state } = req.query;

  // Verify state and signature
  // ... (verification code)

  // Process installation
  await processInstallation(account_id);

  // Redirect to the app's onboarding view via deep link
  const onboardingLink = generateDeepLink({
    accountId: account_id,
    page: 'dashboard',
    viewport: 'stripe.dashboard.onboarding',
    target: 'modal',
  });

  res.redirect(onboardingLink);
};
```

Tip

すべての環境で正しく動作することを確認するため、インストールリンクとディープリンクは live モードと test モードの両方でテストしてください。