---
title: "アプリマニフェストリファレンス | Tajo"
description: "Stripe Apps の設定に使う stripe-app.json マニフェストファイルの完全なスキーマリファレンス"
url: https://tajo.io/jp/docs/stripe-apps/app-manifest/
markdown: https://tajo.io/jp/docs/stripe-apps/app-manifest.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.json` マニフェストファイルは、Stripe App の中心となる設定ファイルです。アプリの識別情報、権限、UI ビュー、セキュリティポリシー、インストール後の動作をここで宣言します。

Caution

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

## マニフェストの全体例

```json
{
  "id": "com.tajo.brevo-integration",
  "version": "1.2.0",
  "name": "Tajo for Brevo",
  "icon": "./assets/icon.png",
  "distribution_type": "public",
  "sandbox_install_compatible": true,
  "stripe_api_access_type": "oauth",
  "allowed_redirect_uris": [
    "https://tajo.io/stripe/callback",
    "https://tajo.io/stripe/oauth/complete"
  ],
  "permissions": [
    {
      "permission": "customer_read",
      "purpose": "Read customer profiles to sync with Brevo contacts"
    },
    {
      "permission": "customer_write",
      "purpose": "Update customer metadata with Brevo sync status"
    },
    {
      "permission": "charge_read",
      "purpose": "Access payment history for Brevo event tracking"
    },
    {
      "permission": "product_read",
      "purpose": "Sync product catalog to Brevo for personalized campaigns"
    },
    {
      "permission": "event_read",
      "purpose": "Read events for Brevo automation triggers"
    },
    {
      "permission": "invoice_read",
      "purpose": "Track invoice lifecycle events in Brevo"
    }
  ],
  "ui_extension": {
    "views": [
      {
        "viewport": "stripe.dashboard.customer.detail",
        "component": "CustomerDetailView"
      },
      {
        "viewport": "stripe.dashboard.customer.list",
        "component": "CustomerListView"
      },
      {
        "viewport": "stripe.dashboard.home.overview",
        "component": "OverviewView"
      },
      {
        "viewport": "stripe.dashboard.drawer.default",
        "component": "DrawerView"
      },
      {
        "viewport": "stripe.dashboard.settings",
        "component": "SettingsView"
      },
      {
        "viewport": "stripe.dashboard.onboarding",
        "component": "OnboardingView"
      }
    ],
    "content_security_policy": {
      "connect-src": [
        "https://api.example.com",
        "https://api.brevo.com"
      ],
      "image-src": [
        "https://cdn.example.com",
        "https://assets.brevo.com"
      ],
      "purpose": "Connect to Tajo API for data sync and Brevo API for contact management"
    }
  },
  "post_install_action": {
    "type": "onboarding"
  },
  "constants": {
    "API_BASE_URL": "https://api.example.com/v1",
    "SYNC_INTERVAL_SECONDS": "300"
  }
}
```

## スキーマリファレンス

### トップレベルのフィールド

| フィールド | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `id` | string | はい | 逆ドメイン記法（スラッグ形式）による一意のアプリ識別子 |
| `version` | string | はい | セマンティックバージョンの文字列（例: `"1.2.0"`） |
| `name` | string | はい | マーケットプレイスに表示される名称（最大 35 文字） |
| `icon` | string | はい | アプリアイコンファイルへの相対パス（300x300 の PNG または SVG） |
| `distribution_type` | string | はい | マーケットプレイス向けは `"public"`、社内利用は `"private"` |
| `sandbox_install_compatible` | boolean | いいえ | サンドボックス／テストモードにインストールできるかどうか |
| `stripe_api_access_type` | string | いいえ | API へのアクセス方式: `"oauth"` または `"api_key"` |
| `allowed_redirect_uris` | string\[\] | いいえ | インストールフローで許可する OAuth リダイレクト URI |
| `permissions` | PermissionRequest\[\] | はい | 権限リクエストの配列 |
| `ui_extension` | UIExtensionManifest | いいえ | UI 拡張の設定 |
| `post_install_action` | PostInstallAction | いいえ | アプリのインストール後に実行するアクション |
| `constants` | object | いいえ | 実行時にアプリから参照できるキーと値のペア |

