הוספת רכישות מתוך האפליקציה לאפליקציית Flutter

1. מבוא

כדי להוסיף רכישות מתוך האפליקציה לאפליקציית Flutter, צריך להגדיר את Apple App Store ואת חנות Google Play, לאמת אסימוני רכישה בקצה עורפי מהימן ולהעניק זכויות כמו מטבעות שניתן להשתמש בהם, שדרוגים חד-פעמיים או הטבות של מינוי חוזר.

ב-Codelab הזה, תשתפו פעולה עם Google Antigravity כדי ליצור את Dash Clicker – משחק קליקר לנייד שמשתמש בקמע של Dash כמטבע – ותשלבו אותו עם שירות לקצה העורפי של Dart shelf ועם 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.

תהליך הלמידה שלך

ב-Codelab הזה נסביר איך ליצור ולחבר את תהליך הרכישה באפליקציה ב-Full Stack, שלב אחרי שלב:

  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. הגדרת חנות Play – יוצרים את האפליקציה ב-Google Play Console, מבקשים מ-Antigravity להגדיר חתימה על מאגר מפתחות של גרסה ב-Gradle, מעלים חבילת App Bundle ראשונית, מוסיפים בודקי רישיונות ומגדירים את המוצרים.
  5. הגדרת Firebase – מפעילים את "כניסה באמצעות חשבון Google" ואת Cloud Firestore במסוף Firebase, מריצים את flutterfire configure ומגדירים טביעות אצבע SHA-1 ל-Android וסכמות URL ל-iOS.
  6. האזנה לעדכוני רכישות – מבקשים מ-Antigravity להוסיף wrapper של 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 ו-App Store בקצה העורפי של Dart ומאחסנים אותם ב-Cloud Firestore.
  • איך לעבד אירועי חיוב בחנות ולסנכרן את הרשאות המינוי והשדרוג בין מכשירים.

דרישות מוקדמות

  • היכרות בסיסית עם ווידג'טים של Flutter, תחביר של Dart וניהול מצב של Provider.
  • חשבון פיתוח ב-Apple (כדי לבדוק רכישות ב-App Store ב-iOS), חשבון פיתוח ב-Google Play (כדי לבדוק רכישות בחנות Play ב-Android) או שניהם.
  • חשבון Firebase ו-Firebase CLI.

2. הגדרת סביבת הפיתוח

עריכה

ב-Codelab הזה נשתמש ב-Google Antigravity כסביבת הפיתוח שמתמקדת ב-AI. בכל שלב, אתם מנחים את Antigravity ליצור או לפתח את לקוח Flutter (app/) ואת הקצה העורפי של Dart (dart-backend/), בודקים את הקוד שנוצר ואם רוצים, בוחנים וריאציות.

התקנת Flutter

ההוראות העדכניות ביותר להתקנת Flutter SDK מופיעות תמיד בכתובת docs.flutter.dev.

