تطبيقات Stripe المضمنة
تتيح تطبيقات Stripe المضمنة للمنصات المبنية على Stripe Connect عرض وظائف تطبيقات الطرف الثالث مباشرة داخل لوحات التحكم الخاصة بها. باستخدام مكونات Connect المضمنة، يمكنك منح الحسابات المتصلة الوصول إلى تطبيقات مثل QuickBooks و Xero و Mailchimp دون الحاجة لزيارة لوحة تحكم Stripe.
نظرة عامة
تستخدم التطبيقات المضمنة مكونين رئيسيين من Connect:
app-install: يعرض زر تثبيت لتطبيق Stripe داخل واجهة منصتكapp-viewport: يعرض viewport محدد للتطبيق داخل واجهة منصتك
يمكّن هذا مشغلي المنصات من تضمين أدوات المحاسبة والتسويق والعمليات مباشرة في منتجهم.
التطبيقات المدعومة
التطبيقات التالية تدعم التضمين عبر مكونات Connect:
| التطبيق | الفئة | حالة الاستخدام |
|---|---|---|
| QuickBooks | محاسبة | مزامنة المدفوعات والفواتير مع QuickBooks |
| Xero | محاسبة | مسك الدفاتر والمطابقة الآلية |
| Mailchimp | تسويق | مزامنة بيانات العملاء لحملات البريد الإلكتروني |
| تطبيقات مخصصة | أي | تطبيقات Stripe الخاصة بك المبنية لمنصتك |
Tip
يمكن تضمين تكامل Tajo مع Brevo في منصات Connect، مما يتيح للحسابات المتصلة مزامنة بيانات Stripe الخاصة بها مع Brevo من خلال واجهة المنصة نفسها.
الإعداد باستخدام Account Sessions API
لتضمين التطبيقات، تحتاج إلى إنشاء Account Sessions مع تمكين المكونات المناسبة:
جانب الخادم: إنشاء 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 زر تثبيت يمكن للحسابات المتصلة استخدامه لتثبيت تطبيق Stripe:
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> );};مكون Viewport للتطبيق
يعرض مكون 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 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> );};مخطط بيانات Metadata لرسوم الوجهة
عند استخدام التطبيقات المضمنة مع رسوم الوجهة (شائعة في منصات Connect)، تحمل بيانات metadata المرفقة بالرسوم بيانات منظمة يمكن لتكاملات المحاسبة والتسويق استهلاكها.
تكاملات المحاسبة
لتطبيقات مثل QuickBooks و Xero، تتبع بيانات metadata لرسوم الوجهة هذا المخطط:
{ "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": { "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" }}تمكّن هذه البيانات الوصفية أتمتة 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 Sessions: أنشئ جلسات جديدة حسب الحاجة؛ لا تقم بتخزين أسرار العميل مؤقتًا
- التحكم في النطاق: استخدم
allowed_appsلتقييد التطبيقات التي يمكن تثبيتها - عزل البيانات: بيانات كل حساب متصل معزولة؛ لا يمكن للمنصة الوصول إلى بيانات التطبيق
- رؤوس CSP: تأكد من أن سياسة أمان المحتوى لمنصتك تسمح بالاتصالات إلى
https://connect-js.stripe.com
Caution
تتطلب مكونات التطبيقات المضمنة تكامل Connect مع وصول Account Sessions API. لا يمكن للحسابات القياسية في Stripe استخدام المكونات المضمنة.