1. مقدمة
لإضافة ميزة الشراء داخل التطبيق إلى تطبيق Flutter، يجب ضبط Apple App Store و"متجر Google Play"، والتحقّق من رموز الشراء المميّزة على واجهة خلفية موثوقة، ومنح أذونات مثل العملات القابلة للاستهلاك أو الترقيات لمرة واحدة أو مزايا الاشتراك المتكرّر.
في هذا الدرس التطبيقي حول الترميز، ستتعاون مع Google Antigravity لإنشاء Dash Clicker، وهي لعبة نقر على الأجهزة الجوّالة تستخدم تميمة Dash كعملة، وربطها بخدمة خلفية shelf بلغة Dart وCloud Firestore للتحقّق من ثلاثة أنواع من عمليات الشراء داخل التطبيق وتتبُّعها:
- منتج استهلاكي (
dash_consumable_2k): عملية شراء قابلة للتكرار تمنح اللاعب على الفور 2,000 نقطة من نقاط Dash ويمكن شراؤها عدة مرات. - منتج غير استهلاكي (
dash_upgrade_3d): ترقية دائمة لمرة واحدة تحوّل تميمة Dash الكلاسيكية إلى تميمة Dash ثلاثية الأبعاد حديثة إلى الأبد. - الاشتراك (
dash_subscription_doubler): اشتراك يتم تجديده تلقائيًا ويضاعف النقرات التي يتم إنشاؤها بشكل سلبي طالما أنّ الاشتراك نشط.
|
|
|
ما ستنشئه
- تطبيق Flutter للأجهزة الجوّالة (
app/) مصمَّم باستخدامmaterial_uiوcupertino_uiيطلب منتجات المتجر ويبدأ عمليات الشراء ويتفاعل مع أحداث الشراء في الوقت الفعلي. - خادم خلفي من Dart
shelf(dart-backend/) يتحقّق من إيصالات الشراء من خلال Google Play وApp Store، ويستطلع أحداث الفوترة في المتجر، ويسجّل حالات الشراء في Cloud Firestore.
رحلتك نحو التعلم
يساعدك هذا الدرس التطبيقي حول الترميز في إنشاء مسار الشراء داخل التطبيق وربطه بالكامل خطوة بخطوة:
- إعداد بيئة التطوير: ثبِّت Flutter وGoogle Antigravity، واطلب من Antigravity إنشاء مشروع Dash Clicker الأوّلي (
app/)، واضبط معرّف حزمة iOS وapplicationIdلنظام Android. - تثبيت المكوّن الإضافي: اطلب من Antigravity إضافة
in_app_purchaseوin_app_purchase_platform_interfaceإلىapp/. - إعداد App Store: سجِّل معرّف التطبيق، وأنشئ حساب اختبار في وضع الحماية، واضبط المنتجات الثلاثة في App Store Connect.
- إعداد "متجر Google Play": أنشئ تطبيقك في Google Play Console، واطلب من Antigravity إعداد توقيع ملف تخزين المفاتيح للإصدار في Gradle، وحمِّل حزمة تطبيق أولية، وأضِف مختبِري التراخيص، واضبط المنتجات.
- إعداد Firebase: فعِّل ميزتَي "تسجيل الدخول باستخدام حساب Google" وCloud Firestore في وحدة تحكُّم Firebase، وشغِّل
flutterfire configure، واضبط الملفات المرجعية SHA-1 لنظام التشغيل Android ومخطّطات عناوين URL لنظام التشغيل iOS. - الاستماع إلى تحديثات الشراء: اطلب من Antigravity إضافة برنامج تضمين
IAPConnectionقابل للاختبار، والاشتراك فيpurchaseStream، واختبار التطبيق باستخدامTestIAPConnection. - إجراء عمليات الشراء: يمكنك أن تطلب من Antigravity تضمين
ProductDetailsفيPurchasableProduct، والاستعلام عن منتجات المتجر، وتفعيلbuyConsumableوbuyNonConsumable، وإكمال عمليات الشراء المعلّقة. - إعداد الخلفية: اطلب من Antigravity إنشاء خادم
dart-backend/باستخدامIapRepositoryوضبط بيانات اعتماد حساب الخدمة. - التحقّق من عمليات الشراء: اطلب من Antigravity فرض تسجيل الدخول إلى Firebase على
PurchasePage، وإرسال رموز الشراء المميّزة إلى/verifypurchase، وتنفيذGooglePlayPurchaseHandlerوAppStorePurchaseHandler. - تتبُّع عمليات الشراء: يمكنك توجيه Antigravity لاستطلاع Google Cloud Pub/Sub وواجهة App Store Server API في الخلفية ومزامنة الأذونات مع عميل Flutter باستخدام
IAPRepo.
أهداف الدورة التعليمية
- كيفية التعاون مع Google Antigravity لإنشاء وتخصيص تطبيق Flutter متكامل لعمليات الشراء داخل التطبيق وخلفية Dart بشكل متكرر.
- كيفية ضبط App Store Connect وGoogle Play Console باستخدام المنتجات الاستهلاكية وغير الاستهلاكية والمنتجات المتوفّرة عند الاشتراك
- كيفية الاستعلام عن المنتجات وبدء عمليات الشراء والتعامل مع عمليات الشراء باستخدام المكوّن الإضافي
in_app_purchase - كيفية التحقّق من رموز الشراء المميّزة على Google Play ومتجر التطبيقات في الخلفية في Dart وتخزينها في Cloud Firestore
- كيفية معالجة أحداث الفوترة في المتجر ومزامنة أذونات الاشتراك والترقية على جميع الأجهزة
المتطلبات الأساسية
- معرفة أساسية بتطبيقات Flutter المصغّرة وصيغة Dart وإدارة حالة
Provider - حساب مطوِّر على Apple (لاختبار عمليات الشراء من App Store على أجهزة iOS) أو حساب مطوِّر على Google Play (لاختبار عمليات الشراء من "متجر Play" على أجهزة Android) أو كليهما
- حساب على Firebase وFirebase CLI
2. إعداد بيئة التطوير
محرِّر
يستخدم هذا الدرس التطبيقي حول الترميز Google Antigravity كبيئة تطوير مستنِدة إلى الذكاء الاصطناعي. في كل خطوة، يمكنك أن تطلب من Antigravity إنشاء أو تطوير عميل Flutter (app/) وخلفية Dart (dart-backend/)، وفحص الرمز الذي تم إنشاؤه، واستكشاف الصيغ المختلفة اختياريًا.
تثبيت Flutter
تتوفّر دائمًا أحدث التعليمات حول تثبيت حزمة تطوير البرامج (SDK) من Flutter على docs.flutter.dev.
في هذا الدرس التطبيقي حول الترميز، ثبِّت البرامج التالية:
- حزمة تطوير البرامج (SDK) من Flutter
- Google Antigravity مع تفعيل المكوّن الإضافي الرسمي لـ Dart وFlutter (متاح في Plugin Marketplace ضمن قسم Build with Google).
- برنامج تجميع لنظام التشغيل المستهدَف على الأجهزة الجوّالة (Android Studio لاستهداف Android أو Xcode لاستهداف iOS)
اطلب من Antigravity إنشاء مشروع للمبتدئين
- افتح Google Antigravity وانتقِل إلى دليل مساحة عمل فارغ حيث تريد إنشاء كل من تطبيق Flutter (
app/) وخادم Dart (dart-backend/). اختَر مسارًا لا يتطلّب أذونات مميزة وعالية المستوى أو يحتوي على مسافات، مثل مجلد في الدليل الرئيسي أوC:\src\. - في لوحة محادثة وكيل Antigravity، أرسِل الطلب التالي لإنشاء تطبيق Dash Clicker الأوّلي في
app/:
Create a new empty Flutter project in `app/` named `dashclicker` targeting Android and iOS (`flutter create app --project-name dashclicker --empty --platforms android,ios`). Add the `cloud_firestore`, `cupertino_icons`, `firebase_auth`, `firebase_core`, `google_sign_in`, `http`, `intl`, `provider`, `logging`, `material_ui`, and `cupertino_ui` packages. Download `dash_old.png` and `dash.png` from `https://raw.githubusercontent.com/flutter/codelabs/main/in_app_purchases/step_00/app/assets/dash_old.png` and `https://raw.githubusercontent.com/flutter/codelabs/main/in_app_purchases/step_00/app/assets/dash.png` into `app/assets/` and register `assets/` under `flutter: assets:` in `app/pubspec.yaml`. Set `minSdk = 23` in `app/android/app/build.gradle.kts`, and add `GIDClientID` and `CFBundleURLTypes` placeholders in `app/ios/Runner/Info.plist`. Scaffold the Dash Clicker starter files using `package:material_ui/material_ui.dart` and `package:cupertino_ui/cupertino_ui.dart`:
- `lib/constants.dart` defining `cloudRegion = 'europe-west1'`, `storeKeyConsumable = 'dash_consumable_2k'`, `storeKeyUpgrade = 'dash_upgrade_3d'`, `storeKeySubscription = 'dash_subscription_doubler'`, and `serverIp = '192.168.178.46'`
- `lib/firebase_options.dart` with a placeholder `DefaultFirebaseOptions` for Android and iOS
- `lib/model/firebase_state.dart` (`enum FirebaseState { loading, available, notAvailable }`), `lib/model/store_state.dart` (`enum StoreState { loading, available, notAvailable }`), `lib/model/purchasable_product.dart` (`enum ProductStatus { purchasable, purchased, pending }` and `PurchasableProduct(this.title, this.description, this.price)`), and `lib/model/past_purchase.dart` (`PurchaseType`, `Store`, `Status`, and `PastPurchase.fromJson`)
- `lib/logic/dash_counter.dart` (`DashCounter extends ChangeNotifier` with `count`, `countString`, `increment()`, `addAutoIncrement()`, `applyPaidMultiplier()`, `removePaidMultiplier()`, `addBoughtDashes(int amount)`, and a 10Hz `Timer.periodic`)
- `lib/logic/dash_purchases.dart` (`DashPurchases extends ChangeNotifier` with `counter`, `storeState = StoreState.available`, mock `products`, `bool get beautifiedDash => false`, and a simulated `buy(PurchasableProduct product)` method)
- `lib/logic/dash_upgrades.dart` (`DashUpgrades extends ChangeNotifier` and `Upgrade` for `'Tim Sneath'`)
- `lib/logic/firebase_notifier.dart` (`FirebaseNotifier extends ChangeNotifier` initializing `Firebase.initializeApp`, `GoogleSignIn.instance`, `FirebaseAuth`, and `FirebaseFirestore`)
- `lib/repo/iap_repo.dart` (`IAPRepo extends ChangeNotifier` listening to Firebase auth changes and the `purchases` collection in Firestore)
- `lib/pages/home_page.dart` (`HomePage`, `DashClickerWidget`, `CounterStateWidget`, and `UpgradeList`), `lib/pages/login_page.dart` (`LoginPage`), and `lib/pages/purchase_page.dart` (`PurchasePage`, `_PurchasesLoading`, `_PurchasesNotAvailable`, `_PurchaseList`, `_PurchaseWidget`, and `PastPurchasesWidget`)
- `lib/main.dart` (`MyApp` and `MyHomePage` providing `FirebaseNotifier`, `DashCounter`, `DashUpgrades`, `IAPRepo`, and `DashPurchases` using `MultiProvider` with a `BottomNavigationBar` switching between `HomePage` and `PurchasePage`)
- `test/widget_test.dart` pumping `const MyApp()` and verifying `find.text('Tim Sneath')`.
فهم الرمز الأوّلي الذي تم إنشاؤه
تنشئ Antigravity مشروع Flutter باسم app/ وتضع هيكل لعبة Dash Clicker باستخدام Provider وChangeNotifier:
- يسجّل "
app/lib/main.dart" خمسةChangeNotifierProvider(FirebaseNotifierوDashCounterوDashUpgradesوIAPRepoوDashPurchases) داخل "MyHomePage" ويبدّل بين "HomePage" و"PurchasePage". - يحدّد
app/lib/constants.dartمعرّفات المنتجات الثلاثة في المتجر التي يجب أن تتطابق مع المعرّفات التي تضبطها في App Store Connect وGoogle Play Console:
const cloudRegion = 'europe-west1';
const storeKeyConsumable = 'dash_consumable_2k';
const storeKeyUpgrade = 'dash_upgrade_3d';
const storeKeySubscription = 'dash_subscription_doubler';
// TODO: Replace by your own server IP
const serverIp = '192.168.178.46';
ضبط معرّف حزمة تطبيقك ومعرّف التطبيق
للتواصل مع App Store و"متجر Play"، يحتاج تطبيقك إلى معرّف نطاق عكسي فريد (على سبيل المثال، dev.flutter.dashclicker). يُطلق على هذا المعرّف في نظام التشغيل iOS اسم معرّف الحزمة، وفي نظام التشغيل Android اسم معرّف التطبيق. يؤدي استخدام المعرّف نفسه على كلا النظامَين الأساسيَين إلى تبسيط عملية الإعداد.
أولاً، عليك إعداد معرّف الحزمة لنظام التشغيل iOS من خلال فتح app/ios/Runner.xcworkspace في Xcode:

