توثيق تطبيق جوال لووكومرس

ما الذي اشتريته: ثلاثة أجزاء تعمل معًا

أي طريق أسلك؟

الصورة الكاملة في 8 خطوات

1. تأكد من جاهزية متجرك (الفصل 3).
2. ثبّت الإضافة (الفصل 4).
3. صمّم الشاشة الرئيسية (الفصل 5).
4. اختر الألوان وطرق تسجيل الدخول والروابط (الفصلان 6 و7).
5. أنشئ مشروع Firebase مجانيًا للإشعارات (الفصل 8).
6. ابنِ تطبيق أندرويد عبر الإنترنت (الفصل 10).
7. ثبّته على هاتفك واختبره (الفصل 11).
8. انشره على Google Play (الفصل 12).

قائمة التحقق

الحسابات التي قد تحتاج إليها

1. في لوحة تحكم WordPress افتح Plugins → Add New → Upload Plugin.
2. اختر الملف mobile-app-for-woocommerce-plugin.zip ثم انقر Install Now، ثم Activate.
   استخدم ملفات zip الداخلية فقط. لا ترفع ملف zip الكبير للحزمة الكاملة.
3. يظهر عنصران جديدان في القائمة اليسرى: App Layouts وApp Settings. وقد أُنشئت لك ثلاثة تخطيطات نموذجية.

تحقق من أنها تعمل

افتح هذا العنوان في متصفحك (استبدله بعنوان متجرك):

https://yourstore.com/wp-json/mo-app/v1/homepage

إذا ظهرت لك صفحة نصية مليئة بالأقواس المعقوفة فالإضافة تعمل. وإذا ظهرت عبارة «Active App Layout not configured» فهذا طبيعي في الوقت الحالي: ستختار التخطيط في الفصل 6.

1. انتقل إلى App Layouts وافتح Modern Store Homepage (أو انقر Add Post لإنشاء تخطيط جديد).
2. انقر الزر الأزرق + وابحث عن Mobile. ستجد ثلاث كتل: Mobile: App Banners وMobile: App Categories وMobile: App Product Collection.
3. أضف الكتل التي تريدها واسحبها إلى الترتيب الذي يناسبك.
4. انقر كتلة واستخدم الإعدادات على اليمين لتعديلها (انظر الجداول أدناه).
5. انقر Update (أو Publish).

الكتل الثلاث

اجعلها أجمل (في الكتل الثلاث)

• العنوان والوصف بألوان مستقلة لكلٍّ منهما.
• الخلفية: لون أو تدرّج لوني أو صورة.
• التباعد: الحشو فوق الكتلة وتحتها، والزوايا المستديرة.

اللوحة الجانبية: App Screen Settings

ستجد في اللوحة اليمنى App Screen Settings. وهي تتحكم في الشريط العلوي وشريط البحث لهذه الشاشة:

ما الذي يُحفظ خلف الكواليس (للفضوليين)

يُحفظ كل تخطيط على هيئة نص كتل بسيط كما يلي. لا تحتاج إلى كتابته أبدًا، وهو موجود هنا لتعرف أنه لا يوجد سحر في الأمر:

<!-- wp:wc-mobile/banners {"layoutType":"slider","bannerHeight":170,"showDots":true,"autoplay":true} /-->

<!-- wp:wc-mobile/categories {"title":"Shop by category","displayStyle":"horizontal_scroll"} /-->

<!-- wp:wc-mobile/products {"title":"Fresh picks for you","layoutType":"grid","gridColumns":2,"limit":6} /-->

General Settings

Drawer Menu

شغّل القائمة المنزلقة أو أوقفها، وأظهر My Wallet وReward Points أو أخفِهما (يحتاجان إلى إضافات إضافية، انظر الفصل 14)، واختر خلفيتها: لونًا أو تدرجًا لونيًا أو عنوان صورة.

Legal & Policies

الصق عناوين الويب لصفحات Privacy Policy وTerms & Conditions وReturn Policy. تشترط متاجر مثل Google Play وجود سياسة خصوصية.

Support & Social

بريد الدعم الإلكتروني، ورقم WhatsApp (مع رمز الدولة، مثل +971…)، وصفحاتك على Facebook وInstagram وX.

App Info & Updates

بعد النشر، الصق رابطي Play Store وApp Store. Minimum App Version: إذا كان إصدار العميل أقدم من هذا الرقم (مثل 1.0.5) يطلب منه التطبيق التحديث قبل المتابعة. اتركه فارغًا حتى تحتاج إليه فعلًا.

Theme (Flex)

إعداد تسجيل الدخول بالهاتف (OTP)

