申请抢先体验

请填写名字，以及邮箱或手机号。我们会与您联系，提供 Tajo 访问详情。

在本页面

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是在应用市场显示的名称（最多 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

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

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

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

purpose 写法建议：

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

UIExtensionManifest

配置应用的 UI 组件：

{
  "ui_extension": {
    "views": [...],
    "content_security_policy": {...}
  }
}
字段类型必填说明
viewsViewManifest[]是视图声明数组
content_security_policyCSPRequest否针对外部资源的内容安全策略

ViewManifest

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

{
  "viewport": "stripe.dashboard.customer.detail",
  "component": "CustomerDetailView"
}
字段类型必填说明
viewportstring是该视图渲染所在的 Dashboard 位置（参见视口参考）
componentstring是要渲染的 React 组件名称（必须与导出的组件名一致）

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

"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": {
    "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 字段）

示例：

// 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;

面向开发的扩展 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
# Validate manifest syntax and schema
stripe apps validate


# Check for common issues
stripe apps check

常见校验错误：

错误原因修复
Invalid permission未知的权限标识查阅权限参考
Invalid viewport未知的视口标识查阅视口参考
Missing purpose权限缺少 purpose 字段为每条权限补上 purpose 字符串
Invalid version版本号不符合 semver使用 MAJOR.MINOR.PATCH 格式
Icon not found图标路径无法解析确认图标文件位于指定路径

申请抢先体验

请填写名字，以及邮箱或手机号。我们会与您联系，提供 Tajo 访问详情。

自动识别
AI 助手

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