On this page

App Manifest 参考

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

完整 Manifest 示例 

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

Schema 参考

顶级字段

字段类型必需描述
idstring是反向域名格式（slug 格式）的唯一应用标识符
versionstring是语义版本字符串（例如 "1.2.0"）
namestring是marketplace 上显示的名称（最多 35 个字符）
iconstring是应用图标文件的相对路径（300x300 PNG 或 SVG）
distribution_typestring是marketplace 用 "public"，内部使用用 "private"
sandbox_install_compatibleboolean否应用是否可以在 sandbox/test 模式下安装
stripe_api_access_typestring否API 访问方式："oauth" 或 "api_key"
allowed_redirect_urisstring[]否安装流程允许的 OAuth 重定向 URI
permissionsPermissionRequest[]是权限请求数组
ui_extensionUIExtensionManifest否UI 扩展配置
post_install_actionPostInstallAction否应用安装后执行的操作
constantsobject否在应用运行时可访问的键值对

id

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

"id": "com.tajo.brevo-integration"
  • 在所有 Stripe Apps 中必须全局唯一
  • 只使用小写字母、数字、连字符和点
  • 应用创建后不能更改
  • 决定应用在 marketplace 上的 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 权限：

{
  "permission": "customer_read",
  "purpose": "Read customer profiles to sync with Brevo contacts"
}
字段类型必需描述
permissionstring是权限标识符（参见权限参考）
purposestring是说明为什么需要此权限的人类可读解释

目的说明指南：

  • 写清晰、具体的解释，让商家能够理解
  • 解释权限用于什么，而不仅仅是它授予什么
  • 保持简洁（一句话）
  • 避免技术术语

UIExtensionManifest

配置应用的 UI 组件：

{
  "ui_extension": {
    "views": [...],
    "content_security_policy": {...}
  }
}
字段类型必需描述
viewsViewManifest[]是视图声明数组
content_security_policyCSPRequest否外部资源的 Content Security Policy

ViewManifest

每个视图将 React 组件映射到 Stripe Dashboard viewport：

{
  "viewport": "stripe.dashboard.customer.detail",
  "component": "CustomerDetailView"
}
字段类型必需描述
viewportstring是此视图渲染的 Dashboard 位置（参见Viewports 参考）
componentstring是要渲染的 React 组件名称（必须与导出的组件名称匹配）

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

"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"在 Dashboard 中打开应用的引导视图
"settings"在 Dashboard 中打开应用的设置视图
"external"将用户重定向到外部 URL（需要 url 字段）

示例：

// 打开引导流程
{
  "post_install_action": {
    "type": "onboarding"
  }
}


// 打开设置页面
{
  "post_install_action": {
    "type": "settings"
  }
}


// 重定向到外部设置
{
  "post_install_action": {
    "type": "external",
    "url": "https://app.tajo.io/stripe/setup"
  }
}

请参阅 Post-Install Actions 指南 了解详细的实现模式。

Constants

定义在应用运行时可访问的静态键值对：

{
  "constants": {
    "API_BASE_URL": "https://api.tajo.io/v1",
    "SYNC_INTERVAL_SECONDS": "300",
    "MAX_BATCH_SIZE": "100"
  }
}
  • 所有值必须是字符串
  • Constants 在构建时嵌入应用中
  • 对在环境之间变化的配置使用 constants
  • 绝不将 secrets 或 API 密钥存储为 constants, 使用 Secret Store API 代替

在应用代码中访问 constants：

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


const apiUrl = constants.API_BASE_URL;

开发扩展 Manifest

在本地开发过程中，有额外的字段可用：

{
  "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：

Terminal window
# 验证 manifest 语法和 schema
stripe apps validate


# 检查常见问题
stripe apps check

常见验证错误：

错误原因修复方法
Invalid permission未知权限标识符检查权限参考
Invalid viewport未知 viewport 标识符检查 Viewports 参考
Missing purpose权限缺少 purpose 字段为每个权限添加 purpose 字符串
Invalid version非 semver 版本字符串使用格式 MAJOR.MINOR.PATCH
Icon not found图标路径无法解析验证图标文件存在于指定路径

Subscribe to updates

developer-docs

Drop your email or phone number — we'll send you what matters next.

AI 助手

你好！关于文档有任何问题都可以问我。

免费开始使用Brevo