Use and adapt etjah-v2

Use the documented interfaces and source layout for etjah-v2. The sections below retain the README’s examples and configuration details.

كيف يعمل تطبيق الويب التقدمي (PWA)

تطبيق الويب التقدمي (PWA) هو تطبيق ويب يستخدم تقنيات الويب الحديثة لتقديم تجربة تشبه التطبيقات الأصلية للمستخدمين. يتميز هذا التطبيق بما يلي:

1. قابلية التثبيت: يمكن للمستخدمين تثبيت التطبيق مباشرة من المتصفح إلى الشاشة الرئيسية لأجهزتهم (Android و iOS) دون الحاجة إلى متاجر التطبيقات.
2. العمل دون اتصال بالإنترنت: بفضل عامل الخدمة (Service Worker)، يمكن للتطبيق العمل حتى في حالة عدم وجود اتصال بالإنترنت، مما يوفر تجربة مستخدم مستمرة.
3. السرعة والأداء: يتم تحميل المحتوى المخزن مؤقتًا بسرعة، مما يقلل من أوقات التحميل ويحسن الأداء العام.
4. تجربة المستخدم المحسّنة: يفتح التطبيق في وضع ملء الشاشة بدون واجهة مستخدم المتصفح، مما يوفر تجربة غامرة.

المكونات الرئيسية لـ PWA

• public/manifest.json: ملف JSON يصف التطبيق للمتصفح، بما في ذلك اسمه، أيقوناته، لون السمة، وكيف يجب أن يظهر عند التثبيت.
• public/sw.js (Service Worker): نص برمجي يعمل في الخلفية، منفصل عن صفحة الويب. يقوم بمعالجة طلبات الشبكة، وتخزين الأصول مؤقتًا (caching)، وتوفير وظائف دون اتصال بالإنترنت، وإدارة التحديثات.
• علامات <meta> في app/layout.tsx: علامات HTML إضافية في قسم <head> لدعم ميزات PWA الخاصة بـ iOS، مثل apple-mobile-web-app-capable و apple-touch-icon.
• components/pwa-install-prompt.tsx: مكون React يعرض مطالبة للمستخدم لتثبيت التطبيق عندما يكون متاحًا.
• components/service-worker-register.tsx: مكون React يقوم بتسجيل عامل الخدمة عند تحميل التطبيق.
• app/loading.tsx: مكون تحميل يظهر أثناء جلب البيانات على الخادم، مما يحسن تجربة المستخدم من خلال توفير ملاحظات مرئية.

كيفية تحديث عامل الخدمة (Service Worker)

عند إجراء تغييرات على ملف public/sw.js أو الأصول المخزنة مؤقتًا، يجب تحديث عامل الخدمة لضمان حصول المستخدمين على أحدث إصدار.

1. تغيير CACHE_NAME: في public/sw.js، قم بتغيير قيمة المتغير CACHE_NAME (على سبيل المثال، من etijah-real-estate-v1 إلى etijah-real-estate-v2). هذا سيجعل عامل الخدمة الجديد يرى أن هناك إصدارًا جديدًا من ذاكرة التخزين المؤقت.
2. تحديث urlsToCache: إذا أضفت صفحات جديدة أو أصولًا ثابتة مهمة، تأكد من إضافتها إلى مصفوفة urlsToCache في public/sw.js.
3. إعادة النشر: بعد إجراء التغييرات، قم بإعادة نشر تطبيقك. سيكتشف المتصفح عامل الخدمة الجديد، ويقوم بتثبيته في الخلفية، ثم ينشطه عند إغلاق المستخدم لجميع علامات تبويب التطبيق القديمة.

كيفية تخصيص ملف manifest.json

يمكنك تخصيص سلوك ومظهر PWA الخاص بك عن طريق تعديل public/manifest.json:

• name و short_name: اسم التطبيق الكامل والمختصر الذي يظهر للمستخدم.
• lang و dir: لغة التطبيق واتجاه النص (مهم جدًا لـ RTL).
• start_url: المسار الذي يجب أن يفتحه التطبيق عند التشغيل.
• display: يحدد وضع عرض التطبيق (على سبيل المثال، standalone لفتح التطبيق في نافذة خاصة به).
• theme_color و background_color: ألوان الواجهة التي يستخدمها المتصفح (مثل شريط الحالة).
• description: وصف موجز للتطبيق.
• icons: قائمة بأيقونات التطبيق بأحجام مختلفة. تأكد من وجود أيقونات 192x192 و 512x512 على الأقل.
• screenshots: (اختياري) لقطات شاشة لتطبيقك تظهر في واجهة تثبيت المتصفح.

Commands in the root manifest

The captured package.json declares the following scripts. Run them from the directory containing that manifest.

Troubleshoot a local change

1. Reproduce the smallest example from the quick-start guide.
2. Compare required configuration and dependency versions with the README.
3. Check the linked issue tracker for the same error. Include the command, runtime version, and relevant error when reporting a problem; omit credentials.

Source and help

• GitHub repository
• Original README
• Issues and existing reports
• Open the project website