### id

アプリ識別子はスラッグ形式の文字列で、通常は逆ドメイン記法で記述します。

```json
"id": "com.tajo.brevo-integration"
```

- すべての Stripe Apps を通じて一意である必要があります
- 使用できるのは小文字、数字、ハイフン、ドットのみです
- アプリの作成後は変更できません
- マーケットプレイス上のアプリの URL を決定します

### version

セマンティックバージョニングに従います。

```json
"version": "1.2.0"
```

- **MAJOR**: 破壊的変更、または大きな機能追加
- **MINOR**: 後方互換性のある新機能
- **PATCH**: バグ修正と細かな改善
- アップロードのたびにインクリメントする必要があります

### distribution\_type

アプリをインストールできる相手を制御します。

| 値 | 説明 |
| --- | --- |
| `"public"` | Stripe App Marketplace ですべてのユーザーが利用できます |
| `"private"` | 自分の Stripe アカウントからのみインストールできます |

### stripe\_api\_access\_type

アプリが Stripe API に対してどう認証するかを決めます。

| 値 | 説明 |
| --- | --- |
| `"oauth"` | 認証に OAuth 2.0 フローを使用します（公開アプリに推奨） |
| `"api_key"` | 制限付き API キーを使用します（非公開アプリに適しています） |

## PermissionRequest

各権限リクエストは、アプリが必要とする Stripe API の権限を 1 つずつ宣言します。

```json
{
  "permission": "customer_read",
  "purpose": "Read customer profiles to sync with Brevo contacts"
}
```

