إضافة عمليات الشراء داخل التطبيق إلى تطبيق Flutter

1. مقدمة

لإضافة ميزة الشراء داخل التطبيق إلى تطبيق Flutter، يجب ضبط Apple App Store و"متجر Google Play"، والتحقّق من رموز الشراء المميّزة على واجهة خلفية موثوقة، ومنح أذونات مثل العملات القابلة للاستهلاك أو الترقيات لمرة واحدة أو مزايا الاشتراك المتكرّر.

في هذا الدرس التطبيقي حول الترميز، ستتعاون مع Google Antigravity لإنشاء Dash Clicker، وهي لعبة نقر على الأجهزة الجوّالة تستخدم تميمة Dash كعملة، وربطها بخدمة خلفية shelf بلغة Dart وCloud Firestore للتحقّق من ثلاثة أنواع من عمليات الشراء داخل التطبيق وتتبُّعها:

  1. منتج استهلاكي (dash_consumable_2k): عملية شراء قابلة للتكرار تمنح اللاعب على الفور 2,000 نقطة من نقاط Dash ويمكن شراؤها عدة مرات.
  2. منتج غير استهلاكي (dash_upgrade_3d): ترقية دائمة لمرة واحدة تحوّل تميمة Dash الكلاسيكية إلى تميمة Dash ثلاثية الأبعاد حديثة إلى الأبد.
  3. الاشتراك (dash_subscription_doubler): اشتراك يتم تجديده تلقائيًا ويضاعف النقرات التي يتم إنشاؤها بشكل سلبي طالما أنّ الاشتراك نشط.

الشاشة الرئيسية للعبة Dash Clicker تعرض تميمة Dash الكلاسيكية وعداد النقر

شاشة الشراء في لعبة Dash Clicker تعرض المنتجات المتاحة داخل التطبيق وعمليات الشراء السابقة

الشاشة الرئيسية للعبة Dash Clicker بعد شراء ترقية 3D Dash

ما ستنشئه

  • تطبيق Flutter للأجهزة الجوّالة (app/) مصمَّم باستخدام material_ui وcupertino_ui يطلب منتجات المتجر ويبدأ عمليات الشراء ويتفاعل مع أحداث الشراء في الوقت الفعلي.
  • خادم خلفي من Dart shelf (dart-backend/) يتحقّق من إيصالات الشراء من خلال Google Play وApp Store، ويستطلع أحداث الفوترة في المتجر، ويسجّل حالات الشراء في Cloud Firestore.

رحلتك نحو التعلم

يساعدك هذا الدرس التطبيقي حول الترميز في إنشاء مسار الشراء داخل التطبيق وربطه بالكامل خطوة بخطوة:

  1. إعداد بيئة التطوير: ثبِّت Flutter وGoogle Antigravity، واطلب من Antigravity إنشاء مشروع Dash Clicker الأوّلي (app/)، واضبط معرّف حزمة iOS وapplicationId لنظام Android.
  2. تثبيت المكوّن الإضافي: اطلب من Antigravity إضافة in_app_purchase وin_app_purchase_platform_interface إلى app/.
  3. إعداد App Store: سجِّل معرّف التطبيق، وأنشئ حساب اختبار في وضع الحماية، واضبط المنتجات الثلاثة في App Store Connect.
  4. إعداد "متجر Google Play": أنشئ تطبيقك في Google Play Console، واطلب من Antigravity إعداد توقيع ملف تخزين المفاتيح للإصدار في Gradle، وحمِّل حزمة تطبيق أولية، وأضِف مختبِري التراخيص، واضبط المنتجات.
  5. إعداد Firebase: فعِّل ميزتَي "تسجيل الدخول باستخدام حساب Google" وCloud Firestore في وحدة تحكُّم Firebase، وشغِّل flutterfire configure، واضبط الملفات المرجعية SHA-1 لنظام التشغيل Android ومخطّطات عناوين URL لنظام التشغيل iOS.
  6. الاستماع إلى تحديثات الشراء: اطلب من Antigravity إضافة برنامج تضمين IAPConnection قابل للاختبار، والاشتراك في purchaseStream، واختبار التطبيق باستخدام TestIAPConnection.
  7. إجراء عمليات الشراء: يمكنك أن تطلب من Antigravity تضمين ProductDetails في PurchasableProduct، والاستعلام عن منتجات المتجر، وتفعيل buyConsumable وbuyNonConsumable، وإكمال عمليات الشراء المعلّقة.
  8. إعداد الخلفية: اطلب من Antigravity إنشاء خادم dart-backend/ باستخدام IapRepository وضبط بيانات اعتماد حساب الخدمة.
  9. التحقّق من عمليات الشراء: اطلب من Antigravity فرض تسجيل الدخول إلى Firebase على PurchasePage، وإرسال رموز الشراء المميّزة إلى /verifypurchase، وتنفيذ GooglePlayPurchaseHandler وAppStorePurchaseHandler.
  10. تتبُّع عمليات الشراء: يمكنك توجيه 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.