في "مستكشف المشروع" (Project navigator) في Xcode، اختَر Runner في أعلى الصفحة، وافتح علامة التبويب Signing & Capabilities (التوقيع والإمكانات)، واختَر Team (الفريق)، وأدخِل Bundle Identifier (معرّف الحزمة) الفريد:

بعد ذلك، عليك تعديل applicationId في Android في app/android/app/build.gradle.kts ليتطابق مع المعرّف الذي اخترته (يمكنك تعديله مباشرةً أو الطلب من Antigravity تعديل applicationId في app/android/app/build.gradle.kts إلى المعرّف الذي اخترته):

3- تثبيت المكوّن الإضافي
في هذه الخطوة، عليك أن تطلب من Antigravity إضافة المكوّن الإضافي in_app_purchase وحزمة واجهة النظام الأساسي الخاصة به (المستخدَمة لمحاكاة اتصالات المتجر في اختبارات التطبيقات المصغّرة) إلى app/.
اطلب من Antigravity تثبيت "in_app_purchase"
في لوحة دردشة وكيل Antigravity، أرسِل الطلب التالي:
In `app/`, add `in_app_purchase` to `dependencies` and `in_app_purchase_platform_interface` to `dev_dependencies` in `pubspec.yaml`.
فهم الرمز البرمجي الذي تم إنشاؤه
يشغِّل Antigravity تطبيق "flutter pub add in_app_purchase dev:in_app_purchase_platform_interface" داخل "app/"، ويعدِّل "app/pubspec.yaml":
dependencies:
flutter:
sdk: flutter
cloud_firestore: ^7.1.0
cupertino_icons: ^2.0.0
cupertino_ui: ^1.1.6
firebase_auth: ^7.0.1
firebase_core: ^5.1.0
google_sign_in: ^7.2.0
http: ^1.6.0
in_app_purchase: ^3.3.1
intl: ^0.20.3
logging: ^1.3.0
material_ui: ^1.11.0
provider: ^6.1.5+1
dev_dependencies:
flutter_test:
sdk: flutter
flutter_lints: ^6.0.0
in_app_purchase_platform_interface: ^1.4.1
- توفّر حزمة
in_app_purchaseواجهة برمجة التطبيقاتInAppPurchaseالتي تعمل على عدّة منصات، وتستند إلى StoreKit على أجهزة iOS و"الفوترة في Google Play" على أجهزة Android. - توفّر
in_app_purchase_platform_interfaceواجهة برمجة التطبيقاتInAppPurchasePlatformAdditionالتي تتيح لك تنفيذ عميلInAppPurchaseوهمي فيapp/test/widget_test.dart.
4. إعداد متجر التطبيقات
لاختبار عمليات الشراء داخل التطبيق على أجهزة iOS، عليك تسجيل تطبيقك في App Store Connect وضبط المنتجات القابلة للشراء. ليس عليك نشر التطبيق أو إرساله للمراجعة، ولكن يجب أن يكون لديك حساب مطوِّر من Apple. إذا لم يكن لديك حساب، يمكنك التسجيل في Apple Developer Program.
اتفاقيات التطبيقات المدفوعة
لاستخدام عمليات الشراء داخل التطبيق، يجب أن تكون لديك اتفاقية تطبيقات مدفوعة نشطة في App Store Connect. انتقِل إلى App Store Connect، واختَر الاتفاقيات والضرائب والخدمات المصرفية (Agreements, Tax, and Banking) (أو النشاط التجاري (Business)).

