متطلبات جودة مراجعة التطبيق

يراجع Stripe كل تطبيق يُقدم للمتجر وفقًا لمجموعة شاملة من متطلبات الجودة. فهم هذه المعايير قبل التطوير يوفر الوقت ويقلل عدد مراحل المراجعة.

نظرة عامة

تقيّم مراجعة تطبيق Stripe تطبيقك عبر ستة مجالات رئيسية:

1. تسعير شفاف, التواصل الواضح حول التكاليف
2. وظائف التطبيق, الموثوقية والاكتمال
3. معايير المطورين, جودة الكود واستخدام API
4. جودة تجربة المستخدم, معايير واجهة وتجربة المستخدم
5. الأمان, حماية البيانات والممارسات الآمنة
6. الامتثال القانوني, متطلبات الخصوصية والتنظيم

التسعير الشفاف

يجب أن يتواصل تطبيقك بوضوح حول جميع التكاليف للمستخدمين:

• إفصاح التسعير: يجب ذكر جميع الأسعار مقدمًا في قائمة المتجر
• بدون رسوم مخفية: يجب ألا يواجه المستخدمون رسومًا غير متوقعة بعد التثبيت
• شروط التجربة: إذا قدمت تجربة، حدد بوضوح المدة وما يحدث بعد انتهائها
• تدفقات الترقية: أي مطالبات بالترقية أو البيع الإضافي يجب أن تكون غير مزعجة واختيارية بوضوح
• العملة: اعرض الأسعار بعملة المستخدم المحلية عند الإمكان

تنسيق التاريخ والوقت

يجب أن تتبع جميع التواريخ والأوقات المعروضة في تطبيقك اتفاقيات لوحة تحكم Stripe:

• استخدم لغة المستخدم لتنسيق التاريخ عند توفرها
• اعرض الأوقات بالمنطقة الزمنية المحلية للمستخدم
• استخدم الطوابع الزمنية النسبية للأحداث الحديثة (مثل “منذ ساعتين”)
• استخدم الطوابع الزمنية المطلقة للأحداث الأقدم مع التاريخ والوقت الكاملين
• اتبع ISO 8601 لأي حقول تاريخ في API

// Good: Use Stripe's date formatting utilities
import { formatDate, formatRelativeTime } from '@stripe/ui-extension-sdk/utils';

const formattedDate = formatDate(timestamp); // Locale-aware
const relativeTime = formatRelativeTime(timestamp); // "2 hours ago"

إعدادات التطبيق

إذا كان تطبيقك يتطلب تكوينًا:

• وفر عرض إعدادات مخصص يمكن الوصول إليه من viewport التطبيق
• املأ الإعدادات الافتراضية المعقولة مسبقًا حيثما أمكن
• تحقق من صحة جميع مدخلات المستخدم مع رسائل خطأ واضحة
• اسمح للمستخدمين بتحديث الإعدادات دون إعادة تثبيت التطبيق
• احفظ الإعدادات عبر الجلسات باستخدام Stripe Secret Store API

دعم Sandbox

يجب أن يعمل تطبيقك بشكل صحيح في وضع sandbox (الاختبار) في Stripe:

• توافق وضع الاختبار: يجب أن تعمل جميع الميزات في وضع الاختبار
• بيانات الاختبار: استخدم بيانات اختبار واقعية توضح وظائف التطبيق
• بدون بيانات حية في sandbox: لا تكشف أبدًا بيانات الإنتاج في وضع الاختبار
• معالجة أنيقة: إذا كانت ميزة غير متاحة في sandbox، اعرض رسالة واضحة تشرح السبب
• عيّن sandbox_install_compatible: true في الـ manifest

{
  "sandbox_install_compatible": true
}

وظائف التطبيق

الموثوقية

• يجب ألا يتعطل التطبيق أو يتجمد أثناء الاستخدام العادي
• يجب أن تعمل جميع الميزات المُعلن عنها كما هو موصوف
• يجب معالجة أخطاء الشبكة بأناقة مع خيارات إعادة المحاولة
• يجب أن يبقى التطبيق متجاوبًا أثناء العمليات الخلفية