في هذا الدرس التطبيقي حول الترميز، ثبِّت البرامج التالية:

  1. حزمة تطوير البرامج (SDK) من Flutter
  2. ‫Google Antigravity مع تفعيل المكوّن الإضافي الرسمي لـ Dart وFlutter (متاح في Plugin Marketplace ضمن قسم Build with Google).
  3. برنامج تجميع لنظام التشغيل المستهدَف على الأجهزة الجوّالة (Android Studio لاستهداف Android أو Xcode لاستهداف iOS)

اطلب من Antigravity إنشاء مشروع للمبتدئين

  1. افتح Google Antigravity وانتقِل إلى دليل مساحة عمل فارغ حيث تريد إنشاء كل من تطبيق Flutter (app/) وخادم Dart (dart-backend/). اختَر مسارًا لا يتطلّب أذونات مميزة وعالية المستوى أو يحتوي على مسافات، مثل مجلد في الدليل الرئيسي أو C:\src\.
  2. في لوحة محادثة وكيل 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:

فتح Runner.xcworkspace في Xcode

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

ضبط معرّف الفريق ومعرّف الحزمة في Xcode Signing & Capabilities

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

ضبط applicationId في 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)).

لوحة بيانات الصفحة الرئيسية في App Store Connect مع إبراز "الاتفاقيات والضرائب والخدمات المصرفية" (Agreements, Tax, and Banking)

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

قائمة اتفاقيات App Store Connect التي تعرض التطبيقات المجانية النشطة والتطبيقات المدفوعة الجديدة

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

قائمة اتفاقيات App Store Connect التي تعرض كلاً من التطبيقات المجانية والتطبيقات المدفوعة النشطة

تسجيل معرّف تطبيق

أنشئ معرّف تطبيق جديدًا في "بوابة مخصّصة للمطوّرين" (Developer Portal) في Apple:

  1. انتقِل إلى معرّفات مطوّري برامج Apple وانقر على الرمز + بجانب العنوان المعرّفات.قائمة معرّفات بوابة Apple Developer Portal مع تمييز زر الإضافة
  2. اختَر معرّفات التطبيقات وانقر على متابعة.شاشة "تسجيل معرّف جديد" (Register a new identifier) مع اختيار "معرّفات التطبيقات" (App IDs)
  3. اختَر تطبيق كنوع الإعلان، ثم انقر على متابعة.شاشة اختيار نوع مع تحديد "تطبيق"
  4. أدخِل وصفًا واضبط معرّف الحزمة (صريح) على معرّف الحزمة نفسه الذي ضبطته في Xcode. تأكَّد من تفعيل ميزة الشراء داخل التطبيق، ثم سجِّل المعرّف.نموذج "تسجيل معرّف تطبيق" (Register an App ID) يعرض الوصف ومعرّف الحزمة الصريح

لمزيد من التفاصيل، يُرجى الاطّلاع على مساعدة حساب المطوّر على Apple.

إنشاء تطبيق جديد ومستخدم في وضع الحماية

أنشئ تطبيقًا جديدًا في App Store Connect باستخدام معرّف الحزمة المسجَّل:

قائمة "التطبيقات" في App Store Connect تعرض خيار "تطبيق جديد"

مربّع حوار "تطبيق جديد" (New App) في App Store Connect يعرض حقول النظام الأساسي والاسم واللغة ورقم تعريف الحزمة ورمز التخزين التعريفي

لمزيد من الإرشادات حول إنشاء تطبيق وإدارة الاتفاقيات، يُرجى الاطّلاع على مركز مساعدة App Store Connect.

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