راجِع اتفاقيات التطبيقات المجانية والمدفوعة. اطّلِع على بنود التطبيقات المدفوعة ووافِق عليها، وأدخِل المعلومات الضريبية والمصرفية المطلوبة.

عند ضبط كل شيء، تتغيّر حالة التطبيقات المدفوعة إلى نشطة. بدون اتفاقية "التطبيقات المدفوعة" (Paid Apps) نشطة، لن يعرض StoreKit منتجاتك داخل التطبيق أثناء الاختبار.

تسجيل معرّف تطبيق
أنشئ معرّف تطبيق جديدًا في "بوابة مخصّصة للمطوّرين" (Developer Portal) في Apple:
- انتقِل إلى معرّفات مطوّري برامج Apple وانقر على الرمز + بجانب العنوان المعرّفات.

- اختَر معرّفات التطبيقات وانقر على متابعة.

- اختَر تطبيق كنوع الإعلان، ثم انقر على متابعة.

- أدخِل وصفًا واضبط معرّف الحزمة (صريح) على معرّف الحزمة نفسه الذي ضبطته في Xcode. تأكَّد من تفعيل ميزة الشراء داخل التطبيق، ثم سجِّل المعرّف.

لمزيد من التفاصيل، يُرجى الاطّلاع على مساعدة حساب المطوّر على Apple.
إنشاء تطبيق جديد ومستخدم في وضع الحماية
أنشئ تطبيقًا جديدًا في App Store Connect باستخدام معرّف الحزمة المسجَّل:
|
|
لمزيد من الإرشادات حول إنشاء تطبيق وإدارة الاتفاقيات، يُرجى الاطّلاع على مركز مساعدة App Store Connect.
لاختبار عمليات الشراء داخل التطبيق بدون تحصيل رسوم حقيقية، أنشِئ حساب Apple في وضع Sandbox في App Store Connect ضمن المستخدمون والوصول > وضع Sandbox. يجب استخدام عنوان بريد إلكتروني غير مرتبط بحساب Apple.

على جهاز iPhone أو iPad التجريبي، سجِّل الدخول باستخدام حساب وضع الحماية ضمن الإعدادات > المطوّر > حساب Apple في وضع الحماية (Settings > Developer > Sandbox Apple Account).
|
|
ضبط عمليات الشراء داخل التطبيق
بعد ذلك، اضبط العناصر الثلاثة القابلة للشراء في App Store Connect:
-
dash_consumable_2k: منتج استهلاكي يمكن شراؤه بشكل متكرر، ويمنح 2,000 Dash لكل عملية شراء. -
dash_upgrade_3d: عملية شراء لترقية غير استهلاكية يمكن إجراؤها مرة واحدة فقط، وتتيح فتح شخصية التميمة "داش" الثلاثية الأبعاد. dash_subscription_doubler: اشتراك يتجدّد تلقائيًا ويضاعف النقرات غير النشطة أثناء تفعيله.

في قسمَي عمليات الشراء داخل التطبيق (والاشتراكات) في تطبيقك، أنشئ المنتجات الثلاثة باستخدام معرّفات المنتجات التالية بالضبط:
- منتج استهلاكي (
dash_consumable_2k):- أنشئ منتجًا استهلاكيًا يحمل الاسم المرجعي
dash consumable 2kومعرّف المنتجdash_consumable_2k.
- اضبط إعدادات التوفّر ليكون المنتج متاحًا في بلد مستخدم وضع الحماية أو منطقته.

- اضبط السعر على
\$1.99(أو ما يعادله بالعملة المحلية).
- أضِف ترجمة بالاسم المعروض "
Spring is in the air" والوصف "2000 dashes fly out".
- حمِّل لقطة شاشة للمراجعة. لا يهم محتوى الصورة في اختبار وضع الحماية، ولكن يؤدي تحميل لقطة شاشة إلى نقل المنتج إلى الحالة جاهز للإرسال، وهو أمر مطلوب لكي يجلب التطبيق المنتج من StoreKit.

- أنشئ منتجًا استهلاكيًا يحمل الاسم المرجعي
- منتج غير استهلاكي (
dash_upgrade_3d):- أنشئ منتجًا غير استهلاكي يحمل الاسم المرجعي
dash upgrade 3dومعرّف المنتجdash_upgrade_3d. - اضبط "الاسم المعروض" على
3D Dashو"الوصف" علىBrings your dash back to the futureو"السعر" على\$0.99. - اضبط إعدادات التوفّر وحمِّل لقطة شاشة للمراجعة تمامًا كما فعلت مع "
dash_consumable_2k".
- أنشئ منتجًا غير استهلاكي يحمل الاسم المرجعي
- اشتراك يتجدّد تلقائيًا (
dash_subscription_doubler):- ضمن الاشتراكات، أنشِئ مجموعة اشتراكات باسم
subscriptions(يمكن للمستخدمين الاشتراك في منتج واحد فقط ضمن المجموعة نفسها في كل مرة، ويمكنهم الترقية أو الاشتراك في خطة أقلّ كلفة ضمن المجموعة).
- أضِف ترجمة محلية في متجر التطبيقات لمجموعة الاشتراكات.

- داخل المجموعة، أنشئ اشتراكًا يحمل الاسم المرجعي
dash subscription doublerومعرّف المنتجdash_subscription_doubler.
- اضبط مدة الاشتراك على أسبوع واحد، والاسم المعروض على
Jet Engine، والوصف علىDoubles your clicks، والسعر على\$0.49. اضبط إعدادات التوفّر وحمِّل لقطة شاشة للمراجعة حتى تصبح الحالة جاهز للإرسال.
- ضمن الاشتراكات، أنشِئ مجموعة اشتراكات باسم
من المفترض أن تظهر منتجاتك الآن في App Store Connect بالحالة جاهز للإرسال:


5- إعداد "متجر Google Play"
لاختبار عمليات الشراء داخل التطبيق على Android، تحتاج إلى حساب مطوِّر على Google Play. إذا لم يكن لديك حساب، يمكنك التسجيل لإنشاء حساب مطوِّر على Google Play.
إنشاء تطبيق جديد
أنشئ تطبيقًا جديدًا في Google Play Console:
- افتح Google Play Console.
- اختَر جميع التطبيقات > إنشاء تطبيق.
- اختَر لغة تلقائية وأدخِل اسم التطبيق (يمكنك تغيير ذلك لاحقًا).
- اختَر لعبة كنوع التطبيق ومجاني كنموذج الأسعار.
- أكمِل بيانَي سياسات المطوّرين وقوانين التصدير الأمريكية، ثم اختَر إنشاء تطبيق.
بعد إنشاء التطبيق، أكمِل مهام إعداد تطبيقك الأولية في لوحة البيانات:

توقيع التطبيق
لاختبار خدمة "الفوترة في Google Play"، يجب تحميل إصدار موقَّع واحد على الأقل appbundle إلى قناة اختبار في Google Play Console.
إنشاء ملف تخزين مفاتيح
إذا لم يكن لديك ملف تخزين مفاتيح التحميل، يمكنك إنشاء ملف من الوحدة الطرفية.
على نظام التشغيل macOS أو Linux:
keytool -genkey -v -keystore ~/key.jks -keyalg RSA -keysize 2048 -validity 10000 -alias key
في نظام التشغيل Windows:
keytool -genkey -v -keystore c:\Users\USER_NAME\key.jks -storetype JKS -keyalg RSA -keysize 2048 -validity 10000 -alias key
إنشاء app/android/key.properties
أنشئ ملف app/android/key.properties يحتوي على مرجع لملف تخزين المفاتيح:
storePassword=<password from previous step>
keyPassword=<password from previous step>
keyAlias=key
storeFile=<location of the key store file, such as /Users/<user name>/key.jks>
اطلب من Antigravity إعداد توقيع الإصدار في Gradle
أرسِل الطلب التالي في Antigravity لربط توقيع الإصدار في app/android/app/build.gradle.kts:
Update `app/android/app/build.gradle.kts` to load `key.properties` into a `Properties` object if the file exists, configure a `release` signing config inside `signingConfigs` using `keyAlias`, `keyPassword`, `storeFile`, and `storePassword`, and assign `signingConfigs.getByName("release")` to the `release` build type when `key.properties` is present.
تحديثات Antigravity app/android/app/build.gradle.kts لتحميل key.properties وتوقيع بُنى الإصدار:
val keystoreProperties = Properties()
val keystorePropertiesFile = rootProject.file("key.properties")
if (keystorePropertiesFile.exists()) {
keystoreProperties.load(FileInputStream(keystorePropertiesFile))
}
android {
// ...
signingConfigs {
create("release") {
keyAlias = keystoreProperties["keyAlias"] as String?
keyPassword = keystoreProperties["keyPassword"] as String?
storeFile = keystoreProperties["storeFile"]?.let { file(it) }
storePassword = keystoreProperties["storePassword"] as String?
}
}
buildTypes {
release {
signingConfig = signingConfigs.getByName("release")
}
}
}
تحميل الإصدار الأول
أنشِئ حِزمة تطبيق إصدار موقَّعة من app/:
cd app
flutter build appbundle
تتم كتابة حزمة الإصدار في app/build/app/outputs/bundle/release/app-release.aab.
في Google Play Console، انتقِل إلى الاختبار والإصدار > الاختبار > الاختبار المغلق، وأنشئ إصدارًا للاختبار المغلق، وحمِّل app-release.aab، ثم انقر على حفظ > مراجعة الإصدار > بدء طرح الإصدار للاختبار المغلق.
إعداد مستخدمين اختباريين
لاختبار عمليات الشراء داخل التطبيق على Android، أضِف حسابات Google الخاصة بالمختبِرين في مكانَين في Google Play Console:
- مختبِرو مسار الاختبار: انتقِل إلى الاختبار والإصدار > الاختبار > الاختبار الداخلي (أو الاختبار المغلق)، وافتح علامة التبويب المختبِرون، ثم انقر على إنشاء قائمة عناوين بريد إلكتروني، وأضِف عناوين البريد الإلكتروني للمختبِرين، واختَر القائمة، ثم انقر على حفظ التغييرات.

- مختبِرو الترخيص: يُرجى الرجوع إلى عرض جميع التطبيقات، واختيار الإعدادات > اختبار الترخيص، وإضافة عناوين البريد الإلكتروني نفسها للمختبِرين، وضبط الردّ على الترخيص على "
RESPOND_NORMALLY"، ثم النقر على حفظ التغييرات.
ضبط عمليات الشراء داخل التطبيق
اضبط معرّفات المنتجات الثلاثة نفسها في Google Play Console:
-
dash_consumable_2k: منتج استهلاكي يمنحك 2,000 Dash. -
dash_upgrade_3d: ترقية لمرة واحدة في لعبة 3D Dash غير قابلة للاستهلاك. -
dash_subscription_doubler: اشتراك يتجدّد تلقائيًا في ميزة مضاعفة النقرات
أولاً، أنشئ المنتجات المدفوعة لمرة واحدة (dash_consumable_2k وdash_upgrade_3d):
- اختَر تطبيقك في Google Play Console وانتقِل إلى تحقيق الربح من خلال Play > المنتجات > المنتجات داخل التطبيق.
- انقر على إنشاء منتج.

- أدخِل معرّف المنتج (
dash_consumable_2k) واسمه ووصفه وسعره بدقة، ثم انقر على حفظ وتفعيل. - كرِّر العملية مع
dash_upgrade_3d.
بعد ذلك، أنشئ الاشتراك (dash_subscription_doubler):
- انتقِل إلى تحقيق الربح المادي باستخدام Google Play > المنتجات > الاشتراكات وانقر على إنشاء اشتراك.

- أدخِل معرّف المنتج (
dash_subscription_doubler)، وأضِف خطة أساسية مع مدة فوترة وسعر أسبوعيَين، ثم انقر على حفظ وتفعيل.
6. إعداد Firebase
يوفّر استخدام خدمة خلفية مع Cloud Firestore للتحقّق من عمليات الشراء وتتبُّعها العديد من مزايا الأمان لتطبيقك:
- يمكنك التحقّق من المعاملات مباشرةً من خلال خوادم Google Play وApple.
- يمكنك التفاعل مع أحداث الفوترة من جهة الخادم (مثل عمليات التجديد أو الإلغاء).
- يمكنك تخزين مصدر وحيد للحقيقة في Cloud Firestore مرتبط بكل مستخدم تمت مصادقته.
- لا يمكن للمستخدمين فتح المزايا المدفوعة من خلال التلاعب بساعة الجهاز.
إنشاء مشروع Firebase
- افتح وحدة تحكُّم Firebase وأنشئ مشروعًا جديدًا في Firebase (على سبيل المثال، Dash Clicker).
- انتقِل إلى Build > Authentication (إنشاء > المصادقة)، وانقر على Get started (البدء)، وافتح علامة التبويب Sign-in method (طريقة تسجيل الدخول)، وفعِّل موفِّر خدمة تسجيل الدخول من Google.

- انتقِل إلى إنشاء > قاعدة بيانات Firestore وأنشئ قاعدة بيانات.

- افتح علامة التبويب القواعد في Cloud Firestore وانشر قواعد الأمان التالية ليتمكّن المستخدمون الذين تمت مصادقتهم من قراءة مستندات الشراء الخاصة بهم فقط:
rules_version = '2';
service cloud.firestore {
match /databases/{database}/documents {
match /purchases/{purchaseId} {
allow read: if request.auth != null && request.auth.uid == resource.data.userId
}
}
}
إعداد Firebase for Flutter
اتّبِع دليل إعداد FlutterFire لتثبيت FlutterFire CLI، ثم شغِّل flutterfire configure داخل app/:
cd app
flutterfire configure
- اختَر مشروع Firebase الذي أنشأته.
- فعِّل android وios.
- أكِّد اختيارك نعم عندما يُطلب منك إلغاء
lib/firebase_options.dart.
إعداد Firebase لنظام التشغيل Android: شهادة SHA-1 لتصحيح الأخطاء
تتطلّب ميزة "تسجيل الدخول باستخدام حساب Google" على Android تسجيل بصمة SHA-1 ملف تخزين مفاتيح تصحيح الأخطاء في وحدة تحكُّم Firebase:
- في وحدة تحكُّم Firebase، افتح نظرة عامة على المشروع > إعدادات المشروع > الإعدادات العامة، وانتقِل للأسفل إلى تطبيقاتك، واختَر تطبيق Android:

- أنشِئ تقرير توقيع من
app/android/:cd app/android ./gradlew :app:signingReport - ابحث عن الملف المرجعي
SHA1ضمنVariant: debugوConfig: debug، وأضِفه إلى تطبيق Android في وحدة تحكُّم Firebase، ثم أعِد تشغيلflutterfire configureفيapp/لكي يتضمّنgoogle-services.jsonوlib/firebase_options.dartإعدادات عميل OAuth المحدَّثة.
إعداد Firebase لنظام التشغيل iOS: ضبط مخطّطات عناوين URL
لإتاحة ميزة "تسجيل الدخول باستخدام حساب Google" على أجهزة iOS، يجب أن يتضمّن "app/ios/Runner/Info.plist" السمة REVERSED_CLIENT_ID من "app/ios/Runner/GoogleService-Info.plist" داخل "CFBundleURLTypes" (يُرجى الاطّلاع على مستندات دمج "google_sign_in" في أجهزة iOS).
يمكنك أن تطلب من Antigravity نسخ REVERSED_CLIENT_ID وCLIENT_ID من app/ios/Runner/GoogleService-Info.plist إلى app/ios/Runner/Info.plist:
Read `CLIENT_ID` and `REVERSED_CLIENT_ID` from `app/ios/Runner/GoogleService-Info.plist` and update `GIDClientID` and `CFBundleURLTypes` (`CFBundleURLSchemes`) in `app/ios/Runner/Info.plist` with those values.
في app/ios/Runner/Info.plist، يظهر إدخال CFBundleURLTypes على النحو التالي:
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleTypeRole</key>
<string>Editor</string>
<key>CFBundleURLSchemes</key>
<array>
<string>com.googleusercontent.apps.YOUR_REVERSED_CLIENT_ID</string>
</array>
</dict>
</array>
7. الاستماع إلى معلومات حول عمليات الشراء
في هذه الخطوة، عليك إعداد تطبيق Flutter للاستماع إلى تحديثات عمليات الشراء في المتجر فور تشغيل التطبيق، والحفاظ على إمكانية اختبار شجرة التطبيقات المصغّرة من خلال تقديم برنامج تضمين IAPConnection قابل للتجاوز.
اطلب من Antigravity الاستماع إلى تحديثات الشراء
أرسِل الطلب التالي في Antigravity:
Update `app/lib/main.dart` to define an `IAPConnection` class with a static `InAppPurchase? _instance` and a static getter and setter for `instance` (defaulting to `InAppPurchase.instance`), and set `lazy: false` on `ChangeNotifierProvider<DashPurchases>`. Update `DashPurchases` in `app/lib/logic/dash_purchases.dart` to set `storeState = StoreState.notAvailable`, hold `final iapConnection = IAPConnection.instance` and `late StreamSubscription<List<PurchaseDetails>> _subscription`, subscribe to `iapConnection.purchaseStream.listen(_onPurchaseUpdate, onDone: _updateStreamOnDone, onError: _updateStreamOnError)` in the constructor, cancel `_subscription` in `dispose()`, and add `_onPurchaseUpdate`, `_updateStreamOnDone`, and `_updateStreamOnError` methods. Finally, update `app/test/widget_test.dart` to define `TestIAPConnection implements InAppPurchase` and set `IAPConnection.instance = TestIAPConnection()` before pumping `MyApp`.
فهم الرمز البرمجي الذي تم إنشاؤه
Eager provider initialization and IAPConnection in app/lib/main.dart
By default, Provider creates its value lazily when a widget first reads it. بما أنّ معاملات المتجر المعلَّقة يمكن أن تصل إلى purchaseStream فور بدء التشغيل، يضبط ChangeNotifierProvider lazy: false. بالإضافة إلى ذلك، يوفّر IAPConnection نقطة ربط ثابتة لكي تتمكّن اختبارات التطبيقات المصغّرة من إدخال تنفيذ InAppPurchase مزيّف:
class IAPConnection {
static InAppPurchase? _instance;
static set instance(InAppPurchase value) {
_instance = value;
}
static InAppPurchase get instance {
_instance ??= InAppPurchase.instance;
return _instance!;
}
}
ChangeNotifierProvider<DashPurchases>(
create: (context) => DashPurchases(context.read<DashCounter>()),
lazy: false,
),
الاشتراك في "purchaseStream" في "app/lib/logic/dash_purchases.dart"
في DashPurchases، يشترك المُنشئ في iapConnection.purchaseStream ويلغي dispose() الاشتراك في _subscription:
final iapConnection = IAPConnection.instance;
DashPurchases(this.counter) {
final purchaseUpdated = iapConnection.purchaseStream;
_subscription = purchaseUpdated.listen(
_onPurchaseUpdate,
onDone: _updateStreamOnDone,
onError: _updateStreamOnError,
);
}
@override
void dispose() {
_subscription.cancel();
super.dispose();
}
تشغيل التطبيق واختباره
شغِّل الحزمة الاختبارية للتطبيق المصغّر في app/ للتأكّد من أنّ TestIAPConnection يحاكي الاتصال بالمتجر بشكل صحيح:
cd app
flutter test
8. إجراء عمليات شراء
في هذه الخطوة، يمكنك استبدال المنتجات الوهمية المضمّنة في الرمز بمنتجات المتجر المباشرة التي يتم جلبها باستخدام queryProductDetails، وبدء عمليات الشراء عندما ينقر المستخدم على منتج، وإكمال المعاملات عند وصول التحديثات على purchaseStream.
اطلب من Antigravity تحميل عمليات الشراء وإجرائها
أرسِل الطلب التالي في Antigravity:
Update `PurchasableProduct` in `app/lib/model/purchasable_product.dart` to wrap a `ProductDetails productDetails` from `package:in_app_purchase/in_app_purchase.dart`, exposing `id`, `title`, `description`, and `price` getters from `productDetails` and initializing `status = ProductStatus.purchasable`. Then update `DashPurchases` in `app/lib/logic/dash_purchases.dart` to initialize `storeState = StoreState.loading`, `products = []`, and `bool _beautifiedDashUpgrade = false` (backing `beautifiedDash`), call `loadPurchases()` in the constructor to check `iapConnection.isAvailable()` and query `{storeKeyConsumable, storeKeySubscription, storeKeyUpgrade}` with `iapConnection.queryProductDetails(ids)`, implement `buy(PurchasableProduct product)` using `PurchaseParam` to call `iapConnection.buyConsumable` for `storeKeyConsumable` and `iapConnection.buyNonConsumable` for `storeKeySubscription` and `storeKeyUpgrade`, and implement `_onPurchaseUpdate` and `_handlePurchase(PurchaseDetails purchaseDetails)` to apply `PurchaseStatus.purchased` rewards (`counter.applyPaidMultiplier()`, `counter.addBoughtDashes(2000)`, `_beautifiedDashUpgrade = true`) and call `iapConnection.completePurchase(purchaseDetails)` when `purchaseDetails.pendingCompletePurchase` is true.
فهم الرمز البرمجي الذي تم إنشاؤه
جارٍ تغليف ProductDetails في app/lib/model/purchasable_product.dart
PurchasableProduct wraps the ProductDetails returned by the store while tracking local UI ProductStatus (purchasable, purchased, or pending):
class PurchasableProduct {
String get id => productDetails.id;
String get title => productDetails.title;
String get description => productDetails.description;
String get price => productDetails.price;
ProductStatus status;
ProductDetails productDetails;
PurchasableProduct(this.productDetails) : status = ProductStatus.purchasable;
}
جارٍ البحث عن منتجات في app/lib/logic/dash_purchases.dart
يتحقّق loadPurchases() أولاً من إمكانية الوصول إلى المتجر الأساسي باستخدام iapConnection.isAvailable()، ثم يرسل طلبات بحث عن معرّفات المنتجات الثلاثة المحدّدة في app/lib/constants.dart:
Future<void> loadPurchases() async {
final available = await iapConnection.isAvailable();
if (!available) {
storeState = StoreState.notAvailable;
notifyListeners();
return;
}
const ids = <String>{
storeKeyConsumable,
storeKeySubscription,
storeKeyUpgrade,
};
final response = await iapConnection.queryProductDetails(ids);
products = response.productDetails
.map((e) => PurchasableProduct(e))
.toList();
storeState = StoreState.available;
notifyListeners();
}
بدء عمليات الشراء وإكمالها
عندما ينقر المستخدم على منتج في PurchasePage، ينشئ buy() PurchaseParam ويرسل المنتجات الاستهلاكية إلى buyConsumable والترقيات أو الاشتراكات التي يتم تحصيل سعرها مرة واحدة إلى buyNonConsumable:
Future<void> buy(PurchasableProduct product) async {
final purchaseParam = PurchaseParam(productDetails: product.productDetails);
switch (product.id) {
case storeKeyConsumable:
await iapConnection.buyConsumable(purchaseParam: purchaseParam);
case storeKeySubscription:
case storeKeyUpgrade:
await iapConnection.buyNonConsumable(purchaseParam: purchaseParam);
default:
throw ArgumentError.value(
product.productDetails,
'${product.id} is not a known product',
);
}
}
عندما يُصدر المتجر عناصر PurchaseDetails معدَّلة في purchaseStream، يمنح _handlePurchase المكافأة المقابلة ويقرّ بالإكمال من خلال طلب completePurchase:
Future<void> _handlePurchase(PurchaseDetails purchaseDetails) async {
if (purchaseDetails.status == PurchaseStatus.purchased) {
switch (purchaseDetails.productID) {
case storeKeySubscription:
counter.applyPaidMultiplier();
case storeKeyConsumable:
counter.addBoughtDashes(2000);
case storeKeyUpgrade:
_beautifiedDashUpgrade = true;
}
}
if (purchaseDetails.pendingCompletePurchase) {
await iapConnection.completePurchase(purchaseDetails);
}
}
تشغيل التطبيق واختباره
شغِّل flutter test في app/ وافتح التطبيق على جهازك الاختباري الذي تم ضبطه. عندما تكون منتجات متجرك نشطة، تعرضها علامة التبويب شراء جاهزة للشراء:

9. إعداد الخلفية
قبل التحقّق من عمليات الشراء وتتبُّعها على خادم، عليك إنشاء خدمة الخلفية Dart في dart-backend/ إلى جانب app/ وضبط بيانات الاعتماد لكل من Firebase وGoogle Play ومتجر التطبيقات.
اطلب من Antigravity إنشاء هيكل خلفية Dart
في لوحة الدردشة لوكيل Antigravity، أرسِل الطلب التالي لإنشاء مشروع dart-backend/:
Create a Dart shelf server project in `dart-backend/` with package name `firebase_backend_dart` (`dart create -t server-shelf`). Add `googleapis: ^16.0.0`, `googleapis_auth`, `http`, and `app_store_server_sdk` to `dependencies`, and `test` to `dev_dependencies` (configuring `deprecated_member_use: ignore` in `dart-backend/analysis_options.yaml`). Create:
- `dart-backend/lib/constants.dart` defining `androidPackageId`, `appStoreIssuerId`, `appStoreKeyId`, `appStoreSharedSecret`, `bundleId`, `googleCloudProjectId`, and `googlePlayPubsubBillingTopic = 'play_billing'`
- `dart-backend/lib/helpers.dart` with `serveHandler(Handler handler)`, `listenPort()`, and `terminateRequestFuture()` listening to `SIGINT` and `SIGTERM`
- `dart-backend/lib/products.dart` defining `ProductData(this.productId, this.type)`, `enum ProductType { subscription, nonSubscription }`, and `productDataMap` for `'dash_consumable_2k'`, `'dash_upgrade_3d'`, and `'dash_subscription_doubler'`
- `dart-backend/lib/iap_repository.dart` defining `enum IAPSource { googleplay, appstore }`, `abstract class Purchase`, `NonSubscriptionPurchase`, `SubscriptionPurchase`, and `IapRepository(this.api, this.projectId)` using `package:googleapis/firestore/v1.dart` (`createOrUpdatePurchase`, `updatePurchase`, and `getPurchases`)
- `dart-backend/bin/server.dart` starting an empty `Router()` with `await serveHandler(router.call)`.
فهم الرمز البرمجي الذي تم إنشاؤه
-
dart-backend/bin/server.dartيبدأRoutershelf_routerويخدم طلبات HTTP على المنفذ8080باستخدامserveHandlerفيdart-backend/lib/helpers.dart. - يربط
dart-backend/lib/products.dartكل معرّف منتج (dash_consumable_2kوdash_upgrade_3dوdash_subscription_doubler) بـProductType(nonSubscriptionأوsubscription). - يغلف
dart-backend/lib/iap_repository.dartقراءة وكتابة مستنداتNonSubscriptionPurchaseوSubscriptionPurchaseفي مجموعةpurchasesمن Cloud Firestore باستخدامFirestoreApi.
يمكنك اختبار بدء تشغيل الخادم محليًا من خلال تشغيل:
cd dart-backend
dart run ./bin/server.dart
إعداد إمكانية الوصول إلى Firebase
للسماح لـ "dart-backend/" بكتابة عمليات الشراء التي تم التحقّق منها في Cloud Firestore، يجب إنشاء مفتاح حساب خدمة:
- في وحدة تحكُّم Firebase، افتح إعدادات المشروع > حسابات الخدمة وانقر على إنشاء مفتاح خاص جديد.

- احفظ ملف JSON الذي تم تنزيله باسم
dart-backend/assets/service-account-firebase.json.
إعداد إمكانية الوصول إلى Google Play
للسماح لـ "dart-backend/" بالتحقّق من عمليات الشراء على Android باستخدام Google Play Android Developer API، يُرجى اتّباع الخطوات التالية:
- افتح صفحة Google Play Android Developer API في Google Cloud Console وفعِّل واجهة برمجة التطبيقات.

- انتقِل إلى صفحة حسابات خدمة Google Cloud وانقر على + إنشاء حساب خدمة.

- أدخِل اسم حساب خدمة وانقر على إنشاء ومتابعة.

- امنح دور مشترك Pub/Sub وانقر على تم.

- افتح قائمة الإجراءات لحساب الخدمة الذي تم إنشاؤه حديثًا واختَر إدارة المفاتيح.

- انقر على إضافة مفتاح > إنشاء مفتاح جديد، واختَر JSON، ثم نزِّل المفتاح:


- احفظ الملف الذي تم تنزيله باسم
dart-backend/assets/service-account-google-play.json. - افتح المستخدمون والأذونات في Google Play Console، وانقر على دعوة مستخدمين جُدد، ثم أدخِل عنوان البريد الإلكتروني لحساب الخدمة:


- امنح إذنَي عرض البيانات المالية وإدارة الطلبات والاشتراكات لتطبيقك، ثم انقر على دعوة مستخدم.

إعداد إمكانية الوصول إلى Apple App Store
للتحقّق من إيصالات متجر التطبيقات في الخلفية، أنشئ مفتاحًا سريًا مشتركًا خاصًا بالتطبيق:
- افتح App Store Connect، واختَر التطبيقات (Apps)، ثم اختَر تطبيقك.
- في الشريط الجانبي، انتقِل إلى عام > معلومات التطبيق.
- ضمن App-Specific Shared Secret (رمز سري مشترك خاص بالتطبيق)، انقر على Manage (إدارة)، وأنشئ رمزًا سريًا مشتركًا جديدًا، ثم انسخه:


تعديل "dart-backend/lib/constants.dart"
تأكَّد من ضبط الثوابت التالية في dart-backend/lib/constants.dart:
-
androidPackageId: جهاز AndroidapplicationId(مثلcom.example.dashclicker). appStoreSharedSecret: الرمز السري المشترَك في App Store Connect-
bundleId: معرّف حزمة iOS (مثلcom.example.dashclicker)
10. التحقّق من عمليات الشراء
عندما يُكمل المستخدم عملية شراء على iOS أو Android، يُصدر المتجر رمزًا مميزًا لإثبات ملكية النطاق (PurchaseDetails.verificationData.serverVerificationData). وبدلاً من الوثوق بجهاز العميل مباشرةً، يرسل تطبيق Flutter هذا الرمز المميز إلى dart-backend/، الذي يتحقّق من الرمز المميز من خلال Google Play أو App Store ويسجّل عملية الشراء في Cloud Firestore.

