مرجع 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"
}
}

مرجع المخطط

الحقول على المستوى الأعلى

الحقلالنوعمطلوبالوصف
idstringنعممعرف التطبيق الفريد بتنسيق النطاق العكسي (صيغة slug)
versionstringنعمسلسلة الإصدار الدلالي (مثل "1.2.0")
namestringنعمالاسم المعروض في المتجر (حد أقصى 35 حرفًا)
iconstringنعمالمسار النسبي لملف أيقونة التطبيق (PNG أو SVG بحجم 300x300)
distribution_typestringنعم"public" للمتجر أو "private" للاستخدام الداخلي
sandbox_install_compatiblebooleanلاهل يمكن تثبيت التطبيق في وضع sandbox/الاختبار
stripe_api_access_typestringلاطريقة الوصول لـ API: "oauth" أو "api_key"
allowed_redirect_urisstring[]لاعناوين URI المسموح بها لإعادة التوجيه في OAuth
permissionsPermissionRequest[]نعممصفوفة طلبات الأذونات
ui_extensionUIExtensionManifestلاتكوين امتداد واجهة المستخدم
post_install_actionPostInstallActionلاالإجراء المتخذ بعد تثبيت التطبيق
constantsobjectلاأزواج مفتاح-قيمة يمكن الوصول إليها في التطبيق وقت التشغيل

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"
}
الحقلالنوعمطلوبالوصف
permissionstringنعممعرف الإذن (راجع مرجع الأذونات)
purposestringنعمشرح مقروء لسبب الحاجة لهذا الإذن

إرشادات الغرض:

  • اكتب تفسيرات واضحة ومحددة يمكن للتجار فهمها
  • اشرح لماذا يُستخدم الإذن، وليس فقط ما يمنحه
  • حافظ على الأوصاف موجزة (جملة واحدة)
  • تجنب المصطلحات التقنية

UIExtensionManifest

يكوّن مكونات واجهة المستخدم لتطبيقك:

{
"ui_extension": {
"views": [...],
"content_security_policy": {...}
}
}
الحقلالنوعمطلوبالوصف
viewsViewManifest[]نعممصفوفة إعلانات العروض
content_security_policyCSPRequestلاسياسة أمان المحتوى للموارد الخارجية

ViewManifest

يربط كل عرض مكون React بـ viewport في لوحة تحكم Stripe:

{
"viewport": "stripe.dashboard.customer.detail",
"component": "CustomerDetailView"
}
الحقلالنوعمطلوبالوصف
viewportstringنعمموقع لوحة التحكم حيث يُعرض هذا العرض (راجع مرجع Viewports)
componentstringنعماسم مكون 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-srcstring[]لاالنطاقات التي يمكن للتطبيق إرسال طلبات شبكة إليها
image-srcstring[]لاالنطاقات التي يمكن للتطبيق تحميل الصور منها
purposestringنعمشرح سبب الحاجة لهذه الاتصالات الخارجية

Caution

أضف فقط النطاقات التي يحتاجها تطبيقك فعلاً للاتصال. قد تؤدي إدخالات CSP المفرطة إلى تدقيق إضافي أثناء المراجعة.

PostInstallAction

يكوّن ما يحدث مباشرة بعد أن يثبت المستخدم تطبيقك:

{
"post_install_action": {
"type": "onboarding"
}
}
الحقلالنوعمطلوبالوصف
typestringنعمنوع الإجراء (انظر أدناه)
urlstringمشروطعنوان 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 قبل التحميل:

Terminal window
# Validate manifest syntax and schema
stripe apps validate
# Check for common issues
stripe apps check

أخطاء التحقق الشائعة:

الخطأالسببالحل
Invalid permissionمعرف إذن غير معروفتحقق من مرجع الأذونات
Invalid viewportمعرف viewport غير معروفتحقق من مرجع Viewports
Missing purposeإذن بدون حقل الغرضأضف سلسلة غرض لكل إذن
Invalid versionسلسلة إصدار غير دلاليةاستخدم التنسيق MAJOR.MINOR.PATCH
Icon not foundمسار الأيقونة لا يشير لملفتحقق من وجود ملف الأيقونة في المسار المحدد

Subscribe to updates

developer-docs

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

مساعد AI

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

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