قائمة مختبِري وضع الحماية في App Store Connect

على جهاز iPhone أو iPad التجريبي، سجِّل الدخول باستخدام حساب وضع الحماية ضمن الإعدادات > المطوّر > حساب Apple في وضع الحماية (Settings > Developer > Sandbox Apple Account).

شاشة إعدادات iOS تعرض قسم "حساب Apple في وضع الحماية"

شاشة إعدادات iOS تعرض حساب Apple Sandbox تم تسجيل الدخول إليه

ضبط عمليات الشراء داخل التطبيق

بعد ذلك، اضبط العناصر الثلاثة القابلة للشراء في App Store Connect:

  • ‫dash_consumable_2k: منتج استهلاكي يمكن شراؤه بشكل متكرر، ويمنح 2,000 Dash لكل عملية شراء.
  • ‫dash_upgrade_3d: عملية شراء لترقية غير استهلاكية يمكن إجراؤها مرة واحدة فقط، وتتيح فتح شخصية التميمة "داش" الثلاثية الأبعاد.
  • dash_subscription_doubler: اشتراك يتجدّد تلقائيًا ويضاعف النقرات غير النشطة أثناء تفعيله.

الشريط الجانبي في App Store Connect مع تمييز "عمليات الشراء داخل التطبيق" و"الاشتراكات"

في قسمَي عمليات الشراء داخل التطبيق (والاشتراكات) في تطبيقك، أنشئ المنتجات الثلاثة باستخدام معرّفات المنتجات التالية بالضبط:

  1. منتج استهلاكي (dash_consumable_2k):
    • أنشئ منتجًا استهلاكيًا يحمل الاسم المرجعي dash consumable 2k ومعرّف المنتج dash_consumable_2k.إنشاء نافذة مشروطة لعملية شراء داخل التطبيق تم ضبطها على dash_consumable_2k
    • اضبط إعدادات التوفّر ليكون المنتج متاحًا في بلد مستخدم وضع الحماية أو منطقته.إعدادات توفّر الشراء داخل التطبيق
    • اضبط السعر على \$1.99 (أو ما يعادله بالعملة المحلية).تم ضبط إعدادات "جدول الأسعار" على 1.99 دولار أمريكي
    • أضِف ترجمة بالاسم المعروض "Spring is in the air" والوصف "2000 dashes fly out".صورة توضّح الاسم المعروض والوصف في صفحة "أقلمة متجر التطبيقات" (App Store Localization)
    • حمِّل لقطة شاشة للمراجعة. لا يهم محتوى الصورة في اختبار وضع الحماية، ولكن يؤدي تحميل لقطة شاشة إلى نقل المنتج إلى الحالة جاهز للإرسال، وهو أمر مطلوب لكي يجلب التطبيق المنتج من StoreKit.قسم "مراجعة المعلومات" مع صورة معاينة لمنتج تم تحميله
  2. منتج غير استهلاكي (dash_upgrade_3d):
    • أنشئ منتجًا غير استهلاكي يحمل الاسم المرجعي dash upgrade 3d ومعرّف المنتج dash_upgrade_3d.
    • اضبط "الاسم المعروض" على 3D Dash و"الوصف" على Brings your dash back to the future و"السعر" على \$0.99.
    • اضبط إعدادات التوفّر وحمِّل لقطة شاشة للمراجعة تمامًا كما فعلت مع "dash_consumable_2k".إعدادات المنتج غير الاستهلاكي لـ dash_upgrade_3d
  3. اشتراك يتجدّد تلقائيًا (dash_subscription_doubler):
    • ضمن الاشتراكات، أنشِئ مجموعة اشتراكات باسم subscriptions (يمكن للمستخدمين الاشتراك في منتج واحد فقط ضمن المجموعة نفسها في كل مرة، ويمكنهم الترقية أو الاشتراك في خطة أقلّ كلفة ضمن المجموعة).مربّع حوار "إنشاء مجموعة اشتراكات"
    • أضِف ترجمة محلية في متجر التطبيقات لمجموعة الاشتراكات.مربّع حوار "أقلمة متجر التطبيقات" لمجموعة الاشتراكات
    • داخل المجموعة، أنشئ اشتراكًا يحمل الاسم المرجعي dash subscription doubler ومعرّف المنتج dash_subscription_doubler.مربّع حوار إنشاء اشتراك لـ dash_subscription_doubler
    • اضبط مدة الاشتراك على أسبوع واحد، والاسم المعروض على Jet Engine، والوصف على Doubles your clicks، والسعر على \$0.49. اضبط إعدادات التوفّر وحمِّل لقطة شاشة للمراجعة حتى تصبح الحالة جاهز للإرسال.مدة الاشتراك وسعره وإعدادات الأقلمة