اطلب من Antigravity التحقّق من عمليات الشراء من جهة العميل والخلفية
أرسِل الطلب التالي في Antigravity لربط تطبيق Flutter بعملية التحقّق من الخلفية في Dart:
1. In `app/`:
- Update `PurchasePage` in `app/lib/pages/purchase_page.dart` to watch `FirebaseNotifier` and return `_PurchasesLoading()` when `state == FirebaseState.loading`, `_PurchasesNotAvailable()` when `state == FirebaseState.notAvailable`, and `const LoginPage()` when `!firebaseNotifier.loggedIn`.
- Add `User? get user => FirebaseAuth.instance.currentUser;` to `FirebaseNotifier` in `app/lib/logic/firebase_notifier.dart`.
- Update `DashPurchases` in `app/lib/logic/dash_purchases.dart` (and its provider in `app/lib/main.dart`) to accept `this.firebaseNotifier`, implement `_verifyPurchase(PurchaseDetails purchaseDetails)` that sends an HTTP `POST` request to `Uri.http('$serverIp:8080', '/verifypurchase')` with JSON body `{'source': purchaseDetails.verificationData.source, 'productId': purchaseDetails.productID, 'verificationData': purchaseDetails.verificationData.serverVerificationData, 'userId': firebaseNotifier.user?.uid}`, and update `_handlePurchase` so purchase rewards are only applied when `await _verifyPurchase(purchaseDetails)` returns `true`.
2. In `dart-backend/`:
- Create `dart-backend/lib/purchase_handler.dart` with `abstract class PurchaseHandler` defining `handleNonSubscription`, `handleSubscription`, and `verifyPurchase` switching on `productData.type`.
- Create `dart-backend/lib/google_play_purchase_handler.dart` with `GooglePlayPurchaseHandler extends PurchaseHandler` that verifies one-time purchases using `androidPublisher.purchases.products.get` and subscriptions using `androidPublisher.purchases.subscriptions.get`, parses order IDs with `extractOrderId(String orderId)` (stripping `..` renewal suffixes), maps statuses with `_nonSubscriptionStatusFrom` and `_subscriptionStatusFrom`, and saves purchases to `iapRepository`.
- Create `dart-backend/lib/app_store_purchase_handler.dart` with `AppStorePurchaseHandler extends PurchaseHandler` that validates receipts with `ITunesApi(ITunesHttpClient(ITunesEnvironment.sandbox(), loggingEnabled: true)).verifyReceipt` and saves `NonSubscriptionPurchase` and `SubscriptionPurchase` records to `iapRepository`.
- Update `dart-backend/bin/server.dart` to initialize `AndroidPublisherApi` and `FirestoreApi` from the service account JSON files in `_createPurchaseHandlers()`, register a `POST /verifypurchase` route, and extract request fields in `getPurchaseData(dynamic payload)` using Dart 3 map pattern matching.
فهم الرمز البرمجي الذي تم إنشاؤه
حظر عمليات الشراء التي لا تتم مصادقتها واستدعاء /verifypurchase
في app/lib/pages/purchase_page.dart، يتحقّق PurchasePage من FirebaseNotifier ويعرض LoginPage إلى أن يسجّل المستخدم الدخول:
var firebaseNotifier = context.watch<FirebaseNotifier>();
if (firebaseNotifier.state == FirebaseState.loading) {
return _PurchasesLoading();
} else if (firebaseNotifier.state == FirebaseState.notAvailable) {
return _PurchasesNotAvailable();
}
if (!firebaseNotifier.loggedIn) {
return const LoginPage();
}
في app/lib/logic/dash_purchases.dart، ينشر _verifyPurchase مصدر المتجر (google_play أو app_store) وproductID وserverVerificationData وuserId الذي تم تسجيل الدخول إليه في الخلفية في Dart قبل أن يمنح _handlePurchase المكافأة داخل التطبيق:
Future<bool> _verifyPurchase(PurchaseDetails purchaseDetails) async {
final url = Uri.http('$serverIp:8080', '/verifypurchase');
const headers = {
'Content-type': 'application/json',
'Accept': 'application/json',
};
final response = await http.post(
url,
body: jsonEncode({
'source': purchaseDetails.verificationData.source,
'productId': purchaseDetails.productID,
'verificationData':
purchaseDetails.verificationData.serverVerificationData,
'userId': firebaseNotifier.user?.uid,
}),
headers: headers,
);
if (response.statusCode == 200) {
return true;
} else {
return false;
}
}
التوجيه ومطابقة الأنماط في Dart 3 في dart-backend/bin/server.dart
على الخادم، يفكّ POST /verifypurchase ترميز نص طلب JSON باستخدام getPurchaseData من خلال نمط خريطة Dart 3 ونوع القيمة التي تم إرجاعها للسجلّ، ثم يفوّض عملية التحقّق إلى معالج المتجر المطابق:
router.post('/verifypurchase', (Request request) async {
final dynamic payload = json.decode(await request.readAsString());
final (:userId, :source, :productData, :token) = getPurchaseData(payload);
final result = await purchaseHandlers[source]!.verifyPurchase(
userId: userId,
productData: productData,
token: token,
);
if (result) {
return Response.ok('all good!');
} else {
return Response.internalServerError();
}
});
({String userId, String source, ProductData productData, String token})
getPurchaseData(dynamic payload) {
if (payload case {
'userId': String userId,
'source': String source,
'productId': String productId,
'verificationData': String token,
}) {
return (
userId: userId,
source: source,
productData: productDataMap[productId]!,
token: token,
);
} else {
throw const FormatException('Unexpected JSON');
}
}
التحقّق من إيصالات Google Play وApp Store
- في
dart-backend/lib/google_play_purchase_handler.dart، يرسلGooglePlayPurchaseHandlerطلبات بحث إلىandroidPublisher.purchases.products.getللمنتجات المدفوعة لمرة واحدة وإلىandroidPublisher.purchases.subscriptions.getللاشتراكات، ويزيل لاحقات التجديد..#من معرّفات طلبات الاشتراك باستخدامextractOrderId، ويكتبNonSubscriptionPurchaseأوSubscriptionPurchaseالناتجَين في Cloud Firestore باستخدامiapRepository. - في
dart-backend/lib/app_store_purchase_handler.dart، يتصلAppStorePurchaseHandlerبـ_iTunesAPI.verifyReceiptباستخدام حزمةapp_store_server_sdkويحفظ كل إيصال تم التحقّق منه فيresponse.latestReceiptInfoفي Cloud Firestore.
تشغيل الخلفية واختبارها
ابدأ تشغيل خادم الخلفية من dart-backend/:
cd dart-backend
dart run bin/server.dart
11. تتبُّع عمليات الشراء
يمكن تجديد الاشتراكات أو انتهاء صلاحيتها أو إلغاؤها خارج تطبيقك. في هذه الخطوة، يمكنك ضبط الخلفية لاستطلاع تحديثات الفوترة في متجر التطبيقات من Google Cloud Pub/Sub وواجهة App Store Server API، وتحديث عميل Flutter لمزامنة أذونات المستخدم النشطة بشكل تفاعلي من Cloud Firestore باستخدام IAPRepo.
ضبط إعدادات Cloud Pub/Sub ومفاتيح App Store Server API
إعداد Google Play Cloud Pub/Sub
- اضبط
googleCloudProjectIdفيdart-backend/lib/constants.dartعلى رقم تعريف مشروعك على Google Cloud وFirebase. - افتح صفحة مواضيع Cloud Pub/Sub في Google Cloud Console، وتأكَّد من اختيار مشروعك، ثم انقر على + إنشاء موضوع.

- اضبط رقم تعريف الموضوع على
play_billing(مطابقةgooglePlayPubsubBillingTopicفيdart-backend/lib/constants.dart، ما يؤدي إلى إنشاء اشتراك تلقائيplay_billing-sub)، ثم انقر على إنشاء.
- افتح قائمة الخيارات الإضافية في موضوع "
play_billing" وانقر على عرض الأذونات.
- انقر على إضافة مستخدم رئيسي، وأدخِل
google-play-developer-notifications@system.gserviceaccount.com، ثم امنحه دور ناشر Pub/Sub، وانقر على حفظ.
- انسخ اسم الموضوع بالكامل، وافتح تطبيقك في Google Play Console، وانتقِل إلى تحقيق الربح مع Google Play > إعداد تحقيق الربح، وألصِق اسم الموضوع، ثم انقر على حفظ التغييرات.

إعداد مفتاح App Store Server API
- سجِّل الدخول إلى App Store Connect واختَر المستخدمون وإمكانية الوصول (Users and Access).
- انتقِل إلى عمليات الدمج > المفاتيح > الشراء داخل التطبيق وانقر على الزر + لإنشاء مفتاح جديد (على سبيل المثال،
Codelab key). - نزِّل ملف مفتاح
.p8واحفظه باسمdart-backend/assets/SubscriptionKey.p8. - انسخ رقم تعريف المفتاح ورقم تعريف جهة الإصدار إلى
appStoreKeyIdوappStoreIssuerIdفيdart-backend/lib/constants.dart.