1. افتح قسم SMS / OTP في أسفل تبويب Integrations.
2. اختر 2Factor أو OTPless مزوّدًا.
3. الصق المفتاح أو المفاتيح التي حصلت عليها من مزوّدك في الحقول التي تظهر.
4. فعّل الخيار Enable Phone Login في الأعلى، ثم انقر Save All Settings.

الجزء أ: إنشاء المشروع وتسجيل تطبيق أندرويد

1. انتقل إلى console.firebase.google.com وسجّل الدخول بحساب Google الخاص بك.
2. انقر Add project، وسمِّه باسم متجرك وأكمل المعالج (يمكنك إيقاف Google Analytics).
3. داخل المشروع انقر أيقونة Android لإضافة تطبيق أندرويد.
4. في الحقل Android package name اكتب اسم الحزمة الذي تريده لتطبيقك، مثل com.yourshop.app. دوّنه: ستكتب الاسم نفسه في App Builder.
5. انقر Register app، ثم Download google-services.json. احتفظ بهذا الملف في مكان آمن. يمكنك تخطي بقية خطوات المعالج.

الجزء ب: نسخ أربع قيم إلى الإضافة

1. في Firebase انقر أيقونة الترس → Project settings → تبويب General.
2. مرّر إلى Your apps. انسخ API key وProject ID وApp ID وMessaging Sender ID (يوجد Sender ID في تبويب Cloud Messaging).
3. في WordPress افتح App Settings → Integrations & APIs → Firebase Configuration والصق كل قيمة في حقلها.

الجزء ج: المفتاح الذي يتيح لمتجرك إرسال الإشعارات

1. في إعدادات مشروع Firebase افتح تبويب Service accounts.
2. انقر Generate new private key. يُنزَّل ملف صغير ينتهي بـ .json.
3. افتح هذا الملف بمحرر نصوص (Notepad أو TextEdit)، وحدّد كل محتواه وانسخه.
4. الصقه في الحقل الكبير Firebase Service Account JSON في الإضافة وانقر Save All Settings.

الجزء د (لتسجيل الدخول عبر Google فقط)

1. في Firebase افتح Authentication → Sign-in method وفعّل Google.
2. بعد أول بناء، أضف بصمتي SHA-1 وSHA-256 للتطبيق في Project settings → تطبيق أندرويد الخاص بك. في بناءات Google Play استخدم البصمات التي يعرضها Google Play ضمن App integrity.
3. نزّل google-services.json مرة أخرى واستخدم الملف الجديد في البناء التالي.

إشعارات الطلبات التلقائية

في Integrations & APIs فعّل Order Placed وOrder Status Updated لإرسال إشعار فوري إلى هاتف العميل كلما أُنشئ طلب أو تغيرت حالته (قيد المعالجة، تم الشحن…).

في الأسفل، تتيح Notification Message Templates كتابة صياغتك الخاصة. يمكنك استخدام هذه العناصر النائبة (placeholders) التي تُستبدل بالتفاصيل الفعلية:

Title:  Order #{order_id} update
Message: Your order is now {order_status}. Thank you for shopping with us!

WhatsApp وSMS (اختياري)

• WhatsApp: يرسل إيصالات الطلبات وتحديثاتها عبر Meta Cloud API أو Twilio أو UltraMsg. الصق رمز المزوّد (token) ورقم المرسِل.
• SMS: يرسل تحديثات الطلبات عبر 2Factor أو MSG91 أو Twilio أو Unifonic. فعّل Order Updates via SMS والصق مفتاح المزوّد.

أرسل إعلانك الخاص

1. افتح تبويب Send Notification.
2. اكتب عنوانًا ورسالة (مثل «تخفيضات نهاية الأسبوع: خصم 20% على الفاكهة»).
3. اختر All users، أو Selected users وابحث بالاسم أو البريد الإلكتروني.
4. انقر إرسال. تعني الرسالة الخضراء أن Firebase قبلته. وتخبرك الرسالة الحمراء بما يجب إصلاحه.

ما تحتاج إليه جاهزًا أولًا

إنشاء مفاتيح WooCommerce (مرة واحدة)

1. افتح WooCommerce → Settings → Advanced → REST API → Add key.
2. Description: Mobile app. User: حساب المدير لديك. Permissions: Read/Write.
3. انقر Generate API key. انسخ Consumer key وConsumer secret إلى ملاحظة آمنة. يظهر السر (secret) مرة واحدة فقط.

املأ App Builder

