แอป Stripe แบบฝัง
แอป Stripe แบบฝังช่วยให้แพลตฟอร์มที่สร้างบน Stripe Connect นำความสามารถของแอปจากผู้ให้บริการภายนอกมาแสดงในแดชบอร์ดของตนเองได้โดยตรง เมื่อใช้ Connect embedded components คุณสามารถให้บัญชีที่เชื่อมต่ออยู่เข้าถึงแอปอย่าง QuickBooks, Xero และ Mailchimp ได้โดยไม่ต้องเข้าไปที่ Stripe Dashboard
ภาพรวม
แอปแบบฝังใช้ Connect embedded components หลักสองตัว
app-install: แสดงปุ่มติดตั้งสำหรับ Stripe App ภายในหน้าจอของแพลตฟอร์มคุณapp-viewport: แสดง viewport ของแอปที่ระบุไว้ภายในหน้าจอของแพลตฟอร์มคุณ
สิ่งนี้ทำให้ผู้ให้บริการแพลตฟอร์มฝังเครื่องมือด้านบัญชี การตลาด และการปฏิบัติงานไว้ในผลิตภัณฑ์ของตนได้โดยตรง
แอปที่รองรับ
แอปต่อไปนี้รองรับการฝังผ่าน Connect components
| แอป | หมวดหมู่ | กรณีใช้งาน |
|---|---|---|
| QuickBooks | บัญชี | ซิงค์การชำระเงินและใบแจ้งหนี้ไปยัง QuickBooks |
| Xero | บัญชี | ทำบัญชีและกระทบยอดแบบอัตโนมัติ |
| Mailchimp | การตลาด | ซิงค์ข้อมูลลูกค้าสำหรับแคมเปญอีเมล |
| แอปที่กำหนดเอง | ทุกหมวดหมู่ | Stripe Apps ของคุณเองที่สร้างขึ้นสำหรับแพลตฟอร์มของคุณ |
Tip
การเชื่อมต่อ Tajo Brevo สามารถฝังไว้ในแพลตฟอร์ม Connect ได้ ทำให้บัญชีที่เชื่อมต่ออยู่ซิงค์ข้อมูล Stripe ของตนไปยัง Brevo ผ่านหน้าจอของแพลตฟอร์มเองได้
การตั้งค่าด้วย Account Sessions API
หากต้องการฝังแอป คุณต้องสร้าง Account Session โดยเปิดใช้งาน component ที่เกี่ยวข้อง
ฝั่งเซิร์ฟเวอร์: สร้าง Account Session
const stripe = require('stripe')('sk_live_...');
// Create an Account Session for the connected accountconst accountSession = await stripe.accountSessions.create({ account: 'acct_connected_account_id', components: { // Enable app install component app_install: { enabled: true, features: { allowed_apps: [ 'com.tajo.brevo-integration', 'com.quickbooks.stripe-app' ], }, }, // Enable app viewport component app_viewport: { enabled: true, features: { allowed_apps: [ 'com.tajo.brevo-integration' ], }, }, },});
// Return the client secret to your frontendres.json({ clientSecret: accountSession.client_secret });ฝั่งไคลเอนต์: เริ่มต้นใช้งาน Connect.js
import { loadConnectAndInitialize } from '@stripe/connect-js';
// Initialize Connect.js with the account sessionconst 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 จะแสดงปุ่มติดตั้งที่บัญชีซึ่งเชื่อมต่ออยู่ใช้ติดตั้ง Stripe App ได้
JavaScript
// Create the app install elementconst appInstall = stripeConnect.create('app-install');
// Set the app to installappInstall.setApp('com.tajo.brevo-integration');
// Mount to a DOM elementconst container = document.getElementById('app-install-container');appInstall.mount(container);
// Listen for install eventsappInstall.on('app_installed', (event) => { console.log('App installed:', event.app_id); // Show the app viewport after installation 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 จะแสดง viewport ของแอปที่ระบุไว้ภายในแพลตฟอร์มของคุณ
JavaScript
// Create the app viewport elementconst appViewport = stripeConnect.create('app-viewport');
// Configure the viewportappViewport.setApp('com.tajo.brevo-integration');appViewport.setViewport('stripe.dashboard.customer.detail');
// Pass object context (e.g., customer ID)appViewport.setObjectContext({ id: 'cus_xxxxx', object: 'customer',});
// Mount to a DOM elementconst container = document.getElementById('app-viewport-container');appViewport.mount(container);React
import { ConnectAppViewport, ConnectComponentsProvider,} from '@stripe/react-connect-js';
const BrevoCustomerView = ({ customerId }: { customerId: string }) => { return ( <ConnectComponentsProvider connectInstance={stripeConnect}> <ConnectAppViewport app="com.tajo.brevo-integration" viewport="stripe.dashboard.customer.detail" objectContext={{ id: customerId, object: 'customer', }} /> </ConnectComponentsProvider> );};สคีมา metadata ของ destination charge
เมื่อใช้แอปแบบฝังร่วมกับ destination charge (ซึ่งพบได้ทั่วไปในแพลตฟอร์ม Connect) metadata ของรายการเรียกเก็บเงินจะพาข้อมูลแบบมีโครงสร้างที่การเชื่อมต่อด้านบัญชีและการตลาดนำไปใช้ต่อได้
การเชื่อมต่อด้านบัญชี
สำหรับแอปอย่าง QuickBooks และ Xero metadata ของ destination charge จะเป็นไปตามสคีมานี้
{ "metadata": { "customer_id": "cus_platform_customer_id", "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 |
quantity | string | จำนวนสินค้า |
unit_amount | string | ราคาต่อหน่วยในหน่วยย่อยที่สุดของสกุลเงิน (เซนต์) |
currency | string | รหัสสกุลเงิน ISO สามตัวอักษร |
platform_fee | string | จำนวนค่าธรรมเนียมแอปพลิเคชันในหน่วยย่อยที่สุดของสกุลเงิน |
platform_fee_currency | string | สกุลเงินของค่าธรรมเนียมแพลตฟอร์ม |
tax_amount | string | จำนวนภาษีในหน่วยย่อยที่สุดของสกุลเงิน |
tax_rate_id | string | รหัสอัตราภาษีของ Stripe ที่ใช้ |
invoice_id | string | รหัสใบแจ้งหนี้ที่เกี่ยวข้อง |
order_id | string | ตัวระบุออเดอร์ภายในของแพลตฟอร์ม |
การเชื่อมต่อด้านการตลาด
สำหรับแอปอย่าง Mailchimp และการเชื่อมต่อ Tajo Brevo metadata ชุดนี้ช่วยให้แบ่งเซกเมนต์ลูกค้าและกำหนดเป้าหมายแคมเปญได้
{ "metadata": { "customer_id": "cus_xxxxx", "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 เช่น
- ชุดอีเมลต้อนรับ สำหรับผู้ที่ซื้อครั้งแรก (
is_first_purchase: "true") - แคมเปญขายเพิ่ม โดยอิงจาก
product_categoryและpurchase_value - โฟลว์รักษาฐานลูกค้า สำหรับลูกค้าแบบสมัครสมาชิก โดยอิงจาก
subscription_interval - แคมเปญดึงลูกค้ากลับ ที่เจาะกลุ่มลูกค้าซึ่งมี
lifetime_valueสูงและเลิกใช้บริการไปแล้ว
ตัวอย่างการเชื่อมต่อกับแพลตฟอร์ม
ตัวอย่างการเชื่อมต่อแพลตฟอร์มแบบสมบูรณ์ที่ฝังแอป 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> );};ข้อควรพิจารณาด้านความปลอดภัย
เมื่อฝังแอปไว้ในแพลตฟอร์มของคุณ
- Account Session มีวันหมดอายุ: สร้างเซสชันใหม่เมื่อจำเป็น และอย่าแคช client secret ไว้
- ควบคุมขอบเขต: ใช้
allowed_appsเพื่อจำกัดว่าแอปใดติดตั้งได้บ้าง - แยกข้อมูลออกจากกัน: ข้อมูลของแต่ละบัญชีที่เชื่อมต่ออยู่จะถูกแยกออกจากกัน แพลตฟอร์มเข้าถึงข้อมูลของแอปไม่ได้
- เฮดเดอร์ CSP: ตรวจสอบว่า Content Security Policy ของแพลตฟอร์มคุณอนุญาตการเชื่อมต่อไปยัง
https://connect-js.stripe.com
Caution
component ของแอปแบบฝังต้องใช้การเชื่อมต่อแบบ Connect ที่เข้าถึง Account Sessions API ได้ บัญชี Stripe แบบมาตรฐานไม่สามารถใช้ embedded components ได้