الاكتمال

• بدون محتوى مؤقت أو ميزات “قريبًا” أو روابط معطلة
• يجب أن تكون جميع عناصر واجهة المستخدم وظيفية, بدون أزرار ميتة أو عناصر تحكم غير نشطة
• يجب أن تشير روابط النص المساعد والتوثيق إلى صفحات صالحة
• يجب أن يزيل إلغاء التثبيت جميع بيانات التطبيق وwebhooks بشكل نظيف

الأداء

• يجب أن تُعرض واجهة المستخدم خلال 3 ثوانٍ على اتصال قياسي
• يجب ألا تحجب عمليات المزامنة الخلفية واجهة المستخدم
• يجب استخدام التصفح بالصفحات أو التحميل الكسول لمجموعات البيانات الكبيرة
• قلل استدعاءات API لتجنب حدود المعدل

معايير المطورين

استخدام API

• استخدم أحدث إصدار مستقر من Stripe API
• اتبع أفضل ممارسات Stripe API للتصفح ومعالجة الأخطاء وعدم التكرار
• لا تتجاوز حدود المعدل, نفذ التراجع الأسي لإعادة المحاولة
• استخدم webhooks للتحديثات القائمة على الأحداث بدلاً من الاستقصاء

جودة الكود

• بدون أخطاء أو تحذيرات وحدة التحكم في بنايات الإنتاج
• احذف جميع سجلات التصحيح قبل التقديم
• عالج جميع الحالات الحدية (حالات فارغة، بيانات مفقودة، فشل الشبكة)
• اتبع أنماط مكتبة مكونات Stripe لواجهة مستخدم متسقة

إدارة الإصدارات

• استخدم الإصدار الدلالي (MAJOR.MINOR.PATCH)
• وثق التغييرات الجذرية في تحديثات الإصدار
• حافظ على التوافق مع الإصدارات السابقة حيثما أمكن

جودة تجربة المستخدم

الإعلانات

• بدون إعلانات: يجب ألا يعرض تطبيقك إعلانات من أي نوع
• بدون ترويج متبادل: لا تروج لمنتجات أو خدمات أخرى داخل واجهة التطبيق
• محتوى مُعلّم: اعرض فقط هوية علامتك التجارية، وليس علامات تجارية لأطراف ثالثة (باستثناء شركاء التكامل مثل Brevo)

اللغة والمحتوى

• لغة متسقة: استخدم مصطلحات متسقة في جميع أنحاء التطبيق
• نبرة مهنية: طابق أسلوب التواصل المهني والموجز للوحة تحكم Stripe
• بدون مصطلحات: تجنب المصطلحات التقنية التي قد لا يفهمها التجار
• تدقيق إملائي: تأكد من خلو جميع النصوص من الأخطاء الإملائية والنحوية
• باللغة الإنجليزية فقط: يجب أن يكون جميع النص المواجه للمستخدم باللغة الإنجليزية لتطبيقات المتجر

حوارات التأكيد

اطلب تأكيد المستخدم للإجراءات المدمرة أو المهمة:

// Good: Confirm before destructive actions
const handleDisconnect = async () => {
  const confirmed = await showConfirmation({
    title: 'Disconnect Brevo Integration',
    message: 'This will stop syncing customer data to Brevo. You can reconnect at any time.',
    confirmLabel: 'Disconnect',
    cancelLabel: 'Cancel',
    destructive: true,
  });

  if (confirmed) {
    await disconnectIntegration();
  }
};

الإجراءات التي تتطلب تأكيدًا:

• قطع التكاملات
• حذف البيانات المتزامنة
• تغيير الإعدادات التي تؤثر على تدفق البيانات
• إعادة تعيين التكوين للإعدادات الافتراضية

حالات التحميل

اعرض دائمًا مؤشرات تحميل للعمليات غير المتزامنة:

// Good: Show loading state during data fetch
const CustomerSyncStatus = () => {
  const { data, isLoading, error } = useSyncStatus();

  if (isLoading) {
    return <Spinner label="Loading sync status..." />;
  }

  if (error) {
    return <Banner type="critical" title="Failed to load sync status">
      {error.message}
    </Banner>;
  }

  return <SyncStatusDisplay data={data} />;
};