1. افتح App Settings → App Builder.
2. ضمن Connect to Cloud Builder اكتب Site URL وPurchase Code، ثم انقر Fetch App Details. تخبرك رسالة خضراء أن الاتصال يعمل ويُفتح النموذج أدناه.
3. Basic App Information: اسم التطبيق، واسم الحزمة، وبريدك الإلكتروني، وهاتفك، ورمز الدولة المكوّن من حرفين (مثل AE وIN وUS).
4. Security Keys: الصق Consumer Key وConsumer Secret. أضف مفتاح Google Maps فقط إذا أردت أن يختار العملاء عناوينهم على الخريطة.
5. Facebook Login Setup: املأه فقط إذا كنت تستخدم تسجيل الدخول عبر Facebook.
6. Branding Images: اختر لون شاشة البداية، ثم اختر App Icon وLoading Logo وSplash Image وملف Firebase Config (google-services.json). يُرفع كل ملف لحظة اختياره ويظهر معه Uploaded Successfully بالأخضر.
7. اختر Build Output Type: APK للتجربة على هاتفك، أو App Bundle (AAB) لـ Google Play.
8. انقر Save Details، ثم Start Android Build.

ماذا يحدث بعد ذلك

قواعد يجب معرفتها

• الملفات الأربعة كلها مطلوبة: الأيقونة، وشعار التحميل، وصورة شاشة البداية، وgoogle-services.json.
• يجب أن يظهر اسم الحزمة داخل ملف google-services.json. في أول بناء لك، إذا اختلفا، تعتمد أداة البناء اسم الحزمة الموجود في الملف.
• يسمح رمز شراء واحد بعدد التطبيقات المذكور في ترخيصك (عادةً تطبيق واحد لعنوان متجر واحد). إذا ظهرت لك رسالة «maximum number of apps reached» فتواصل مع الدعم.
• بعض التراخيص مقصورة على بناءات APK. عندها تنشئ أداة البناء ملف APK حتى لو اخترت App Bundle.
• تنشئ أداة البناء ملفات أندرويد. أما آيفون فانظر الفصل 13.
• تُحذف الصور التي رفعتَها وملف Firebase من خادم البناء بعد نحو ثلاثة أشهر.

عندما يحدث خطأ

1. افتح البريد الإلكتروني على هاتف أندرويد الخاص بك وانقر Download APK (أو نزّل الملف على حاسوب وأرسله إلى الهاتف).
2. افتح الملف المنزَّل. قد يطلب منك أندرويد السماح بالتثبيت من هذا المصدر. اسمح به لهذه المرة فقط.
3. افتح التطبيق. انتظر بضع ثوانٍ: تظهر شاشة البداية ثم شاشتك الرئيسية.
4. اتبع قائمة التحقق هذه.

Google Play (أندرويد)

1. أنشئ حساب مطوّر في Google Play Console.
2. أنشئ تطبيقًا جديدًا واملأ صفحة المتجر: وصفًا قصيرًا وآخر طويلًا، وأيقونة، ولقطات شاشة للتطبيق، وصورة مميزة (feature graphic).
3. أضف رابط سياسة الخصوصية (مطلوب).
4. أجب عن استبيانات المحتوى (الإعلانات، وأمان البيانات، والفئة العمرية المستهدفة). وضّح أن التطبيق يستخدم الموقع لملء عنوان التوصيل، ولا يعرض إعلانات.
5. ابنِ App Bundle (AAB) في App Builder، وارفعه ضمن Production → Create release، ثم أرسله للمراجعة.
6. تستغرق المراجعة عادةً من بضع ساعات إلى بضعة أيام. بعد ذلك الصق رابط المتجر في App Settings → App Info & Updates.

Apple App Store (آيفون)

يحتاج تطبيق آيفون إلى جهاز Mac مثبّت عليه Xcode وحساب Apple Developer، لذا يُنجز هذا الجزء من الشيفرة المصدرية بمساعدة مطوّر (الفصل 13). كما تشترط Apple Sign in with Apple إذا قدّم التطبيق تسجيلات دخول اجتماعية أخرى، وسياسة خصوصية.

الإعداد لمرة واحدة

1. ثبّت Flutter بالإصدار 3.41 أو أحدث (يثبّت Dart أيضًا).
2. شغّل flutter doctor وأصلح كل بند يبلّغ عنه (Android SDK والتراخيص، وXcode، وCocoaPods).
3. فُكّ ضغط flutter-app-source.zip، وافتح الطرفية في المجلد وشغّل:

flutter pub get

وجّه التطبيق إلى متجرك

افتح lib/core/constants/app_config.dart وغيّر سطرين:

static const String siteUrl = 'https://yourstore.com';   // no slash at the end
static const String appName = 'My Store';