من المفترض أن تظهر منتجاتك الآن في App Store Connect بالحالة جاهز للإرسال:

قائمة "عمليات الشراء داخل التطبيق" التي تعرض dash_consumable_2k وdash_upgrade_3d كعناصر جاهزة للإرسال

قائمة الاشتراكات التي تعرض dash_subscription_doubler على أنّها جاهزة للإرسال

5- إعداد "متجر Google Play"

لاختبار عمليات الشراء داخل التطبيق على Android، تحتاج إلى حساب مطوِّر على Google Play. إذا لم يكن لديك حساب، يمكنك التسجيل لإنشاء حساب مطوِّر على Google Play.

إنشاء تطبيق جديد

أنشئ تطبيقًا جديدًا في Google Play Console:

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

بعد إنشاء التطبيق، أكمِل مهام إعداد تطبيقك الأولية في لوحة البيانات:

لوحة بيانات 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:

  1. مختبِرو مسار الاختبار: انتقِل إلى الاختبار والإصدار > الاختبار > الاختبار الداخلي (أو الاختبار المغلق)، وافتح علامة التبويب المختبِرون، ثم انقر على إنشاء قائمة عناوين بريد إلكتروني، وأضِف عناوين البريد الإلكتروني للمختبِرين، واختَر القائمة، ثم انقر على حفظ التغييرات.علامة التبويب &quot;المختبِرون&quot; في صفحة &quot;الاختبار الداخلي&quot; في Google Play Console
  2. مختبِرو الترخيص: يُرجى الرجوع إلى عرض جميع التطبيقات، واختيار الإعدادات > اختبار الترخيص، وإضافة عناوين البريد الإلكتروني نفسها للمختبِرين، وضبط الردّ على الترخيص على "RESPOND_NORMALLY"، ثم النقر على حفظ التغييرات.إعدادات اختبار الترخيص في Google Play Console

ضبط عمليات الشراء داخل التطبيق

اضبط معرّفات المنتجات الثلاثة نفسها في Google Play Console:

  • ‫dash_consumable_2k: منتج استهلاكي يمنحك 2,000 Dash.
  • ‫dash_upgrade_3d: ترقية لمرة واحدة في لعبة 3D Dash غير قابلة للاستهلاك.
  • ‫dash_subscription_doubler: اشتراك يتجدّد تلقائيًا في ميزة مضاعفة النقرات

أولاً، أنشئ المنتجات المدفوعة لمرة واحدة (dash_consumable_2k وdash_upgrade_3d):

  1. اختَر تطبيقك في Google Play Console وانتقِل إلى تحقيق الربح من خلال Play > المنتجات > المنتجات داخل التطبيق.
  2. انقر على إنشاء منتج.صفحة &quot;المنتجات داخل التطبيق&quot; في Google Play Console مع زر &quot;إنشاء منتج&quot;
  3. أدخِل معرّف المنتج (dash_consumable_2k) واسمه ووصفه وسعره بدقة، ثم انقر على حفظ وتفعيل.
  4. كرِّر العملية مع dash_upgrade_3d.

بعد ذلك، أنشئ الاشتراك (dash_subscription_doubler):

  1. انتقِل إلى تحقيق الربح المادي باستخدام Google Play > المنتجات > الاشتراكات وانقر على إنشاء اشتراك.صفحة &quot;الاشتراكات&quot; في Google Play Console مع زر &quot;إنشاء اشتراك&quot;
  2. أدخِل معرّف المنتج (dash_subscription_doubler)، وأضِف خطة أساسية مع مدة فوترة وسعر أسبوعيَين، ثم انقر على حفظ وتفعيل.

6. إعداد Firebase