المتطلبات:

• اعرض مؤشرات دوران أو شاشات هيكلية أثناء تحميل البيانات
• عطّل الأزرار أثناء تقديم النماذج
• اعرض مؤشرات تقدم للعمليات طويلة المدة
• لا تعرض أبدًا شاشة فارغة أثناء التحميل

رسائل الخطأ

وفر رسائل خطأ واضحة وقابلة للتنفيذ:

// Bad: Generic error
"Something went wrong"

// Good: Specific and actionable
"Unable to sync customer data to Brevo. Please verify your Brevo API key
in Settings and try again."

إرشادات رسائل الخطأ:

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

الأمان

Secret Store API

استخدم Stripe Secret Store API لتخزين جميع البيانات الحساسة:

import { createHttpClient, STRIPE_API_KEY } from '@stripe/ui-extension-sdk/http_client';

// Good: Store secrets using the Secret Store API
const storeBrevoApiKey = async (apiKey: string) => {
  const stripe = createHttpClient(STRIPE_API_KEY);
  await stripe.apps.secrets.create({
    name: 'brevo_api_key',
    payload: apiKey,
    scope: { type: 'account' },
  });
};

// Good: Retrieve secrets from the Secret Store
const getBrevoApiKey = async () => {
  const stripe = createHttpClient(STRIPE_API_KEY);
  const secret = await stripe.apps.secrets.find({
    name: 'brevo_api_key',
    scope: { type: 'account' },
  });
  return secret.payload;
};

لا تخزن أبدًا البيانات الحساسة في:

• التخزين المحلي أو تخزين الجلسة
• ملفات تعريف الارتباط
• معاملات URL
• قيم مشفرة في الكود المصدري
• ملفات تكوين نصية عادية

التشفير

• بدون تشفير مخصص: لا تنفذ خوارزميات تشفير خاصة بك
• استخدم آليات أمان Stripe المدمجة (Secret Store، مفاتيح التوقيع)
• استخدم HTTPS لجميع استدعاءات API الخارجية
• تحقق من صحة جميع توقيعات webhook قبل المعالجة

معالجة البيانات

• اطلب فقط الأذونات التي يحتاجها تطبيقك فعلاً
• لا تخزن بيانات Stripe خارج ما هو ضروري للوظائف
• نفذ سياسات الاحتفاظ بالبيانات المتوافقة مع سياسة الخصوصية
• وفر آلية للمستخدمين لطلب حذف البيانات

الامتثال القانوني

سياسة الخصوصية

يجب أن يكون لتطبيقك سياسة خصوصية متاحة للعامة تغطي:

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

شروط الخدمة

• وفر شروط خدمة واضحة لتطبيقك
• لا تتضمن شروطًا تتعارض مع شروط خدمة Stripe
• حدد بوضوح أي قيود أو حدود استخدام

الامتثال التنظيمي

• التزم بجميع أنظمة حماية البيانات المعمول بها
• نفذ اتفاقيات معالجة البيانات المناسبة
• ادعم طلبات نقل البيانات وحذفها
• حافظ على سجلات تدقيق للوصول إلى البيانات ومعالجتها

الجدول الزمني لعملية المراجعة

الأسباب الشائعة للرفض

1. معالجة أخطاء مفقودة, يتعطل التطبيق عند أخطاء الشبكة أو البيانات غير المتوقعة
2. حالات تحميل غير كافية, شاشات فارغة أثناء جلب البيانات
3. تسعير غير واضح, التسعير غير مُفصح بالكامل في القائمة
4. أذونات مفرطة, طلب أذونات غير مطلوبة للتطبيق
5. وضع sandbox معطل, التطبيق لا يعمل في وضع الاختبار
6. مشاكل أمنية, تخزين الأسرار خارج Secret Store API
7. سياسة خصوصية مفقودة, بدون URL سياسة خصوصية متاح
8. وظائف غير مكتملة, ميزات “قريبًا” أو محتوى مؤقت