يُضاف مسار API وهو /wp-json/mo-app/v1 تلقائيًا. للاختبار مع متجر على حاسوبك استخدم عنوانًا يستطيع الهاتف الوصول إليه: في محاكي أندرويد http://10.0.2.2:8888/wp، وفي محاكي آيفون http://localhost:8888/wp.

الاسم والمعرّف والأيقونة وشاشة البداية والإصدار

dart run change_app_package_name:main com.yourbrand.app

dart run flutter_launcher_icons

dart run flutter_native_splash:create

ملفات Firebase

لا تحتوي الحزمة على أي ملفات Firebase: فهي تخص مشروعك أنت (الفصل 8).

• أندرويد: ضع google-services.json في android/app/، ثم أضف إضافة خدمات Google. في android/settings.gradle.kts أضف داخل plugins { }:

id("com.google.gms.google-services") version "4.4.2" apply false

وفي android/app/build.gradle.kts أضف داخل plugins { }:

id("com.google.gms.google-services")

• آيفون: افتح ios/Runner.xcworkspace في Xcode، واسحب GoogleService-Info.plist إلى مجلد Runner وفعّل Copy items if needed.

بدون هذين الملفين يبقى التطبيق يعمل للتسوّق بشكل طبيعي، لكن الإشعارات الفورية وتسجيل الدخول عبر Google تكونان متوقفتين.

Facebook وGoogle وApple والخرائط

في ios/Runner/Info.plist استبدل القيم النائبة:

<string>fbYOURAPPID</string>      <!-- keep the fb prefix -->
<key>FacebookAppID</key><string>YOURAPPID</string>
<key>FacebookClientToken</key><string>CLIENT-TOKEN</string>

لنظام أندرويد اتبع دليل الحزمة flutter_facebook_auth. فعّل Google وApple في Firebase Authentication؛ ويحتاج تسجيل الدخول عبر Apple أيضًا إلى القدرة Sign in with Apple في Xcode. لا يحتاج Razorpay إلى مفتاح في التطبيق: يُقرأ من إعدادات Razorpay في WooCommerce لديك.

التشغيل والبناء

flutter run                          # on a phone or emulator
flutter build apk --release          # Android APK
flutter build appbundle --release    # Android AAB for Google Play
flutter build ipa --release          # iPhone (on a Mac)

توقيع تطبيق أندرويد لـ Google Play

تستخدم بناءات الإصدار (release) مفتاح التصحيح (debug) حتى تضيف مفتاحك الخاص. أنشئ مفتاحًا مرة واحدة واحتفظ به في مكان آمن:

keytool -genkey -v -keystore ~/upload-keystore.jks -keyalg RSA -keysize 2048 -validity 10000 -alias upload

أنشئ android/key.properties:

storePassword=YOUR_PASSWORD
keyPassword=YOUR_PASSWORD
keyAlias=upload
storeFile=/Users/you/upload-keystore.jks

وفي android/app/build.gradle.kts حمّله واستخدمه في signingConfigs / buildTypes.release كما هو موضح في دليل توقيع Flutter. أما لآيفون فاختر فريقك في Xcode → Signing & Capabilities.

العنوان الأساسي: https://yourstore.com/wp-json/mo-app/v1. ترسل الطلبات التي تتطلب تسجيل الدخول الترويسة X-App-Token التي يعيدها طلب تسجيل الدخول.

جرّب بنفسك

# The home layout and global settings
curl https://yourstore.com/wp-json/mo-app/v1/homepage

# Products: page 1, 10 items, search for "milk"
curl "https://yourstore.com/wp-json/mo-app/v1/products?page=1&per_page=10&search=milk"

# Log in and keep the token
curl -X POST https://yourstore.com/wp-json/mo-app/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"customer@example.com","password":"secret"}'

# Use the token to read the customer's orders
curl https://yourstore.com/wp-json/mo-app/v1/orders -H "X-App-Token: YOUR_TOKEN"

مثال بلغة Dart (داخل التطبيق)

final res = await dio.get('/products', queryParameters: {'category': 'fruits', 'per_page': 20});
final products = res.data['products'];

جميع نقاط النهاية

يحتوي مجلد includes/api في الإضافة على ملف لكل مجموعة مع المعاملات الدقيقة.

حدّث الإضافة برفع ملف zip الجديد (Replace current with uploaded)؛ وتبقى تخطيطاتك وإعداداتك محفوظة. وحدّث التطبيق ببناء إصدار جديد ورفعه إلى المتاجر. ولإزالة الإضافة، عطّلها واحذفها؛ وتبقى تخطيطات تطبيقك في قاعدة البيانات حتى تحذفها من App Layouts.

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