| フィールド | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `permission` | string | はい | 権限の識別子（[権限リファレンス](https://tajo.io/jp/docs/stripe-apps/permissions)を参照） |
| `purpose` | string | はい | その権限が必要な理由を人が読んで分かる形で説明した文 |

**purpose を書くときの指針:**

- 加盟店が理解できる、明確で具体的な説明を書きます
- 権限が何を許可するかではなく、何のために使うかを説明します
- 説明は簡潔に（1 文）まとめます
- 専門用語は避けます

## UIExtensionManifest

アプリの UI コンポーネントを設定します。

```json
{
  "ui_extension": {
    "views": [...],
    "content_security_policy": {...}
  }
}
```

| フィールド | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `views` | ViewManifest\[\] | はい | ビュー宣言の配列 |
| `content_security_policy` | CSPRequest | いいえ | 外部リソースに対する Content Security Policy |

## ViewManifest

各ビューは、React コンポーネントを Stripe ダッシュボードのビューポートに対応付けます。

```json
{
  "viewport": "stripe.dashboard.customer.detail",
  "component": "CustomerDetailView"
}
```

| フィールド | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `viewport` | string | はい | このビューを描画するダッシュボード上の位置（[ビューポートリファレンス](https://tajo.io/jp/docs/stripe-apps/viewports)を参照） |
| `component` | string | はい | 描画する React コンポーネントの名前（エクスポートしたコンポーネント名と一致させます） |

1 つのアプリで、複数のビューポート向けにビューを宣言できます。

```json
"views": [
  {
    "viewport": "stripe.dashboard.customer.detail",
    "component": "CustomerDetailView"
  },
  {
    "viewport": "stripe.dashboard.payment.detail",
    "component": "PaymentDetailView"
  },
  {
    "viewport": "stripe.dashboard.home.overview",
    "component": "OverviewView"
  }
]
```

## CSPRequest

Content Security Policy は、アプリが接続できる外部ドメインを制御します。

```json
{
  "content_security_policy": {
    "connect-src": [
      "https://api.example.com",
      "https://api.brevo.com"
    ],
    "image-src": [
      "https://cdn.example.com"
    ],
    "purpose": "Connect to Tajo API for data sync and load images from CDN"
  }
}
```

| フィールド | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `connect-src` | string\[\] | いいえ | アプリがネットワークリクエストを送信できるドメイン |
| `image-src` | string\[\] | いいえ | アプリが画像を読み込めるドメイン |
| `purpose` | string | はい | これらの外部接続が必要な理由の説明 |

Caution

アプリが実際に接続する必要のあるドメインだけを記載してください。CSP のエントリが多すぎると、審査がより厳しくなる場合があります。

## PostInstallAction

ユーザーがアプリをインストールした直後の動作を設定します。

```json
{
  "post_install_action": {
    "type": "onboarding"
  }
}
```

| フィールド | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `type` | string | はい | アクションの種類（下記を参照） |
| `url` | string | 条件付き | `external` 種別のアクションで使う URL |

### アクションの種類

| 種類 | 動作 |
| --- | --- |
| `"onboarding"` | ダッシュボードでアプリのオンボーディングビューを開きます |
| `"settings"` | ダッシュボードでアプリの設定ビューを開きます |
| `"external"` | ユーザーを外部 URL にリダイレクトします（`url` フィールドが必要） |

例:

```json
// Open onboarding flow
{
  "post_install_action": {
    "type": "onboarding"
  }
}

// Open settings page
{
  "post_install_action": {
    "type": "settings"
  }
}

// Redirect to external setup
{
  "post_install_action": {
    "type": "external",
    "url": "https://app.tajo.io/stripe/setup"
  }
}
```

実装パターンの詳細は[インストール後アクションのガイド](https://tajo.io/jp/docs/stripe-apps/post-install)を参照してください。

## 定数

アプリの実行時に参照できる静的なキーと値のペアを定義します。

```json
{
  "constants": {
    "API_BASE_URL": "https://api.example.com/v1",
    "SYNC_INTERVAL_SECONDS": "300",
    "MAX_BATCH_SIZE": "100"
  }
}
```

- すべての値は文字列である必要があります
- 定数はビルド時にアプリへ埋め込まれます
- 環境ごとに変わる設定値には定数を使います
- シークレットや API キーを定数として保存しては**いけません**。代わりに Secret Store API を使用してください

アプリのコードから定数を参照します。

```typescript
import { constants } from '@stripe/ui-extension-sdk/constants';

const apiUrl = constants.API_BASE_URL;
```

## 開発用の拡張マニフェスト

ローカル開発中は、追加のフィールドを利用できます。

```json
{
  "id": "com.tajo.brevo-integration",
  "version": "0.1.0",
  "name": "Tajo for Brevo (Dev)",
  "icon": "./assets/icon-dev.png",
  "distribution_type": "private",
  "sandbox_install_compatible": true,
  "dev": {
    "hot_reload": true,
    "port": 4242
  }
}
```

`dev` セクションは、本番ビルドとアプリのアップロード時に取り除かれます。ローカル開発を便利にする設定にのみ使用してください。

## 検証

アップロードの前にマニフェストを検証します。

```bash
# Validate manifest syntax and schema
stripe apps validate

# Check for common issues
stripe apps check
```

よくある検証エラー:

| エラー | 原因 | 対処 |
| --- | --- | --- |
| `Invalid permission` | 未知の権限識別子 | [権限リファレンス](https://tajo.io/jp/docs/stripe-apps/permissions)を確認します |
| `Invalid viewport` | 未知のビューポート識別子 | [ビューポートリファレンス](https://tajo.io/jp/docs/stripe-apps/viewports)を確認します |
| `Missing purpose` | purpose フィールドのない権限 | 各権限に purpose の文字列を追加します |
| `Invalid version` | semver 形式でないバージョン文字列 | `MAJOR.MINOR.PATCH` の形式を使用します |
| `Icon not found` | アイコンのパスを解決できない | 指定したパスにアイコンファイルがあるか確認します |