طلب من Antigravity استطلاع أحداث المتجر ومزامنة حالة العميل
أرسِل الطلب التالي في Antigravity:
1. In `dart-backend/`:
- Update `GooglePlayPurchaseHandler` in `dart-backend/lib/google_play_purchase_handler.dart` to accept `pubsub.PubsubApi pubsubApi` from `package:googleapis/pubsub/v1.dart`, start a 10-second `Timer.periodic` calling `_pullMessageFromPubSub()`, decode base64 Pub/Sub messages in `_processMessage(String data64, String? ackId)` (handling `testNotification`, `subscriptionNotification`, and `oneTimeProductNotification`), and acknowledge processed messages in `_ackMessage(String id)`.
- Update `AppStorePurchaseHandler` in `dart-backend/lib/app_store_purchase_handler.dart` to accept `AppStoreServerAPI appStoreServerAPI`, start a 10-second `Timer.periodic` calling `_pullStatus()`, query `appStoreServerAPI.getAllSubscriptionStatuses(purchase.orderId)` for active App Store subscriptions in `iapRepository`, and update their expiration date and `SubscriptionStatus` in Firestore.
- Update `dart-backend/bin/server.dart` to add `pubsub.PubsubApi.cloudPlatformScope` to the Google Play client scopes, construct `PubsubApi` and `AppStoreServerAPI` (reading `assets/SubscriptionKey.p8` and caching JWT tokens in `assets/appstore.token`), and pass them to `GooglePlayPurchaseHandler` and `AppStorePurchaseHandler`.
- Create unit tests in `dart-backend/test/firebase_backend_dart_test.dart` verifying `extractOrderId` (with and without a `..0` suffix) and `getPurchaseData` (valid and invalid payloads).
2. In `app/`:
- Update `DashPurchases` in `app/lib/logic/dash_purchases.dart` (and its provider in `app/lib/main.dart`) to accept `this.iapRepo` (`IAPRepo`), register `iapRepo.addListener(purchasesUpdate)` in the constructor and `iapRepo.removeListener(purchasesUpdate)` in `dispose()`, and implement `purchasesUpdate()` and `_updateStatus(PurchasableProduct product, ProductStatus status)` (setting `product.status = status` when `product.status != status`) so `iapRepo.hasActiveSubscription` applies or removes the paid counter multiplier and `iapRepo.hasUpgrade` updates `_beautifiedDashUpgrade` and product statuses.
فهم الرمز البرمجي الذي تم إنشاؤه
استطلاع Google Play Pub/Sub وواجهة App Store Server API في الخلفية
في dart-backend/lib/google_play_purchase_handler.dart، يستطلع _pullMessageFromPubSub اشتراك projects/$googleCloudProjectId/subscriptions/$googlePlayPubsubBillingTopic-sub كل 10 ثوانٍ، ويفك ترميز كل حمولة إشعار base64، ويعيد تشغيل handleSubscription أو handleNonSubscription لإعادة تحميل Firestore، ويقرّ باستلام الرسالة باستخدام _ackMessage:
Future<void> _pullMessageFromPubSub() async {
print('Polling Google Play messages');
final request = pubsub.PullRequest(maxMessages: 1000);
final topicName =
'projects/$googleCloudProjectId/subscriptions/$googlePlayPubsubBillingTopic-sub';
final pullResponse = await pubsubApi.projects.subscriptions.pull(
request,
topicName,
);
final messages = pullResponse.receivedMessages ?? [];
for (final message in messages) {
final data64 = message.message?.data;
if (data64 != null) {
await _processMessage(data64, message.ackId);
}
}
}
وبالمثل، في dart-backend/lib/app_store_purchase_handler.dart، يرسل _pullStatus طلبات بحث إلى appStoreServerAPI.getAllSubscriptionStatuses(purchase.orderId) كل 10 ثوانٍ ويعدّل expiryDate وSubscriptionStatus (active أو expired) لكل اشتراك في Cloud Firestore.
مزامنة عمليات الشراء في Firestore على الجهاز
في app/lib/repo/iap_repo.dart، يستمع IAPRepo إلى مستندات purchases الخاصة بالمستخدم الذي تمت مصادقته في Cloud Firestore في الوقت الفعلي ويحسب hasActiveSubscription وhasUpgrade:
var purchaseStream = _firestore
.collection('purchases')
.where('userId', isEqualTo: user.uid)
.snapshots();
_purchaseSubscription = purchaseStream.listen((snapshot) {
purchases = snapshot.docs.map((document) {
var data = document.data();
return PastPurchase.fromJson(data);
}).toList();
hasActiveSubscription = purchases.any(
(element) =>
element.productId == storeKeySubscription &&
element.status != Status.expired,
);
hasUpgrade = purchases.any(
(element) => element.productId == storeKeyUpgrade,
);
notifyListeners();
});
عندما يُرسل IAPRepo إشعارًا إلى المستمعين، يفعّل DashPurchases.purchasesUpdate() في app/lib/logic/dash_purchases.dart مضاعِف النقرات بمقدار 10 مرات أو يوقفه، ويبدّل _beautifiedDashUpgrade، ويعدّل حالات المنتجات المعروضة على PurchasePage:
void purchasesUpdate() {
var subscriptions = <PurchasableProduct>[];
var upgrades = <PurchasableProduct>[];
if (products.isNotEmpty) {
subscriptions = products
.where((element) => element.productDetails.id == storeKeySubscription)
.toList();
upgrades = products
.where((element) => element.productDetails.id == storeKeyUpgrade)
.toList();
}
if (iapRepo.hasActiveSubscription) {
counter.applyPaidMultiplier();
for (var element in subscriptions) {
_updateStatus(element, ProductStatus.purchased);
}
} else {
counter.removePaidMultiplier();
for (var element in subscriptions) {
_updateStatus(element, ProductStatus.purchasable);
}
}
if (iapRepo.hasUpgrade != _beautifiedDashUpgrade) {
_beautifiedDashUpgrade = iapRepo.hasUpgrade;
for (var element in upgrades) {
_updateStatus(
element,
_beautifiedDashUpgrade
? ProductStatus.purchased
: ProductStatus.purchasable,
);
}
notifyListeners();
}
}
void _updateStatus(PurchasableProduct product, ProductStatus status) {
if (product.status != status) {
product.status = status;
notifyListeners();
}
}
تشغيل التطبيق والخلفية واختبارهما
شغِّل اختبارات الوحدات والتطبيقات المصغّرة في كلا المشروعَين للتأكّد من أنّ كل شيء يتم تحليله واجتيازه بشكل صحيح:
cd dart-backend
dart test
cd ../app
flutter test
12. تهانينا
تهانينا! لقد تعاونت مع Google Antigravity لإنشاء عملية تكامل كاملة لعمليات الشراء داخل التطبيق في Flutter باستخدام واجهة خلفية للتحقّق من Dart.
ما أنشأته
- تم إعداد المنتجات الاستهلاكية (
dash_consumable_2k) وغير الاستهلاكية (dash_upgrade_3d) والاشتراكات التي يتم تجديدها تلقائيًا (dash_subscription_doubler) في App Store Connect وGoogle Play Console. - تم ربط تطبيق Dash Clicker Flutter (
app/) بالمكوّن الإضافيin_app_purchase، والاستعلام عن تفاصيل المنتج والاستماع إلىpurchaseStream. - تم إنشاء خلفية
shelfبلغة Dart (dart-backend/) تتحقّق من الرموز المميّزة للشراء باستخدام Google Play Android Developer API ومتجر التطبيقات، وتستطلع تحديثات الفوترة باستخدام Cloud Pub/Sub وApp Store Server API، وتحتفظ بحالة الشراء في Cloud Firestore. - مزامنة أذونات الشراء التي تم التحقّق منها مع عميل Flutter في الوقت الفعلي باستخدام
IAPRepo
الخطوات التالية
- أضِف البرمجيات الوسيطة للتحقّق من الرمز المميّز لرقم تعريف مصادقة Firebase إلى
POST /verifypurchaseفيdart-backend/bin/server.dart. - انشر
dart-backend/على Cloud Run واضبط إعدادات الردّ التلقائي على الويب للإشعارات الفورية في Google Cloud Pub/Sub و"إشعارات خادم متجر التطبيقات".






