---
title: "App Manifest 参考 | Tajo"
description: "用于配置 Stripe Apps 的 stripe-app.json manifest 文件的完整 schema 参考"
url: https://tajo.io/zh-cn/docs/stripe-apps/app-manifest/
markdown: https://tajo.io/zh-cn/docs/stripe-apps/app-manifest.md
lang: zh-CN
author: "Set Noa"
author_url: https://tajo.io/zh-cn/set-noa/
robots: noindex
---

申请抢先体验

请输入您的名字和公司电子邮箱地址。我们会发送确认 Tajo 访问申请的链接。

# App Manifest 参考

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

`stripe-app.json` manifest 文件是 Stripe App 的核心配置。它声明应用的身份、权限、UI 视图、安全策略以及安装后行为。

Caution

**状态：计划中，尚未构建。** Tajo 没有 Stripe App，因此本章中的任何内容目前都无法安装。本页中的 app 标识、URL 和凭据都是用于示意的占位值，而不是可用的线上端点。

## 完整 manifest 示例

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

## Schema 参考

### 顶层字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | string | 是 | 采用反向域名写法的唯一应用标识（slug 格式） |
| `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

应用标识是 slug 格式的字符串，通常采用反向域名写法：

```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 权限：

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

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `permission` | string | 是 | 权限标识（参见[权限参考](https://tajo.io/zh-cn/docs/stripe-apps/permissions)） |
| `purpose` | string | 是 | 面向人的说明，解释为什么需要该权限 |

**purpose 写法建议：**

- 写出商家能看懂的清晰、具体的说明
- 说明该权限的用途，而不只是它授予了什么
- 描述保持简洁（一句话）
- 避免技术黑话

## UIExtensionManifest

配置应用的 UI 组件：

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

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `views` | ViewManifest\[\] | 是 | 视图声明数组 |
| `content_security_policy` | CSPRequest | 否 | 针对外部资源的内容安全策略 |

## ViewManifest

每个视图把一个 React 组件映射到 Stripe Dashboard 的某个视口：

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

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `viewport` | string | 是 | 该视图渲染所在的 Dashboard 位置（参见[视口参考](https://tajo.io/zh-cn/docs/stripe-apps/viewports)） |
| `component` | string | 是 | 要渲染的 React 组件名称（必须与导出的组件名一致） |

单个应用可以为不同视口声明多个视图：

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

## CSPRequest

内容安全策略控制应用可以连接哪些外部域名：

```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"` | 在 Dashboard 中打开应用的引导视图 |
| `"settings"` | 在 Dashboard 中打开应用的设置视图 |
| `"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/zh-cn/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;
```

## 面向开发的扩展 manifest

本地开发期间可以使用额外字段：

```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` 段在生产构建和应用上传时会被剥离。它只用于本地开发的便利设置。

## 校验

上传前先校验 manifest：

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

# Check for common issues
stripe apps check
```

常见校验错误：

| 错误 | 原因 | 修复 |
| --- | --- | --- |
| `Invalid permission` | 未知的权限标识 | 查阅[权限参考](https://tajo.io/zh-cn/docs/stripe-apps/permissions) |
| `Invalid viewport` | 未知的视口标识 | 查阅[视口参考](https://tajo.io/zh-cn/docs/stripe-apps/viewports) |
| `Missing purpose` | 权限缺少 purpose 字段 | 为每条权限补上 purpose 字符串 |
| `Invalid version` | 版本号不符合 semver | 使用 `MAJOR.MINOR.PATCH` 格式 |
| `Icon not found` | 图标路径无法解析 | 确认图标文件位于指定路径 |