يوفّر استخدام خدمة خلفية مع Cloud Firestore للتحقّق من عمليات الشراء وتتبُّعها العديد من مزايا الأمان لتطبيقك:

  • يمكنك التحقّق من المعاملات مباشرةً من خلال خوادم Google Play وApple.
  • يمكنك التفاعل مع أحداث الفوترة من جهة الخادم (مثل عمليات التجديد أو الإلغاء).
  • يمكنك تخزين مصدر وحيد للحقيقة في Cloud Firestore مرتبط بكل مستخدم تمت مصادقته.
  • لا يمكن للمستخدمين فتح المزايا المدفوعة من خلال التلاعب بساعة الجهاز.

إنشاء مشروع Firebase

  1. افتح وحدة تحكُّم Firebase وأنشئ مشروعًا جديدًا في Firebase (على سبيل المثال، Dash Clicker).
  2. انتقِل إلى Build > Authentication (إنشاء > المصادقة)، وانقر على Get started (البدء)، وافتح علامة التبويب Sign-in method (طريقة تسجيل الدخول)، وفعِّل موفِّر خدمة تسجيل الدخول من Google.علامة التبويب &quot;طريقة تسجيل الدخول&quot; في مصادقة Firebase تعرض تفعيل Google
  3. انتقِل إلى إنشاء > قاعدة بيانات Firestore وأنشئ قاعدة بيانات.بانر إنشاء Cloud Firestore في وحدة تحكُّم Firebase
  4. افتح علامة التبويب القواعد في 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
  1. اختَر مشروع Firebase الذي أنشأته.
  2. فعِّل android وios.
  3. أكِّد اختيارك نعم عندما يُطلب منك إلغاء lib/firebase_options.dart.

إعداد Firebase لنظام التشغيل Android: شهادة SHA-1 لتصحيح الأخطاء

تتطلّب ميزة "تسجيل الدخول باستخدام حساب Google" على Android تسجيل بصمة SHA-1 ملف تخزين مفاتيح تصحيح الأخطاء في وحدة تحكُّم Firebase:

  1. في وحدة تحكُّم Firebase، افتح نظرة عامة على المشروع > إعدادات المشروع > الإعدادات العامة، وانتقِل للأسفل إلى تطبيقاتك، واختَر تطبيق Android:إعدادات مشروع Firebase التي تعرض إعدادات تطبيق Android وزر &quot;إضافة بصمة إصبع&quot;
  2. أنشِئ تقرير توقيع من app/android/:
    cd app/android
    ./gradlew :app:signingReport
    
  3. ابحث عن الملف المرجعي 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/ وافتح التطبيق على جهازك الاختباري الذي تم ضبطه. عندما تكون منتجات متجرك نشطة، تعرضها علامة التبويب شراء جاهزة للشراء:

علامة التبويب &quot;شراء&quot; في لعبة Dash Clicker تعرض منتجات المتجر الثلاثة التي تم تحميلها من المتجر

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 يبدأ Router shelf_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، يجب إنشاء مفتاح حساب خدمة:

  1. في وحدة تحكُّم Firebase، افتح إعدادات المشروع > حسابات الخدمة وانقر على إنشاء مفتاح خاص جديد.علامة التبويب &quot;حسابات الخدمة&quot; في إعدادات مشروع Firebase تعرض الخيار &quot;إنشاء مفتاح خاص جديد&quot;
  2. احفظ ملف JSON الذي تم تنزيله باسم dart-backend/assets/service-account-firebase.json.

إعداد إمكانية الوصول إلى Google Play

