先行利用を申し込む

お名前とメールアドレスまたは電話番号をご入力ください。Tajo のアクセス方法をご案内します。

このページの内容

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

stripe-app.json マニフェストファイルは、Stripe App の中心となる設定ファイルです。アプリの識別情報、権限、UI ビュー、セキュリティポリシー、インストール後の動作をここで宣言します。

マニフェストの全体例 

{
  "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": "Subscribe to real-time 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.tajo.io",
        "https://api.brevo.com"
      ],
      "image-src": [
        "https://cdn.tajo.io",
        "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.tajo.io/v1",
    "SYNC_INTERVAL_SECONDS": "300"
  }
}

スキーマリファレンス

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

フィールド型必須説明
idstringはい逆ドメイン記法（スラッグ形式）による一意のアプリ識別子
versionstringはいセマンティックバージョンの文字列（例: "1.2.0"）
namestringはいマーケットプレイスに表示される名称（最大 35 文字）
iconstringはいアプリアイコンファイルへの相対パス（300x300 の PNG または SVG）
distribution_typestringはいマーケットプレイス向けは "public"、社内利用は "private"
sandbox_install_compatiblebooleanいいえサンドボックス／テストモードにインストールできるかどうか
stripe_api_access_typestringいいえAPI へのアクセス方式: "oauth" または "api_key"
allowed_redirect_urisstring[]いいえインストールフローで許可する OAuth リダイレクト URI
permissionsPermissionRequest[]はい権限リクエストの配列
ui_extensionUIExtensionManifestいいえUI 拡張の設定
post_install_actionPostInstallActionいいえアプリのインストール後に実行するアクション
constantsobjectいいえ実行時にアプリから参照できるキーと値のペア

id

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

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

version

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

"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 つずつ宣言します。

{
  "permission": "customer_read",
  "purpose": "Read customer profiles to sync with Brevo contacts"
}
フィールド型必須説明
permissionstringはい権限の識別子（権限リファレンスを参照）
purposestringはいその権限が必要な理由を人が読んで分かる形で説明した文

purpose を書くときの指針:

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

UIExtensionManifest

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

{
  "ui_extension": {
    "views": [...],
    "content_security_policy": {...}
  }
}
フィールド型必須説明
viewsViewManifest[]はいビュー宣言の配列
content_security_policyCSPRequestいいえ外部リソースに対する Content Security Policy

ViewManifest

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

{
  "viewport": "stripe.dashboard.customer.detail",
  "component": "CustomerDetailView"
}
フィールド型必須説明
viewportstringはいこのビューを描画するダッシュボード上の位置（ビューポートリファレンスを参照）
componentstringはい描画する React コンポーネントの名前（エクスポートしたコンポーネント名と一致させます）

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

"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 は、アプリが接続できる外部ドメインを制御します。

{
  "content_security_policy": {
    "connect-src": [
      "https://api.tajo.io",
      "https://api.brevo.com"
    ],
    "image-src": [
      "https://cdn.tajo.io"
    ],
    "purpose": "Connect to Tajo API for data sync and load images from CDN"
  }
}
フィールド型必須説明
connect-srcstring[]いいえアプリがネットワークリクエストを送信できるドメイン
image-srcstring[]いいえアプリが画像を読み込めるドメイン
purposestringはいこれらの外部接続が必要な理由の説明

Caution

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

PostInstallAction

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

{
  "post_install_action": {
    "type": "onboarding"
  }
}
フィールド型必須説明
typestringはいアクションの種類（下記を参照）
urlstring条件付きexternal 種別のアクションで使う URL

アクションの種類

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

例:

// 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"
  }
}

実装パターンの詳細はインストール後アクションのガイドを参照してください。

定数

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

{
  "constants": {
    "API_BASE_URL": "https://api.tajo.io/v1",
    "SYNC_INTERVAL_SECONDS": "300",
    "MAX_BATCH_SIZE": "100"
  }
}
  • すべての値は文字列である必要があります
  • 定数はビルド時にアプリへ埋め込まれます
  • 環境ごとに変わる設定値には定数を使います
  • シークレットや API キーを定数として保存してはいけません。代わりに Secret Store API を使用してください

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

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


const apiUrl = constants.API_BASE_URL;

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

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

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

検証

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

Terminal window
# Validate manifest syntax and schema
stripe apps validate


# Check for common issues
stripe apps check

よくある検証エラー:

エラー原因対処
Invalid permission未知の権限識別子権限リファレンスを確認します
Invalid viewport未知のビューポート識別子ビューポートリファレンスを確認します
Missing purposepurpose フィールドのない権限各権限に purpose の文字列を追加します
Invalid versionsemver 形式でないバージョン文字列MAJOR.MINOR.PATCH の形式を使用します
Icon not foundアイコンのパスを解決できない指定したパスにアイコンファイルがあるか確認します

先行利用を申し込む

お名前とメールアドレスまたは電話番号をご入力ください。Tajo のアクセス方法をご案内します。

自動判定
AIアシスタント

こんにちは！ドキュメントについて何でもお聞きください。