On this page

Embedded Stripe Apps

Embedded Stripe Apps cho phép các nền tảng xây dựng trên Stripe Connect hiển thị chức năng app của bên thứ ba trực tiếp trong dashboard của họ. Sử dụng Connect embedded components, bạn có thể cấp cho connected accounts quyền truy cập vào các app như QuickBooks, Xero và Mailchimp mà không cần họ truy cập Stripe Dashboard.

Tổng Quan

Embedded apps sử dụng hai Connect embedded components chính:

app-install: Render nút cài đặt cho Stripe App trong platform UI của bạn
app-viewport: Render một app viewport cụ thể trong platform UI của bạn

Điều này cho phép các nhà điều hành nền tảng nhúng các công cụ kế toán, marketing và vận hành trực tiếp vào sản phẩm của họ.

Các App Được Hỗ Trợ

Các app sau đây hỗ trợ nhúng qua Connect components:

App	Danh Mục	Trường Hợp Sử Dụng
QuickBooks	Kế Toán	Đồng bộ thanh toán và hóa đơn với QuickBooks
Xero	Kế Toán	Kế toán và đối soát tự động
Mailchimp	Marketing	Đồng bộ dữ liệu khách hàng cho email campaigns
Custom Apps	Bất kỳ	Stripe Apps tùy chỉnh của bạn cho nền tảng

Tip

Tích hợp Tajo Brevo có thể được nhúng trong Connect platforms, cho phép connected accounts đồng bộ dữ liệu Stripe của họ với Brevo thông qua giao diện riêng của nền tảng.

Thiết Lập Với Account Sessions API

Để nhúng apps, bạn cần tạo Account Sessions với các components được bật phù hợp:

Server-Side: Tạo Account Session

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

// Tạo Account Session cho tài khoản connected
const accountSession = await stripe.accountSessions.create({
  account: 'acct_connected_account_id',
  components: {
    // Bật app install component
    app_install: {
      enabled: true,
      features: {
        allowed_apps: [
          'com.tajo.brevo-integration',
          'com.quickbooks.stripe-app'
        ],
      },
    },
    // Bật app viewport component
    app_viewport: {
      enabled: true,
      features: {
        allowed_apps: [
          'com.tajo.brevo-integration'
        ],
      },
    },
  },
});

// Trả về client secret cho frontend
res.json({ clientSecret: accountSession.client_secret });

Client-Side: Khởi Tạo Connect.js

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

// Khởi tạo Connect.js với account session
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

Component app-install render nút cài đặt mà connected accounts có thể dùng để cài đặt Stripe App:

JavaScript

// Tạo app install element
const appInstall = stripeConnect.create('app-install');

// Đặt app để cài đặt
appInstall.setApp('com.tajo.brevo-integration');

// Mount vào DOM element
const container = document.getElementById('app-install-container');
appInstall.mount(container);

// Lắng nghe sự kiện cài đặt
appInstall.on('app_installed', (event) => {
  console.log('App installed:', event.app_id);
  // Hiển thị app viewport sau khi cài đặt
  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

Component app-viewport render một app viewport cụ thể trong nền tảng của bạn:

JavaScript

// Tạo app viewport element
const appViewport = stripeConnect.create('app-viewport');

// Cấu hình viewport
appViewport.setApp('com.tajo.brevo-integration');
appViewport.setViewport('stripe.dashboard.customer.detail');

// Truyền object context (ví dụ: customer ID)
appViewport.setObjectContext({
  id: 'cus_xxxxx',
  object: 'customer',
});

// Mount vào 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>
  );
};

Schema Metadata Destination Charge

Khi sử dụng embedded apps với destination charges (phổ biến trong Connect platforms), charge metadata mang dữ liệu có cấu trúc mà các tích hợp kế toán và marketing có thể sử dụng.

Tích Hợp Kế Toán

Đối với các app như QuickBooks và Xero, metadata destination charge theo schema này:

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

Trường	Kiểu	Mô Tả
`customer_id`	string	Định danh khách hàng của nền tảng
`customer_email`	string	Email khách hàng để khớp hóa đơn/biên lai
`product_name`	string	Tên hiển thị sản phẩm cho các mục hàng
`product_id`	string	Stripe product ID
`quantity`	string	Số lượng mặt hàng
`unit_amount`	string	Đơn giá theo đơn vị tiền tệ nhỏ nhất (cent)
`currency`	string	Mã tiền tệ ISO ba chữ cái
`platform_fee`	string	Số tiền phí ứng dụng theo đơn vị tiền tệ nhỏ nhất
`platform_fee_currency`	string	Đơn vị tiền tệ cho phí nền tảng
`tax_amount`	string	Số tiền thuế theo đơn vị tiền tệ nhỏ nhất
`tax_rate_id`	string	Stripe tax rate ID được áp dụng
`invoice_id`	string	Invoice ID liên quan
`order_id`	string	Định danh đơn hàng nội bộ của nền tảng

Tích Hợp Marketing

Đối với các app như Mailchimp và tích hợp Tajo Brevo, metadata cho phép phân khúc khách hàng và nhắm mục tiêu chiến dịch:

{
  "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 này cho phép các automation Brevo như:

Welcome series cho người mua lần đầu (is_first_purchase: "true")
Upsell campaigns dựa trên product_category và purchase_value
Retention flows cho khách hàng subscription dựa trên subscription_interval
Win-back campaigns nhắm mục tiêu khách hàng có lifetime_value cao đã rời đi

Ví Dụ Tích Hợp Nền Tảng

Tích hợp nền tảng hoàn chỉnh nhúng app Tajo Brevo:

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>
  );
};

Lưu Ý Bảo Mật

Khi nhúng apps trong nền tảng của bạn:

Account Sessions hết hạn: Tạo sessions mới khi cần; không cache client secrets
Kiểm soát phạm vi: Sử dụng allowed_apps để hạn chế apps nào có thể được cài đặt
Cô lập dữ liệu: Dữ liệu của mỗi connected account được cô lập; nền tảng không thể truy cập dữ liệu app
CSP headers: Đảm bảo Content Security Policy của nền tảng cho phép kết nối đến https://connect-js.stripe.com

Caution

Các embedded app components yêu cầu tích hợp Connect với Account Sessions API access. Các tài khoản Stripe tiêu chuẩn không thể sử dụng embedded components.

Embedded Stripe Apps

Tổng Quan

Các App Được Hỗ Trợ

Thiết Lập Với Account Sessions API

Server-Side: Tạo Account Session

Client-Side: Khởi Tạo Connect.js

App Install Component

JavaScript

React

App Viewport Component

JavaScript

React

Schema Metadata Destination Charge

Tích Hợp Kế Toán

Tích Hợp Marketing

Ví Dụ Tích Hợp Nền Tảng

Lưu Ý Bảo Mật

Subscribe to updates

Thanks — you're subscribed.