On this page

Embedded Stripe Apps

Embedded Stripe Apps 允许基于 Stripe Connect 构建的平台直接在其自己的 dashboard 中展示第三方 app 功能。使用 Connect embedded components，您可以让 connected accounts 访问 QuickBooks、Xero 和 Mailchimp 等应用，而无需他们访问 Stripe Dashboard。

概述

Embedded apps 使用两个关键的 Connect embedded components：

app-install：在您的平台 UI 中渲染 Stripe App 的安装按钮
app-viewport：在您的平台 UI 中渲染特定的 app viewport

这使平台运营商能够将会计、营销和运营工具直接嵌入到他们的产品中。

支持的 Apps

以下 apps 支持通过 Connect components 嵌入：

App	类别	使用场景
QuickBooks	会计	将付款和发票同步到 QuickBooks
Xero	会计	自动化记账和对账
Mailchimp	营销	同步客户数据用于电子邮件营销活动
Custom Apps	任何	您为平台构建的自定义 Stripe Apps

Tip

Tajo Brevo 集成可以嵌入到 Connect 平台中，允许 connected accounts 通过平台自己的界面将 Stripe 数据同步到 Brevo。

使用 Account Sessions API 进行设置

要嵌入 apps，您需要创建启用了适当 components 的 Account Sessions：

服务器端：创建 Account Session

const stripe = require('stripe')('sk_live_...');

// 为 connected account 创建 Account Session
const accountSession = await stripe.accountSessions.create({
  account: 'acct_connected_account_id',
  components: {
    // 启用 app install component
    app_install: {
      enabled: true,
      features: {
        allowed_apps: [
          'com.tajo.brevo-integration',
          'com.quickbooks.stripe-app'
        ],
      },
    },
    // 启用 app viewport component
    app_viewport: {
      enabled: true,
      features: {
        allowed_apps: [
          'com.tajo.brevo-integration'
        ],
      },
    },
  },
});

// 将 client secret 返回给前端
res.json({ clientSecret: accountSession.client_secret });

客户端：初始化 Connect.js

import { loadConnectAndInitialize } from '@stripe/connect-js';

// 使用 account session 初始化 Connect.js
const stripeConnect = loadConnectAndInitialize({
  publishableKey: 'pk_live_...',
  fetchClientSecret: async () => {
    const response = await fetch('/api/account-session', {
      method: 'POST',
    });
    const { clientSecret } = await response.json();
    return clientSecret;
  },
});

App Install Component

app-install component 渲染一个安装按钮，connected accounts 可以使用它来安装 Stripe App：

JavaScript

// 创建 app install element
const appInstall = stripeConnect.create('app-install');

// 设置要安装的 app
appInstall.setApp('com.tajo.brevo-integration');

// 挂载到 DOM element
const container = document.getElementById('app-install-container');
appInstall.mount(container);

// 监听安装事件
appInstall.on('app_installed', (event) => {
  console.log('App installed:', event.app_id);
  // 安装后显示 app viewport
  showAppViewport();
});

appInstall.on('app_uninstalled', (event) => {
  console.log('App uninstalled:', event.app_id);
});

React

import {
  ConnectAppInstall,
  ConnectComponentsProvider,
} from '@stripe/react-connect-js';

const AppInstallButton = () => {
  return (
    <ConnectComponentsProvider connectInstance={stripeConnect}>
      <ConnectAppInstall
        app="com.tajo.brevo-integration"
        onAppInstalled={(event) => {
          console.log('App installed:', event.app_id);
        }}
        onAppUninstalled={(event) => {
          console.log('App uninstalled:', event.app_id);
        }}
      />
    </ConnectComponentsProvider>
  );
};

App Viewport Component

app-viewport component 在您的平台中渲染特定的 app viewport：

JavaScript

// 创建 app viewport element
const appViewport = stripeConnect.create('app-viewport');

// 配置 viewport
appViewport.setApp('com.tajo.brevo-integration');
appViewport.setViewport('stripe.dashboard.customer.detail');

// 传递 object context（例如 customer ID）
appViewport.setObjectContext({
  id: 'cus_xxxxx',
  object: 'customer',
});

// 挂载到 DOM element
const container = document.getElementById('app-viewport-container');
appViewport.mount(container);

React

import {
  ConnectAppViewport,
  ConnectComponentsProvider,
} from '@stripe/react-connect-js';

const BrevoCusomerView = ({ customerId }: { customerId: string }) => {
  return (
    <ConnectComponentsProvider connectInstance={stripeConnect}>
      <ConnectAppViewport
        app="com.tajo.brevo-integration"
        viewport="stripe.dashboard.customer.detail"
        objectContext={{
          id: customerId,
          object: 'customer',
        }}
      />
    </ConnectComponentsProvider>
  );
};

Destination Charge Metadata Schema

在 Connect 平台中使用 embedded apps 配合 destination charges 时，charge metadata 携带结构化数据，会计和营销集成可以使用这些数据。