للسماح لـ "dart-backend/" بالتحقّق من عمليات الشراء على Android باستخدام Google Play Android Developer API، يُرجى اتّباع الخطوات التالية:

  1. افتح صفحة Google Play Android Developer API في Google Cloud Console وفعِّل واجهة برمجة التطبيقات.صفحة Google Cloud Console لواجهة Google Play Android Developer API
  2. انتقِل إلى صفحة حسابات خدمة Google Cloud وانقر على + إنشاء حساب خدمة.صفحة &quot;حسابات الخدمة&quot; في Google Cloud Console تعرض خيار &quot;إنشاء حساب خدمة&quot;
  3. أدخِل اسم حساب خدمة وانقر على إنشاء ومتابعة.الخطوة المتعلقة بتفاصيل حساب الخدمة
  4. امنح دور مشترك Pub/Sub وانقر على تم.خطوة منح حساب الخدمة هذا إذن الوصول إلى المشروع، وتظهر فيها دور &quot;مشترك Pub/Sub&quot;
  5. افتح قائمة الإجراءات لحساب الخدمة الذي تم إنشاؤه حديثًا واختَر إدارة المفاتيح.قائمة إجراءات حساب الخدمة مع تمييز خيار &quot;إدارة المفاتيح&quot;
  6. انقر على إضافة مفتاح > إنشاء مفتاح جديد، واختَر JSON، ثم نزِّل المفتاح:قائمة &quot;إضافة مفتاح&quot; تعرض خيار &quot;إنشاء مفتاح جديد&quot;مربّع حوار &quot;إنشاء مفتاح خاص&quot; مع اختيار JSON
  7. احفظ الملف الذي تم تنزيله باسم dart-backend/assets/service-account-google-play.json.
  8. افتح المستخدمون والأذونات في Google Play Console، وانقر على دعوة مستخدمين جُدد، ثم أدخِل عنوان البريد الإلكتروني لحساب الخدمة:صفحة &quot;المستخدمون والأذونات&quot; في Google Play Consoleجدول حسابات Google Cloud Service يعرض عنوان البريد الإلكتروني لحساب الخدمة
  9. امنح إذنَي عرض البيانات المالية وإدارة الطلبات والاشتراكات لتطبيقك، ثم انقر على دعوة مستخدم.علامة تبويب &quot;أذونات التطبيق&quot; التي تعرض خيارَي &quot;عرض البيانات المالية&quot; و&quot;إدارة الطلبات والاشتراكات&quot; محدَّدَين

إعداد إمكانية الوصول إلى Apple App Store

للتحقّق من إيصالات متجر التطبيقات في الخلفية، أنشئ مفتاحًا سريًا مشتركًا خاصًا بالتطبيق:

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

تعديل "dart-backend/lib/constants.dart"

تأكَّد من ضبط الثوابت التالية في dart-backend/lib/constants.dart:

  • ‫androidPackageId: جهاز Android‏ applicationId (مثل 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.

التسلسل الهرمي لفئة PurchaseHandler التي يتم تنفيذها من خلال GooglePlayPurchaseHandler وAppStorePurchaseHandler

اطلب من 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

  1. اضبط googleCloudProjectId في dart-backend/lib/constants.dart على رقم تعريف مشروعك على Google Cloud وFirebase.
  2. افتح صفحة مواضيع Cloud Pub/Sub في Google Cloud Console، وتأكَّد من اختيار مشروعك، ثم انقر على + إنشاء موضوع.صفحة &quot;مواضيع Google Cloud Pub/Sub&quot; التي تعرض زر &quot;إنشاء موضوع&quot;
  3. اضبط رقم تعريف الموضوع على play_billing (مطابقة googlePlayPubsubBillingTopic في dart-backend/lib/constants.dart، ما يؤدي إلى إنشاء اشتراك تلقائي play_billing-sub)، ثم انقر على إنشاء.مربّع حوار إنشاء موضوع يتضمّن رقم تعريف الموضوع play_billing
  4. افتح قائمة الخيارات الإضافية في موضوع "play_billing" وانقر على عرض الأذونات.قائمة مواضيع Pub/Sub مع تمييز إذن بعرض البيانات
  5. انقر على إضافة مستخدم رئيسي، وأدخِل google-play-developer-notifications@system.gserviceaccount.com، ثم امنحه دور ناشر Pub/Sub، وانقر على حفظ.لوحة &quot;إضافة العناصر الرئيسية&quot; (Add principals) التي تمنح دور &quot;ناشر Pub/Sub&quot;‏ (Pub/Sub Publisher) إلى google-play-developer-notifications
  6. انسخ اسم الموضوع بالكامل، وافتح تطبيقك في Google Play Console، وانتقِل إلى تحقيق الربح مع Google Play > إعداد تحقيق الربح، وألصِق اسم الموضوع، ثم انقر على حفظ التغييرات.إعدادات تحقيق الربح في Google Play Console التي تعرض اسم موضوع الإشعارات في الوقت الفعلي الخاصة بالمطوّرين

إعداد مفتاح App Store Server API

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

قائمة مفاتيح الشراء داخل التطبيق في App Store Connect التي تعرض معرّف جهة الإصدار ومعرّف المفتاح

طلب من 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 و"إشعارات خادم متجر التطبيقات".

مزيد من المعلومات