כדי להשתמש ב-Codelab הזה, צריך להתקין את התוכנות הבאות:

  1. Flutter SDK
  2. ‫Google Antigravity עם הפלאגין הרשמי של Dart ו-Flutter מופעל (זמין ב-Plugin Marketplace בקטע פיתוח פתרונות עם 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

בחלונית הניווט בפרויקט ב-Xcode, בוחרים באפשרות Runner (כלי ההרצה) בחלק העליון, פותחים את הכרטיסייה Signing & Capabilities (חתימה ויכולות), בוחרים את Team (צוות) ומזינים את Bundle Identifier (מזהה החבילה) הייחודי:

הגדרת מזהה הצוות ומזהה החבילה בקטע Signing & Capabilities ב-Xcode

עכשיו צריך לעדכן את 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 מספק את ה-API של InAppPurchase בפלטפורמות שונות, שמגובה על ידי StoreKit ב-iOS וחיוב ב-Google Play ב-Android.
  • ‫in_app_purchase_platform_interface חושף את InAppPurchasePlatformAddition, שמאפשר להטמיע לקוח InAppPurchase מדומה ב-app/test/widget_test.dart.

4. הגדרת חנות האפליקציות

כדי לבדוק רכישות באפליקציה ב-iOS, צריך לרשום את האפליקציה ב-App Store Connect ולהגדיר מוצרים שניתן לרכוש. אתם לא צריכים לפרסם את האפליקציה או לשלוח אותה לבדיקה, אבל אתם צריכים חשבון פיתוח של אפל. אם אין לכם חשבון, הירשמו לתוכנית Apple Developer Program.

כדי להשתמש ברכישות באפליקציה, צריך להיות לכם הסכם פעיל בנושא אפליקציות בתשלום ב-App Store Connect. עוברים אל App Store Connect ובוחרים באפשרות Agreements, Tax, and Banking (הסכמים, מיסים ובנקאות) או Business (עסק).

לוח הבקרה בדף הבית של App Store Connect, שבו מודגשים הסכמים, מיסים ובנקאות

קוראים את ההסכמים של אפליקציות בחינם ואפליקציות בתשלום. מעיינים בתנאים של אפליקציות בתשלום ומאשרים אותם, ומזינים את פרטי המס והבנק הנדרשים.

רשימת ההסכמים ב-App Store Connect שבה מוצג שההסכם של האפליקציות החינמיות פעיל ושההסכם של האפליקציות בתשלום חדש

כשהכול מוגדר, הסטטוס של אפליקציות בתשלום משתנה לפעיל. בלי הסכם פעיל של אפליקציות בתשלום, StoreKit לא יחזיר את המוצרים באפליקציה במהלך הבדיקה.

רשימת ההסכמים של App Store Connect שבה מוצגות גם אפליקציות חינמיות וגם אפליקציות בתשלום במצב פעיל

רישום מזהה אפליקציה

יוצרים מזהה אפליקציה חדש בפורטל למפתחים של אפל:

  1. נכנסים אל Apple Developer Identifiers ולוחצים על הסמל + לצד הכותרת Identifiers.רשימת המזהים בפורטל המפתחים של אפל, עם הדגשה של כפתור ההוספה
  2. בוחרים באפשרות מזהי אפליקציות ולוחצים על המשך.מסך רישום של מזהה חדש עם מזהי אפליקציות שנבחרו
  3. בוחרים באפשרות אפליקציה ולוחצים על המשך.מסך לבחירת סוג, כשהאפשרות "אפליקציה" מסומנת
  4. מזינים תיאור ומגדירים את מזהה החבילה (מפורש) למזהה החבילה המדויק שהגדרתם ב-Xcode. מוודאים שהיכולת רכישה באפליקציה מופעלת, ואז רושמים את המזהה.טופס רישום של מזהה אפליקציה שבו מוצגים תיאור ומזהה חבילה מפורש

פרטים נוספים זמינים במרכז העזרה של חשבון הפיתוח של אפל.

יצירת אפליקציה חדשה ומשתמש חדש בארגז החול

יוצרים אפליקציה חדשה ב-App Store Connect באמצעות מזהה החבילה הרשום:

תפריט האפליקציות ב-App Store Connect, שבו מוצגת האפשרות "אפליקציה חדשה"

תיבת הדו-שיח "אפליקציה חדשה" ב-App Store Connect, שבה מוצגים השדות של הפלטפורמה, השם, השפה, מזהה החבילה והמק"ט

במרכז העזרה של App Store Connect מוסבר איך ליצור אפליקציה ולנהל הסכמים.

כדי לבדוק רכישות באפליקציה בלי חיובים אמיתיים, יוצרים חשבון אפל בארגז חול ב-App Store Connect בקטע Users and Access (משתמשים וגישה) > Sandbox (ארגז חול). אתם צריכים להשתמש בכתובת אימייל שלא משויכת כבר לחשבון אפל.

רשימת הבודקים של App Store Connect Sandbox

באייפון או באייפד שמשמשים לבדיקה, נכנסים לחשבון בארגז החול דרך הגדרות > מפתח > חשבון אפל בארגז החול.

מסך ההגדרות של iOS שבו מוצג הקטע "חשבון אפל בארגז חול"

מסך ההגדרות ב-iOS שבו מוצג חשבון אפל בארגז חול שמחובר למערכת

הגדרת הרכישות באפליקציה

בשלב הבא, מגדירים את שלושת הפריטים שניתן לרכוש ב-App Store Connect:

  • ‫dash_consumable_2k: רכישה של פריט מתכלה שאפשר לקנות שוב ושוב, ומקבלים 2,000 נקודות Dash בכל רכישה.
  • ‫dash_upgrade_3d: רכישה של שדרוג שלא ניתן לצריכה, שאפשר לקנות רק פעם אחת, ופותחת את הקמע של Dash בתלת-ממד.
  • 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.לוקליזציה של חנות האפליקציות עם השם המוצג והתיאור
    • מעלים צילום מסך של הביקורת. תוכן התמונה לא משנה לבדיקה בארגז החול, אבל העלאת צילום מסך מעבירה את המוצר למצב מוכן לשליחה, שנדרש כדי שהאפליקציה תאחזר את המוצר מ-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 (מינויים), יוצרים Subscription Group (קבוצת מינויים) בשם subscriptions (משתמשים יכולים להירשם רק למוצר אחד באותה קבוצה בכל פעם, ולשדרג או לשדרג לאחור בתוך הקבוצה).תיבת הדו-שיח "יצירת קבוצת מינויים"
    • מוסיפים לוקליזציה של App Store לקבוצת המינויים.תיבת הדו-שיח "לוקליזציה של App Store" לקבוצת המינויים
    • בתוך הקבוצה, יוצרים מינוי עם שם קובץ העזר dash subscription doubler ומזהה המוצר dash_subscription_doubler.תיבת הדו-שיח "יצירת מינוי" של dash_subscription_doubler
    • מגדירים את משך המינוי לערך שבוע אחד, את השם המוצג לערך Jet Engine, את התיאור לערך Doubles your clicks ואת המחיר לערך \$0.49. מגדירים את הזמינות ומעלים צילום מסך לבדיקה כדי שהסטטוס שלו יהפוך למוכן לשליחה.הגדרות משך המינוי, המחיר והלוקליזציה

המוצרים אמורים להופיע עכשיו ב-App Store Connect בסטטוס Ready to Submit (מוכן לשליחה):

רשימת רכישות באפליקציה שבה מוצגים הפריטים dash_consumable_2k ו-dash_upgrade_3d במצב "מוכן לשליחה"

רשימת מינויים שבה המינוי dash_subscription_doubler מוצג כ"מוכן לשליחה"

5. הגדרת חנות 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

כדי להגדיר חתימה על גרסאות ב-app/android/app/build.gradle.kts, שולחים את ההנחיה הבאה ב-Antigravity:

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 ולחתום על גרסאות build להפצה:

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 Bundle חתום של גרסת האפליקציה מ-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 Dashes.
  • ‫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. עוברים אל ייצור הכנסות באמצעות Play > מוצרים > מינויים ולוחצים על יצירת מינוי.הדף &quot;מינויים&quot; ב-Google Play Console עם הלחצן &quot;יצירת מינוי&quot;
  2. מזינים את מזהה המוצר (dash_subscription_doubler), מוסיפים מינוי בסיסי עם תקופת חיוב שבועית ומחיר, ואז שומרים ומפעילים אותו.

6. הגדרת Firebase

שימוש בשירות לקצה העורפי עם Cloud Firestore כדי לאמת ולעקוב אחרי רכישות מספק לאפליקציה כמה יתרונות אבטחה:

  • אתם מאמתים עסקאות ישירות מול השרתים של Google Play ושל אפל.
  • אתם יכולים להגיב לאירועי חיוב בצד השרת (כמו חידושים או ביטולים).
  • אתם שומרים מקור אמת יחיד (SSOT) ב-Cloud Firestore שמשויך לכל משתמש מאומת.
  • המשתמשים לא יכולים לשנות את השעון במכשיר כדי לקבל הטבות פרימיום.

יצירת פרויקט ב-Firebase

  1. פותחים את מסוף Firebase ויוצרים פרויקט Firebase חדש (לדוגמה, Dash Clicker).
  2. עוברים אל Build > Authentication, לוחצים על Get started, פותחים את הכרטיסייה שיטת התחברות ומפעילים את ספק הכניסה Google.הכרטיסייה &quot;שיטת התחברות&quot; באימות ב-Firebase, שבה מוצג ש-Google מופעלת
  3. עוברים אל Build > Firestore Database ויוצרים מסד נתונים.באנר ליצירת Cloud Firestore במסוף Firebase
  4. פותחים את הכרטיסייה Rules ב-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 ל-Flutter

פועלים לפי המדריך להגדרת FlutterFire כדי להתקין את FlutterFire CLI, ואז מריצים את flutterfire configure בתוך app/:

cd app
flutterfire configure
  1. בוחרים את הפרויקט ב-Firebase שיצרתם.
  2. מפעילים את android ו-ios.
  3. מאשרים באמצעות yes כשמוצגת בקשה לשנות את lib/firebase_options.dart.

הגדרת Firebase ל-Android: ניפוי באגים של אישור SHA-1

כדי להשתמש בכניסה באמצעות חשבון Google ב-Android, צריך לרשום את טביעת האצבע SHA-1 של מאגר מפתחות ניפוי הבאגים במסוף Firebase:

  1. במסוף Firebase, פותחים את Project Overview (סקירה כללית של הפרויקט) > Project settings (הגדרות הפרויקט) > General (כללי), גוללים למטה אל Your apps (האפליקציות שלך) ובוחרים את אפליקציית 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 להאזין לעדכונים על רכישות בחנות ברגע שהאפליקציה מופעלת, ומשאירים את עץ הווידג'טים במצב שניתן לבדיקה על ידי הוספת wrapper של 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`.

הסבר על הקוד שנוצר

אתחול ספק נלהב ו-IAPConnection ב-app/lib/main.dart

כברירת מחדל, הערך של Provider נוצר באופן עצל (lazy) כשהווידג'ט קורא אותו בפעם הראשונה. מכיוון שעסקאות בחנות הפיזית בהמתנה יכולות להגיע אל 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, ה-constructor נרשם ל-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 כולל את ProductDetails שמוחזר על ידי החנות בזמן מעקב אחרי ProductStatus של ממשק המשתמש המקומי (purchasable,‏ purchased או 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 ול-App Store.

מבקשים מ-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 מאתחל shelf_router 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, פותחים את Project settings > Service accounts (הגדרות הפרויקט > חשבונות שירות) ולוחצים על Generate new private key (יצירת מפתח פרטי חדש).הכרטיסייה &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 ומפעילים את ה-API.דף מסוף Google Cloud של Google Play Android Developer API
  2. עוברים אל הדף "חשבונות שירות" ב-Google Cloud ולוחצים על + יצירת חשבון שירות.הדף Service accounts במסוף Google Cloud, שבו מוצגת האפשרות Create service account
  3. מזינים שם לחשבון השירות ולוחצים על Create and continue.שלב פרטי חשבון השירות
  4. מקצים את התפקיד מנוי Pub/Sub ולוחצים על סיום.שלב בפרויקט שבו מעניקים לחשבון השירות הזה גישה לתפקיד &quot;מנוי ב-Pub/Sub&quot;
  5. פותחים את תפריט הפעולות של חשבון השירות החדש ובוחרים באפשרות ניהול מפתחות.תפריט הפעולות של חשבון השירות, עם הדגשה של Manage keys
  6. בוחרים באפשרות Add key > Create new key, בוחרים באפשרות JSON ומורידים את המפתח:תפריט הוספת מפתח שבו מוצגת האפשרות &quot;יצירת מפתח חדש&quot;תיבת הדו-שיח ליצירת מפתח פרטי עם בחירה ב-JSON
  7. שומרים את הקובץ שהורדתם בשם dart-backend/assets/service-account-google-play.json.
  8. פותחים את הדף משתמשים והרשאות ב-Google Play Console, לוחצים על הזמנת משתמשים חדשים ומזינים את כתובת האימייל של חשבון השירות:הדף &quot;משתמשים והרשאות&quot; ב-Google Play Consoleטבלת חשבונות השירות ב-Google Cloud, שבה מוצגת כתובת האימייל של חשבון השירות
  9. נותנים לאפליקציה את ההרשאות הצגת נתונים פיננסיים וניהול הזמנות ומינויים, ואז לוחצים על הזמנת משתמש.כרטיסיית ההרשאות שניתנות לאפליקציה, שבה מסומנות האפשרויות &quot;הצגת נתונים פיננסיים&quot; ו&quot;ניהול הזמנות ומינויים&quot;

הגדרת גישה ל-Apple App Store

כדי לאמת קבלות מ-App Store בקצה העורפי, צריך ליצור סוד משותף ספציפי לאפליקציה:

  1. פותחים את App Store Connect, לוחצים על Apps (אפליקציות) ובוחרים את האפליקציה הרלוונטית.
  2. בסרגל הצד, עוברים אל כללי > פרטי האפליקציה.
  3. בקטע App-Specific Shared Secret (סוד משותף ספציפי לאפליקציה), לוחצים על Manage (ניהול), יוצרים סוד משותף חדש ומעתיקים אותו:הקטע &quot;סוד משותף ספציפי לאפליקציה&quot; ב-App Store Connectמודל של סוד משותף ספציפי לאפליקציה שבו מוצג הסוד שנוצר

עדכון של 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 לאמת את הרכישות בצד הלקוח ובקצה העורפי

כדי לקשר בין האפליקציה שנוצרה ב-Flutter לבין תהליך האימות בקצה העורפי של Dart, שולחים את ההנחיה הבאה ב-Antigravity:

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 ובסוג החזרה של הרשומה, ואז מעביר את האימות ל-store handler התואם:

  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.

הגדרת מפתחות API של Cloud Pub/Sub ושל App Store Server

הגדרת Google Play Cloud Pub/Sub

  1. מגדירים את googleCloudProjectId ב-dart-backend/lib/constants.dart למזהה הפרויקט ב-Google Cloud וב-Firebase.
  2. פותחים את הדף Cloud Pub/Sub Topics במסוף Google Cloud, מוודאים שהפרויקט שלכם נבחר ולוחצים על ‎+ Create Topic.הדף &quot;נושאי Google Cloud Pub/Sub&quot; עם הכפתור &quot;יצירת נושא&quot;
  3. מגדירים את Topic ID ל-play_billing (תואם ל-googlePlayPubsubBillingTopic ב-dart-backend/lib/constants.dart, שיוצר באופן אוטומטי מינוי ברירת מחדל play_billing-sub), ולוחצים על Create.יצירת תיבת דו-שיח של נושא עם מזהה הנושא play_billing
  4. פותחים את סמל האפשרויות הנוספות (3 נקודות) בנושא play_billing ולוחצים על הצגת הרשאות.תפריט הנושאים ב-Pub/Sub עם הדגשה של הרשאות הצפייה
  5. לוחצים על Add principal, מזינים את google-play-developer-notifications@system.gserviceaccount.com, מקצים את התפקיד Pub/Sub Publisher ולוחצים על Save.החלונית &quot;הוספת חשבונות משתמשים&quot; שבה מקצים את התפקיד &quot;פרסום הודעות ב-Pub/Sub&quot; ל-google-play-developer-notifications
  6. מעתיקים את השם המלא של הנושא, פותחים את האפליקציה ב-Google Play Console, עוברים אל ייצור הכנסות באמצעות Play > הגדרת ייצור הכנסות, מדביקים את שם הנושא ולוחצים על שמירת השינויים.הגדרת המונטיזציה ב-Google Play Console, שבה מוצג שם הנושא של התראות בזמן אמת למפתחים

הגדרת מפתח API של שרת App Store

  1. נכנסים אל App Store Connect ובוחרים באפשרות Users and Access (משתמשים וגישה).
  2. עוברים אל Integrations > Keys > In-App Purchase (שילובים > מפתחות > רכישה באפליקציה) ולוחצים על הכפתור + כדי ליצור מפתח חדש (לדוגמה, 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 שניות, מפענח כל מטען ייעודי (payload) של התראה ב-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.
  • פיתוח של קצה עורפי (backend) של Dart shelf (dart-backend/) שמאמת אסימוני רכישה באמצעות Google Play Android Developer API ו-App Store, דוגם עדכוני חיוב באמצעות Cloud Pub/Sub ו-App Store Server API, ושומר את מצב הרכישה ב-Cloud Firestore.
  • סנכרון הרשאות הרכישה המאומתות בחזרה ללקוח Flutter בזמן אמת באמצעות IAPRepo.

השלבים הבאים

  • מוסיפים תוכנת ביניים לאימות של טוקן מזהה של Firebase Auth ל-POST /verifypurchase ב-dart-backend/bin/server.dart.
  • פורסים את dart-backend/ ב-Cloud Run ומגדירים תגובות לפעולות אינטרנט (webhooks) מסוג Push ל-Google Cloud Pub/Sub ולהתראות משרת App Store.

מידע נוסף