会计集成

对于 QuickBooks 和 Xero 等应用，destination charge metadata 遵循以下 schema：

{
  "metadata": {
    "customer_id": "cus_platform_customer_id",
    "customer_email": "[email protected]",
    "product_name": "Premium Subscription",
    "product_id": "prod_xxxxx",
    "quantity": "1",
    "unit_amount": "4999",
    "currency": "usd",
    "platform_fee": "500",
    "platform_fee_currency": "usd",
    "tax_amount": "450",
    "tax_rate_id": "txr_xxxxx",
    "invoice_id": "inv_xxxxx",
    "order_id": "order_12345"
  }
}

字段	类型	描述
`customer_id`	string	平台的客户标识符
`customer_email`	string	用于发票/收据匹配的客户电子邮件
`product_name`	string	行项目的产品显示名称
`product_id`	string	Stripe 产品 ID
`quantity`	string	商品数量
`unit_amount`	string	最小货币单位（分）的单价
`currency`	string	三字母 ISO 货币代码
`platform_fee`	string	最小货币单位的应用费金额
`platform_fee_currency`	string	平台费的货币
`tax_amount`	string	最小货币单位的税额
`tax_rate_id`	string	应用的 Stripe 税率 ID
`invoice_id`	string	关联的发票 ID
`order_id`	string	平台内部订单标识符

营销集成

对于 Mailchimp 和 Tajo Brevo 集成等应用，metadata 支持客户细分和营销活动定向：

{
  "metadata": {
    "customer_id": "cus_xxxxx",
    "customer_email": "[email protected]",
    "customer_name": "Jane Smith",
    "product_category": "subscription",
    "product_name": "Pro Plan",
    "purchase_value": "4999",
    "currency": "usd",
    "is_first_purchase": "true",
    "referral_source": "partner_campaign",
    "subscription_interval": "monthly",
    "lifetime_value": "29994"
  }
}

此 metadata 支持以下 Brevo 自动化：

针对首次购买者的 Welcome series（is_first_purchase: "true"）
基于 product_category 和 purchase_value 的 Upsell campaigns
基于 subscription_interval 针对订阅客户的 Retention flows
针对流失的高 lifetime_value 客户的 Win-back campaigns

平台集成示例

嵌入 Tajo Brevo app 的完整平台集成：

import { useState, useEffect } from 'react';
import {
  ConnectAppInstall,
  ConnectAppViewport,
  ConnectComponentsProvider,
} from '@stripe/react-connect-js';
import { loadConnectAndInitialize } from '@stripe/connect-js';

const TajoBrevoPlatformIntegration = ({ connectedAccountId, customerId }) => {
  const [stripeConnect, setStripeConnect] = useState(null);
  const [isInstalled, setIsInstalled] = useState(false);

  useEffect(() => {
    const instance = loadConnectAndInitialize({
      publishableKey: 'pk_live_...',
      fetchClientSecret: async () => {
        const res = await fetch('/api/account-session', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ accountId: connectedAccountId }),
        });
        const { clientSecret } = await res.json();
        return clientSecret;
      },
    });
    setStripeConnect(instance);
  }, [connectedAccountId]);

  if (!stripeConnect) return <div>Loading...</div>;

  return (
    <ConnectComponentsProvider connectInstance={stripeConnect}>
      {!isInstalled ? (
        <div>
          <h3>Connect Brevo via Tajo</h3>
          <p>Install the Tajo integration to sync customer data with Brevo.</p>
          <ConnectAppInstall
            app="com.tajo.brevo-integration"
            onAppInstalled={() => setIsInstalled(true)}
          />
        </div>
      ) : (
        <div>
          <h3>Brevo Customer Profile</h3>
          <ConnectAppViewport
            app="com.tajo.brevo-integration"
            viewport="stripe.dashboard.customer.detail"
            objectContext={{
              id: customerId,
              object: 'customer',
            }}
          />
        </div>
      )}
    </ConnectComponentsProvider>
  );
};

安全注意事项

在平台中嵌入 apps 时：

Account Sessions 会过期：根据需要创建新 sessions；不要缓存 client secrets
范围控制：使用 allowed_apps 限制可以安装哪些 apps
数据隔离：每个 connected account 的数据是隔离的；平台无法访问 app 数据
CSP headers：确保您平台的 Content Security Policy 允许连接到 https://connect-js.stripe.com

Caution

Embedded app components 需要具有 Account Sessions API 访问权限的 Connect 集成。标准 Stripe 账户不能使用 embedded components。

Embedded Stripe Apps

概述

支持的 Apps

使用 Account Sessions API 进行设置

服务器端：创建 Account Session

客户端：初始化 Connect.js

App Install Component

JavaScript

React

App Viewport Component

JavaScript

React

Destination Charge Metadata Schema

会计集成

营销集成

平台集成示例

安全注意事项

Subscribe to updates

Thanks — you're subscribed.