مرجع App Manifest
ملف stripe-app.json هو التكوين المركزي لتطبيق Stripe الخاص بك. يحدد هوية تطبيقك وأذوناته وعروض واجهة المستخدم وسياسات الأمان وسلوك ما بعد التثبيت.
Caution
الحالة: مخطط له. لا يوجد حتى الآن تطبيق Tajo في متجر تطبيقات Stripe. ومعرّفات التطبيق وعناوين URL وبيانات الاعتماد الواردة في هذه الصفحة أمثلة توضيحية لا نقاط نهاية فعلية.
مثال Manifest كامل
{ "id": "com.tajo.brevo-integration", "version": "1.2.0", "name": "Tajo for Brevo", "icon": "./assets/icon.png", "distribution_type": "public", "sandbox_install_compatible": true, "stripe_api_access_type": "oauth", "allowed_redirect_uris": [ "https://tajo.io/stripe/callback", "https://tajo.io/stripe/oauth/complete" ], "permissions": [ { "permission": "customer_read", "purpose": "Read customer profiles to sync with Brevo contacts" }, { "permission": "customer_write", "purpose": "Update customer metadata with Brevo sync status" }, { "permission": "charge_read", "purpose": "Access payment history for Brevo event tracking" }, { "permission": "product_read", "purpose": "Sync product catalog to Brevo for personalized campaigns" }, { "permission": "event_read", "purpose": "Subscribe to real-time events for Brevo automation triggers" }, { "permission": "invoice_read", "purpose": "Track invoice lifecycle events in Brevo" } ], "ui_extension": { "views": [ { "viewport": "stripe.dashboard.customer.detail", "component": "CustomerDetailView" }, { "viewport": "stripe.dashboard.customer.list", "component": "CustomerListView" }, { "viewport": "stripe.dashboard.home.overview", "component": "OverviewView" }, { "viewport": "stripe.dashboard.drawer.default", "component": "DrawerView" }, { "viewport": "stripe.dashboard.settings", "component": "SettingsView" }, { "viewport": "stripe.dashboard.onboarding", "component": "OnboardingView" } ], "content_security_policy": { "connect-src": [ "https://api.example.com", "https://api.brevo.com" ], "image-src": [ "https://cdn.example.com", "https://assets.brevo.com" ], "purpose": "Connect to Tajo API for data sync and Brevo API for contact management" } }, "post_install_action": { "type": "onboarding" }, "constants": { "API_BASE_URL": "https://api.example.com/v1", "SYNC_INTERVAL_SECONDS": "300" }}مرجع المخطط
الحقول على المستوى الأعلى
| الحقل | النوع | مطلوب | الوصف |
|---|---|---|---|
id | string | نعم | معرف التطبيق الفريد بتنسيق النطاق العكسي (صيغة slug) |
version | string | نعم | سلسلة الإصدار الدلالي (مثل "1.2.0") |
name | string | نعم | الاسم المعروض في المتجر (حد أقصى 35 حرفًا) |
icon | string | نعم | المسار النسبي لملف أيقونة التطبيق (PNG أو SVG بحجم 300x300) |
distribution_type | string | نعم | "public" للمتجر أو "private" للاستخدام الداخلي |
sandbox_install_compatible | boolean | لا | هل يمكن تثبيت التطبيق في وضع sandbox/الاختبار |
stripe_api_access_type | string | لا | طريقة الوصول لـ API: "oauth" أو "api_key" |
allowed_redirect_uris | string[] | لا | عناوين URI المسموح بها لإعادة التوجيه في OAuth |
permissions | PermissionRequest[] | نعم | مصفوفة طلبات الأذونات |
ui_extension | UIExtensionManifest | لا | تكوين امتداد واجهة المستخدم |
post_install_action | PostInstallAction | لا | الإجراء المتخذ بعد تثبيت التطبيق |
constants | object | لا | أزواج مفتاح-قيمة يمكن الوصول إليها في التطبيق وقت التشغيل |
id
معرف التطبيق هو سلسلة بتنسيق slug، عادةً بتنسيق النطاق العكسي:
"id": "com.tajo.brevo-integration"- يجب أن يكون فريدًا عالميًا عبر جميع تطبيقات Stripe
- استخدم الأحرف الصغيرة والأرقام والشرطات والنقاط فقط
- لا يمكن تغييره بعد إنشاء التطبيق
- يحدد عنوان URL للتطبيق في المتجر
version
يتبع الإصدار الدلالي:
"version": "1.2.0"- MAJOR: تغييرات جذرية أو إضافات ميزات كبيرة
- MINOR: ميزات جديدة متوافقة مع الإصدارات السابقة
- PATCH: إصلاحات أخطاء وتحسينات طفيفة
- يجب زيادته مع كل تحميل
distribution_type
يتحكم في من يمكنه تثبيت تطبيقك:
| القيمة | الوصف |
|---|---|
"public" | متاح على متجر تطبيقات Stripe لجميع المستخدمين |
"private" | قابل للتثبيت فقط بواسطة حساب Stripe الخاص بك |
stripe_api_access_type
يحدد كيفية مصادقة تطبيقك مع Stripe API:
| القيمة | الوصف |
|---|---|
"oauth" | يستخدم تدفق OAuth 2.0 للمصادقة (موصى به للتطبيقات العامة) |
"api_key" | يستخدم مفاتيح API مقيدة (مناسب للتطبيقات الخاصة) |
PermissionRequest
يحدد كل طلب إذن صلاحية Stripe API محددة يحتاجها تطبيقك:
{ "permission": "customer_read", "purpose": "Read customer profiles to sync with Brevo contacts"}| الحقل | النوع | مطلوب | الوصف |
|---|---|---|---|
permission | string | نعم | معرف الإذن (راجع مرجع الأذونات) |
purpose | string | نعم | شرح مقروء لسبب الحاجة لهذا الإذن |
إرشادات الغرض:
- اكتب تفسيرات واضحة ومحددة يمكن للتجار فهمها
- اشرح لماذا يُستخدم الإذن، وليس فقط ما يمنحه
- حافظ على الأوصاف موجزة (جملة واحدة)
- تجنب المصطلحات التقنية
UIExtensionManifest
يكوّن مكونات واجهة المستخدم لتطبيقك:
{ "ui_extension": { "views": [...], "content_security_policy": {...} }}| الحقل | النوع | مطلوب | الوصف |
|---|---|---|---|
views | ViewManifest[] | نعم | مصفوفة إعلانات العروض |
content_security_policy | CSPRequest | لا | سياسة أمان المحتوى للموارد الخارجية |
ViewManifest
يربط كل عرض مكون React بـ viewport في لوحة تحكم Stripe:
{ "viewport": "stripe.dashboard.customer.detail", "component": "CustomerDetailView"}| الحقل | النوع | مطلوب | الوصف |
|---|---|---|---|
viewport | string | نعم | موقع لوحة التحكم حيث يُعرض هذا العرض (راجع مرجع Viewports) |
component | string | نعم | اسم مكون React المراد عرضه (يجب أن يتطابق مع اسم المكون المصدّر) |
يمكن للتطبيق الواحد الإعلان عن عروض متعددة لـ viewports مختلفة:
"views": [ { "viewport": "stripe.dashboard.customer.detail", "component": "CustomerDetailView" }, { "viewport": "stripe.dashboard.payment.detail", "component": "PaymentDetailView" }, { "viewport": "stripe.dashboard.home.overview", "component": "OverviewView" }]CSPRequest
تتحكم سياسة أمان المحتوى في النطاقات الخارجية التي يمكن لتطبيقك الاتصال بها:
{ "content_security_policy": { "connect-src": [ "https://api.example.com", "https://api.brevo.com" ], "image-src": [ "https://cdn.example.com" ], "purpose": "Connect to Tajo API for data sync and load images from CDN" }}| الحقل | النوع | مطلوب | الوصف |
|---|---|---|---|
connect-src | string[] | لا | النطاقات التي يمكن للتطبيق إرسال طلبات شبكة إليها |
image-src | string[] | لا | النطاقات التي يمكن للتطبيق تحميل الصور منها |
purpose | string | نعم | شرح سبب الحاجة لهذه الاتصالات الخارجية |
Caution
أضف فقط النطاقات التي يحتاجها تطبيقك فعلاً للاتصال. قد تؤدي إدخالات CSP المفرطة إلى تدقيق إضافي أثناء المراجعة.
PostInstallAction
يكوّن ما يحدث مباشرة بعد أن يثبت المستخدم تطبيقك:
{ "post_install_action": { "type": "onboarding" }}| الحقل | النوع | مطلوب | الوصف |
|---|---|---|---|
type | string | نعم | نوع الإجراء (انظر أدناه) |
url | string | مشروط | عنوان URL لإجراءات من نوع external |
أنواع الإجراءات
| النوع | السلوك |
|---|---|
"onboarding" | يفتح عرض الإعداد الخاص بالتطبيق في لوحة التحكم |
"settings" | يفتح عرض الإعدادات الخاص بالتطبيق في لوحة التحكم |
"external" | يعيد توجيه المستخدم إلى عنوان URL خارجي (يتطلب حقل url) |
أمثلة:
// Open onboarding flow{ "post_install_action": { "type": "onboarding" }}
// Open settings page{ "post_install_action": { "type": "settings" }}
// Redirect to external setup{ "post_install_action": { "type": "external", "url": "https://app.tajo.io/stripe/setup" }}راجع دليل إجراءات ما بعد التثبيت لأنماط التنفيذ المفصلة.
الثوابت
حدد أزواج مفتاح-قيمة ثابتة يمكن الوصول إليها وقت التشغيل في تطبيقك:
{ "constants": { "API_BASE_URL": "https://api.example.com/v1", "SYNC_INTERVAL_SECONDS": "300", "MAX_BATCH_SIZE": "100" }}- جميع القيم يجب أن تكون سلاسل نصية
- يتم تضمين الثوابت في التطبيق وقت البناء
- استخدم الثوابت للتكوين الذي يختلف بين البيئات
- لا تخزن أبدًا الأسرار أو مفاتيح API كثوابت, استخدم Secret Store API بدلاً من ذلك
الوصول إلى الثوابت في كود تطبيقك:
import { constants } from '@stripe/ui-extension-sdk/constants';
const apiUrl = constants.API_BASE_URL;Manifest موسع للتطوير
أثناء التطوير المحلي، تتوفر حقول إضافية:
{ "id": "com.tajo.brevo-integration", "version": "0.1.0", "name": "Tajo for Brevo (Dev)", "icon": "./assets/icon-dev.png", "distribution_type": "private", "sandbox_install_compatible": true, "dev": { "hot_reload": true, "port": 4242 }}يتم حذف قسم dev أثناء عمليات البناء للإنتاج وتحميل التطبيقات. استخدمه فقط لإعدادات راحة التطوير المحلي.
التحقق
تحقق من صحة الـ manifest قبل التحميل:
# Validate manifest syntax and schemastripe apps validate
# Check for common issuesstripe apps checkأخطاء التحقق الشائعة:
| الخطأ | السبب | الحل |
|---|---|---|
Invalid permission | معرف إذن غير معروف | تحقق من مرجع الأذونات |
Invalid viewport | معرف viewport غير معروف | تحقق من مرجع Viewports |
Missing purpose | إذن بدون حقل الغرض | أضف سلسلة غرض لكل إذن |
Invalid version | سلسلة إصدار غير دلالية | استخدم التنسيق MAJOR.MINOR.PATCH |
Icon not found | مسار الأيقونة لا يشير لملف | تحقق من وجود ملف الأيقونة في المسار المحدد |