تطبيقات 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 account
const 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 frontend
res.json({ clientSecret: accountSession.client_secret });

جانب العميل: تهيئة Connect.js

import { loadConnectAndInitialize } from '@stripe/connect-js';
// Initialize Connect.js with the 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 زر تثبيت يمكن للحسابات المتصلة استخدامه لتثبيت تطبيق Stripe:

JavaScript

// Create the app install element
const appInstall = stripeConnect.create('app-install');
// Set the app to install
appInstall.setApp('com.tajo.brevo-integration');
// Mount to a DOM element
const container = document.getElementById('app-install-container');
appInstall.mount(container);
// Listen for install events
appInstall.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 element
const appViewport = stripeConnect.create('app-viewport');
// Configure the viewport
appViewport.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 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>
);
};

مخطط بيانات Metadata لرسوم الوجهة

عند استخدام التطبيقات المضمنة مع رسوم الوجهة (شائعة في منصات Connect)، تحمل بيانات metadata المرفقة بالرسوم بيانات منظمة يمكن لتكاملات المحاسبة والتسويق استهلاكها.

تكاملات المحاسبة

لتطبيقات مثل QuickBooks و Xero، تتبع بيانات metadata لرسوم الوجهة هذا المخطط:

{
"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_idstringمعرف العميل في المنصة
customer_emailstringبريد العميل الإلكتروني لمطابقة الفواتير/الإيصالات
product_namestringاسم المنتج المعروض لبنود السطر
product_idstringمعرف منتج Stripe
quantitystringكمية العنصر
unit_amountstringسعر الوحدة بأصغر وحدة عملة (سنتات)
currencystringرمز العملة ISO المكون من ثلاثة أحرف
platform_feestringمبلغ رسوم التطبيق بأصغر وحدة عملة
platform_fee_currencystringعملة رسوم المنصة
tax_amountstringمبلغ الضريبة بأصغر وحدة عملة
tax_rate_idstringمعرف معدل ضريبة Stripe المطبق
invoice_idstringمعرف الفاتورة المرتبطة
order_idstringمعرف الطلب الداخلي للمنصة

تكاملات التسويق

لتطبيقات مثل Mailchimp وتكامل Tajo مع Brevo، تمكّن البيانات الوصفية من تقسيم العملاء واستهداف الحملات:

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

تمكّن هذه البيانات الوصفية أتمتة 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 استخدام المكونات المضمنة.

Subscribe to updates

developer-docs

Drop your email or phone number — we'll send you what matters next.

مساعد AI

مرحباً! اسألني أي شيء عن الوثائق.

ابدأ مجانًا مع Brevo