مرجع App Manifest
ملف stripe-app.json هو التكوين المركزي لتطبيق Stripe الخاص بك. يحدد هوية تطبيقك وأذوناته وعروض واجهة المستخدم وسياسات الأمان وسلوك ما بعد التثبيت.
مثال 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.tajo.io", "https://api.brevo.com" ], "image-src": [ "https://cdn.tajo.io", "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.tajo.io/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.tajo.io", "https://api.brevo.com" ], "image-src": [ "https://cdn.tajo.io" ], "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.tajo.io/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 | مسار الأيقونة لا يشير لملف | تحقق من وجود ملف الأيقونة في المسار المحدد |