یادداشت‌های انتشار کتابخانه صورت‌حساب Google Play

این سند حاوی یادداشت‌های انتشار برای کتابخانه پرداخت گوگل پلی است.

کتابخانه پرداخت گوگل پلی نسخه ۸.۱.۰ (۲۰۲۵-۱۱-۰۶)

نسخه ۸.۱.۰ کتابخانه پرداخت گوگل پلی و افزونه‌های کاتلین اکنون در دسترس هستند.

خلاصه تغییرات

  • اشتراک‌های معلق

    پارامتر جدیدی به متد BillingClient.queryPurchasesAsync() اضافه شده است تا اشتراک‌های معلق را هنگام جستجوی اشتراک‌ها لحاظ کند. اشتراک‌های معلق همچنان به کاربر نسبت داده می‌شوند، اما فعال نیستند، یا به این دلیل که کاربر اشتراک را متوقف کرده یا روش پرداخت تمدید آنها رد شده است.

    شیء Purchase که در شنونده برگردانده می‌شود، برای هر اشتراک معلق isSuspended() = true برمی‌گرداند. در این حالت، شما نباید به اشتراک خریداری شده دسترسی بدهید و در عوض، کاربر را به مرکز اشتراک‌ها هدایت کنید که در آنجا می‌تواند روش‌های پرداخت خود را مدیریت کند یا برای فعال‌سازی مجدد اشتراک خود، حالت مکث ایجاد کند.

  • به‌روزرسانی‌های اشتراک‌ها :

    • شیء BillingFlowParams.ProductDetailsParams اکنون دارای متد setSubscriptionProductReplacementParams() است که در آن می‌توانید اطلاعات جایگزینی سطح محصول را مشخص کنید.

    • شیء SubscriptionProductReplacementParams دو متد setter دارد:

      • setOldProductId : محصول قدیمی که باید با محصول موجود در ProductDetails فعلی جایگزین شود.
      • setReplacementMode : این حالت جایگزینی سطح آیتم است. این حالت‌ها اساساً مشابه SubscriptionUpdateParams هستند، اما نگاشت مقدار به‌روزرسانی شده است. یک حالت جایگزینی جدید KEEP_EXISTING معرفی شده است که به شما امکان می‌دهد برنامه پرداخت موجود را برای یک آیتم بدون تغییر نگه دارید.

    • SubscriptionUpdateParams setSubscriptionReplacementMode منسوخ خواهد شد. به جای آن باید از SubscriptionProductReplacementParams.setReplacementMode استفاده کنید.

  • minSdkVersion به ۲۳ به‌روزرسانی شد.

  • فعال‌سازی APIهای پیش‌سفارش برای محصولات یکبار مصرف

    رابط برنامه‌نویسی کاربردی (API ProductDetails.oneTimePurchaseOfferDetails.getPreorderDetails() که جزئیات پیش‌سفارش را دریافت می‌کند، اکنون برای استفاده در دسترس است.

  • کتابخانه پرداخت گوگل پلی اکنون از کاتلین نسخه ۲.۲.۰ پشتیبانی می‌کند.

کتابخانه صورتحساب گوگل پلی نسخه ۸.۰.۰ (۲۰۲۵-۰۶-۳۰)

نسخه ۸.۰.۰ کتابخانه پرداخت گوگل پلی و افزونه‌های کاتلین اکنون در دسترس هستند.

خلاصه تغییرات

  • از این پس به اقلام درون‌برنامه‌ای، محصولات یکبار مصرف گفته می‌شود.

  • گزینه‌های خرید متعدد و پیشنهادهای ویژه برای محصولات یکبار مصرف.

    اکنون می‌توانید چندین گزینه خرید و پیشنهاد برای محصولات یکبار مصرف خود داشته باشید. این امر به شما انعطاف‌پذیری در نحوه فروش محصولاتتان می‌دهد و پیچیدگی مدیریت آنها را کاهش می‌دهد.

  • متد queryProductDetailsAsync() بهبود یافته است.

    قبل از PBL 8.0.0، متد queryProductDetailsAsync() محصولاتی را که نمی‌توانستند واکشی شوند، برنمی‌گرداند. این می‌تواند به دلایلی مانند پیدا نشدن محصول یا عدم وجود پیشنهاد برای کاربر باشد. با PBL 8.0.0، محصولات واکشی نشده با یک کد وضعیت سطح محصول جدید بازگردانده می‌شوند که اطلاعاتی در مورد محصولات واکشی نشده ارائه می‌دهد. توجه داشته باشید که تغییری در امضای ProductDetailsResponseListener.onProductDetailsResponse() وجود دارد که نیاز به تغییراتی در برنامه شما دارد. برای اطلاعات بیشتر، به process the result مراجعه کنید.

  • اتصال مجدد خودکار سرویس.

    پارامتر سازنده جدید BillingClient.Builder.enableAutoServiceReconnection() به توسعه‌دهندگان اجازه می‌دهد تا اتصال مجدد خودکار سرویس را فعال کنند، که با مدیریت خودکار اتصال‌های مجدد به سرویس صورتحساب Play و حذف نیاز به فراخوانی دستی startConnection() در صورت قطع اتصال سرویس، مدیریت اتصال را ساده می‌کند. برای اطلاعات بیشتر، به بخش «برقراری مجدد خودکار اتصال» مراجعه کنید.

  • کدهای زیرپاسخ برای متد launchBillingFlow() .

    نتیجه‌ی پرداخت (BillingResult) که از launchBillingFlow() برگردانده می‌شود، اکنون شامل یک فیلد کد زیرپاسخ خواهد بود. این فیلد فقط در برخی موارد پر می‌شود تا دلیل دقیق‌تری برای شکست ارائه دهد. با PBL 8.0.0، یک زیرکد PAYMENT_DECLINED_DUE_TO_INSUFFICIENT_FUNDS برای حالتی که موجودی کاربر کمتر از قیمت کالایی است که قصد خرید آن را دارد، برگردانده می‌شود.

  • متد queryPurchaseHistory() حذف شد.

    متد queryPurchaseHistory() که قبلاً به عنوان منسوخ شده علامت گذاری شده بود، اکنون حذف شده است. برای جزئیات بیشتر در مورد اینکه از چه API های جایگزین استفاده کنید، به Query Purchase History مراجعه کنید.

  • متد querySkuDetailsAsync() حذف شد.

    متد querySkuDetailsAsync() که قبلاً به عنوان منسوخ شده علامت گذاری شده بود، اکنون حذف شده است. به جای آن باید از queryProductDetailsAsync استفاده کنید.

  • متد BillingClient.Builder.enablePendingPurchases() حذف شد.

    متد enablePendingPurchases() که هیچ پارامتری نداشت و قبلاً به عنوان منسوخ علامت‌گذاری شده بود، اکنون حذف شده است. به جای آن باید از enablePendingPurchases(PendingPurchaseParams params) استفاده کنید. توجه داشته باشید که enablePendingPurchases() منسوخ شده از نظر عملکردی معادل enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build()) است.

  • متد queryPurchasesAsync() که مقدار skuType را دریافت می‌کرد و بیش از حد بارگذاری شده بود، حذف شد.

    متد queryPurchasesAsync(String skuType, PurchasesResponseListener listener) که قبلاً به عنوان منسوخ علامت‌گذاری شده بود، اکنون حذف شده است. به عنوان جایگزین، می‌توانید از queryPurchasesAsync(QueryPurchasesParams queryPurchasesParams, PurchasesResponseListener listener) استفاده کنید.

کتابخانه پرداخت گوگل پلی نسخه ۷.۱.۱ (۲۰۲۴-۱۰-۰۳)

نسخه ۷.۱.۱ کتابخانه پرداخت گوگل پلی و افزونه‌های کاتلین اکنون در دسترس هستند.

رفع اشکالات

کتابخانه پرداخت گوگل پلی نسخه ۷.۱.۰ (۲۰۲۴-۰۹-۱۹)

نسخه ۷.۱.۰ کتابخانه پرداخت گوگل پلی و افزونه‌های کاتلین اکنون در دسترس هستند.

خلاصه تغییرات

  • بهبود ایمنی نخ مربوط به وضعیت اتصال و مدیریت.
  • تغییرات جزئی برای کدهای پاسخ تست [ BillingResult ][billing-result] که به طور کامل در Play Billing Library 7.1.1 منتشر شده است، اعمال شد. برای آزمایش ادغام خود با استفاده از این ویژگی، باید به Play Billing Library 7.1.1 ارتقا دهید. یک اشکال وجود دارد که فقط برنامه‌هایی را که [billing overrides testing enabled][enable-billing-overrides-testing] دارند، تحت تأثیر قرار می‌دهد و بر استفاده منظم تأثیری ندارد. برای اطلاعات بیشتر، به Test BillingResult response codes مراجعه کنید. [billing-result]: /reference/com/android/billingclient/api/BillingResult [enable-billing-overrides-testing]: /google/play/billing/test-response-codes#enable-billing-overrides-testing

کتابخانه پرداخت گوگل پلی نسخه ۷.۰.۰ (۲۰۲۴-۰۵-۱۴)

نسخه ۷.۰.۰ کتابخانه پرداخت گوگل پلی و افزونه‌های کاتلین اکنون در دسترس هستند.

خلاصه تغییرات

کتابخانه پرداخت گوگل پلی نسخه ۶.۲.۱ (۲۰۲۴-۰۴-۱۶)

نسخه ۶.۲.۱ کتابخانه پرداخت گوگل پلی و افزونه‌های کاتلین اکنون در دسترس هستند.

خلاصه تغییرات

کتابخانه پرداخت گوگل پلی نسخه ۶.۲.۰ (۲۰۲۴-۰۳-۰۶)

نسخه ۶.۲.۰ کتابخانه پرداخت گوگل پلی و افزونه‌های کاتلین اکنون در دسترس هستند.

خلاصه تغییرات

کتابخانه پرداخت گوگل پلی نسخه ۶.۱.۰ (۲۰۲۳-۱۱-۱۴)

نسخه ۶.۱.۰ کتابخانه پرداخت گوگل پلی و افزونه‌های کاتلین اکنون در دسترس هستند.

خلاصه تغییرات

کتابخانه پرداخت گوگل پلی نسخه ۶.۰.۱ (۲۰۲۳-۰۶-۲۲)

نسخه ۶.۰.۱ کتابخانه پرداخت گوگل پلی و افزونه‌های کاتلین اکنون در دسترس هستند.

خلاصه تغییرات

کتابخانه پرداخت Play را برای سازگاری با اندروید ۱۴ به‌روزرسانی کنید.

کتابخانه پرداخت گوگل پلی نسخه ۶.۰ (۲۰۲۳-۰۵-۱۰)

نسخه ۶.۰.۰ کتابخانه پرداخت گوگل پلی و افزونه‌های کاتلین اکنون در دسترس هستند.

خلاصه تغییرات

  • یک enum جدید ReplacementMode اضافه شد تا جایگزین ProrationMode شود.

    توجه داشته باشید که ProrationMode به دلایل سازگاری با نسخه‌های قبلی هنوز در دسترس است.

  • شناسه سفارش برای خریدهای PENDING حذف شد.

    پیش از این، شناسه سفارش همیشه ایجاد می‌شد، حتی اگر خرید در انتظار خرید بود. از نسخه ۶.۰.۰ به بعد، شناسه سفارش برای خریدهای در انتظار خرید ایجاد نمی‌شود و برای این خریدها، شناسه سفارش پس از انتقال خرید به حالت PURCHASED پر می‌شود.

  • متدهای queryPurchases و launchPriceConfirmationFlow حذف شدند.

    متدهای queryPurchases و launchPriceConfirmationFlow که قبلاً به عنوان منسوخ علامت‌گذاری شده بودند، اکنون در Play Billing Library 6.0.0 حذف شده‌اند. توسعه‌دهندگان باید به جای queryPurchases از queryPurchasesAsync استفاده کنند. برای جایگزین‌های launchPriceConfirmationFlow ، به تغییرات قیمت مراجعه کنید.

  • کد پاسخ خطای شبکه جدید اضافه شد.

    یک کد پاسخ خطای شبکه جدید، NETWORK_ERROR ، از نسخه ۶.۰.۰ به PBL اضافه شده است. این کد زمانی برگردانده می‌شود که خطایی به دلیل مشکل اتصال شبکه رخ دهد. این خطاهای اتصال شبکه قبلاً به عنوان SERVICE_UNAVAILABLE گزارش می‌شدند.

  • SERVICE_UNAVAILABLE و SERVICE_TIMEOUT به‌روزرسانی شدند.

    با شروع از نسخه ۶.۰.۰ PBL، خطاهای ناشی از timeout در پردازش به جای SERVICE_TIMEOUT فعلی، به صورت SERVICE_UNAVAILABLE برگردانده می‌شوند.

    این رفتار در نسخه‌های قبلی PBL تغییر نمی‌کند.

  • SERVICE_TIMEOUT حذف شد.

    با شروع از نسخه ۶.۰.۰ PBL، دیگر SERVICE_TIMEOUT برگردانده نخواهد شد. نسخه‌های قبلی PBL همچنان این کد را برمی‌گردانند.

  • ثبت وقایع اضافی اضافه شد.

    نسخه ۶ کتابخانه پرداخت Play شامل گزارش‌گیری‌های اضافی است که بینشی در مورد استفاده از API (مانند موفقیت و شکست) و مشکلات اتصال سرویس ارائه می‌دهد. این اطلاعات برای بهبود عملکرد کتابخانه پرداخت Play و ارائه پشتیبانی بهتر برای خطاها استفاده خواهد شد.

کتابخانه پرداخت گوگل پلی نسخه ۵.۲.۱ (۲۰۲۳-۰۶-۲۲)

نسخه ۵.۲.۱ کتابخانه پرداخت گوگل پلی و افزونه‌های کاتلین اکنون در دسترس هستند.

خلاصه تغییرات

کتابخانه پرداخت Play را برای سازگاری با اندروید ۱۴ به‌روزرسانی کنید.

کتابخانه پرداخت گوگل پلی نسخه ۵.۲ (۲۰۲۳-۰۴-۰۶)

نسخه ۵.۲.۰ کتابخانه پرداخت گوگل پلی و افزونه‌های کاتلین اکنون در دسترس هستند.

خلاصه تغییرات

کتابخانه پرداخت گوگل پلی نسخه ۵.۱ (۲۰۲۲-۱۰-۳۱)

نسخه ۵.۱.۰ کتابخانه پرداخت گوگل پلی و افزونه‌های کاتلین اکنون در دسترس هستند.

این نسخه شامل تغییرات زیر است.

خلاصه تغییرات

نسخه ۵.۰ کتابخانه پرداخت گوگل پلی (۲۰۲۲-۰۵-۱۱)

نسخه ۵.۰.۰ کتابخانه پرداخت گوگل پلی و افزونه‌های کاتلین اکنون در دسترس هستند.

این نسخه شامل تغییرات زیر است.

خلاصه تغییرات

  • مدل جدیدی برای اشتراک‌ها معرفی شد، از جمله موجودیت‌های جدیدی که به شما امکان می‌دهند چندین پیشنهاد برای یک محصول اشتراکی ایجاد کنید. برای اطلاعات بیشتر، به راهنمای مهاجرت مراجعه کنید.
  • BillingClient.queryProductDetailsAsync() به جای BillingClient.querySkuDetailsAsync() اضافه شد.
  • متد setIsOfferPersonalized() برای الزامات افشای قیمت‌گذاری شخصی‌سازی‌شده اتحادیه اروپا اضافه شد. برای کسب اطلاعات بیشتر در مورد نحوه استفاده از این متد، به بخش «اعلام قیمت شخصی‌سازی‌شده» مراجعه کنید.
  • queryPurchases() که قبلاً منسوخ شده بود و با queryPurchasesAsync که در کتابخانه صورتحساب Google Play نسخه ۴.۰.۰ معرفی شده بود، جایگزین شده بود، حذف شد.
  • launchPriceChangeFlow منسوخ شده است و در نسخه‌های آینده حذف خواهد شد. برای کسب اطلاعات بیشتر در مورد جایگزین‌ها، به Launch a price change confirmation flow مراجعه کنید.
  • setVrPurchaseFlow() که قبلاً هنگام نمونه‌سازی جریان خرید استفاده می‌شد، حذف شد. در نسخه‌های قبلی، این متد کاربر را به تکمیل خرید در دستگاه اندروید خود هدایت می‌کرد. پس از حذف این متد، کاربران خرید را از طریق جریان خرید استاندارد تکمیل خواهند کرد.

نسخه ۴.۱ کتابخانه پرداخت گوگل پلی (۲۰۲۲-۰۲-۲۳)

نسخه ۴.۱.۰ کتابخانه پرداخت گوگل پلی و افزونه‌های کاتلین اکنون در دسترس هستند.

این نسخه شامل تغییرات زیر است.

خلاصه تغییرات

  • برای کمک به مدیریت کاهش پرداخت‌های اشتراک BillingClient.showInAppMessages() اضافه شد. برای کسب اطلاعات بیشتر در مورد نحوه استفاده از پیام‌رسانی درون‌برنامه‌ای برای مدیریت کاهش پرداخت‌های اشتراک، به مدیریت کاهش پرداخت‌ها مراجعه کنید.

نسخه ۴.۰ کتابخانه پرداخت گوگل پلی (۲۰۲۱-۰۵-۱۸)

نسخه ۴.۰.۰ کتابخانه پرداخت گوگل پلی و افزونه‌های کاتلین اکنون در دسترس هستند.

خلاصه تغییرات

  • تابع BillingClient.queryPurchasesAsync() به جای BillingClient.queryPurchases() اضافه شد که در نسخه‌های بعدی حذف خواهد شد.

  • حالت جایگزینی اشتراک جدید IMMEDIATE_AND_CHARGE_FULL_PRICE اضافه شد.

  • متد BillingClient.getConnectionState() برای بازیابی وضعیت اتصال کتابخانه‌ی پرداخت Play اضافه شد.

  • Javadoc و پیاده‌سازی آن به‌روزرسانی شد تا مشخص شود که یک متد در کدام thread می‌تواند فراخوانی شود و نتایج کدام thread ارسال شود.

  • تابع BillingFlowParams.Builder.setSubscriptionUpdateParams() به عنوان روشی جدید برای شروع به‌روزرسانی‌های اشتراک اضافه شد. این تابع جایگزین BillingFlowParams#getReplaceSkusProrationMode ، BillingFlowParams#getOldSkuPurchaseToken ، BillingFlowParams#getOldSku ، BillingFlowParams.Builder#setReplaceSkusProrationMode ، BillingFlowParams.Builder#setOldSku می‌شود که حذف شده‌اند.

  • توابع Purchase.getQuantity() و PurchaseHistoryRecord.getQuantity() اضافه شدند.

  • Purchase#getSkus() و PurchaseHistoryRecord#getSkus() اضافه شدند. این توابع جایگزین Purchase#getSku و PurchaseHistoryRecord#getSku می‌شوند که حذف شده‌اند.

  • BillingFlowParams#getSku ‎، BillingFlowParams#getSkuDetails ‎ و BillingFlowParams#getSkuType ‎ حذف شدند.

کتابخانه پرداخت گوگل پلی نسخه ۳.۰.۳ (۲۰۲۱-۰۳-۱۲)

نسخه ۳.۰.۳ کتابخانه پرداخت گوگل پلی، افزونه کاتلین و افزونه یونیتی اکنون در دسترس هستند.

رفع اشکالات جاوا و کاتلین

  • رفع نشت حافظه هنگام فراخوانی endConnection() .
  • رفع مشکل استفاده از کتابخانه پرداخت گوگل پلی توسط برنامه‌هایی که از حالت اجرای تک وظیفه‌ای استفاده می‌کنند. یک فراخوانی onPurchasesUpdated() زمانی اجرا می‌شود که یک برنامه از لانچر اندروید از سر گرفته شود و پنجره پرداخت قبل از تعلیق قابل مشاهده بوده باشد.

رفع اشکالات یونیتی

  • به‌روزرسانی به نسخه ۳.۰.۳ جاوا برای رفع مشکل نشت حافظه و حل مشکل جلوگیری از خریدها هنگام از سرگیری برنامه از لانچر اندروید و قابل مشاهده بودن کادر پرداخت قبل از تعلیق.

کتابخانه پرداخت گوگل پلی نسخه ۳.۰.۲ (۲۰۲۰-۱۱-۲۴)

نسخه ۳.۰.۲ کتابخانه پرداخت گوگل پلی و افزونه کاتلین اکنون در دسترس هستند.

رفع اشکالات

  • اشکالی در افزونه کاتلین که در آن کوروتین با خطای "قبلاً از سر گرفته شده" از کار می‌افتاد، برطرف شد.
  • رفع مشکل ارجاعات حل نشده هنگام استفاده از افزونه Kotlin با کتابخانه kotlinx.coroutines نسخه ۱.۴+.

کتابخانه پرداخت گوگل پلی نسخه ۳.۰.۱ (۲۰۲۰-۰۹-۳۰)

نسخه ۳.۰.۱ کتابخانه پرداخت گوگل پلی و افزونه کاتلین اکنون در دسترس هستند.

رفع اشکالات

  • اشکالی که باعث می‌شد اگر برنامه در حین جریان صدور صورتحساب از کار بیفتد و بازیابی شود، PurchasesUpdatedListener ممکن است با نتیجه خرید فراخوانی نشود، برطرف شد.

نسخه ۳.۰ کتابخانه پرداخت گوگل پلی (۲۰۲۰-۰۶-۰۸)

نسخه ۳.۰.۰ کتابخانه پرداخت گوگل پلی، افزونه کاتلین و افزونه یونیتی اکنون در دسترس هستند.

خلاصه تغییرات

  • پشتیبانی از SKU پاداشی حذف شد.
  • پارامترهای ChildDirected و UnderAgeOfConsent حذف شدند.
  • متدهای منسوخ‌شده‌ی payload توسعه‌دهنده حذف شدند.
  • متدهای منسوخ‌شده‌ی BillingFlowParams.setAccountId() و BillingFlowParams.setDeveloperId() حذف شدند.
  • متدهای منسوخ‌شده‌ی BillingFlowParams.setOldSkus(String oldSku) و BillingFlowParams.addOldSku(String oldSku) حذف شدند.
  • حاشیه‌نویسی‌های مربوط به قابلیت تهی‌سازی اضافه شد.

رفع اشکالات

  • SkuDetails.getIntroductoryPriceCycles() اکنون به جای String int برمی‌گرداند.
  • اشکالی که باعث می‌شد جریان صورتحساب، حتی اگر هیچ پارامتر اضافی تنظیم نشده بود، به عنوان دارای پارامترهای اضافی در نظر گرفته شود، برطرف شد.

کتابخانه پرداخت گوگل پلی نسخه ۲.۲.۱ (۲۰۲۰-۰۵-۲۰)

نسخه ۲.۲.۱ کتابخانه پرداخت گوگل پلی اکنون در دسترس است.

رفع اشکالات

  • نسخه پیش‌فرض کتابخانه پرداخت Java Play که افزونه Kotlin به آن وابسته است، به‌روزرسانی شد.

انتشار نسخه ۲.۲.۰ کتابخانه پرداخت گوگل پلی و پشتیبانی از یونیتی (۲۰۲۰-۰۳-۲۳)

نسخه ۲.۲.۰ از سیستم پرداخت گوگل پلی، قابلیت‌هایی را ارائه می‌دهد که به توسعه‌دهندگان کمک می‌کند تا اطمینان حاصل کنند که خریدها به کاربر صحیح نسبت داده می‌شوند. این تغییرات جایگزین نیاز به ساخت راه‌حل‌های سفارشی بر اساس بار مفید توسعه‌دهنده می‌شود. به عنوان بخشی از این به‌روزرسانی، قابلیت بار مفید توسعه‌دهنده منسوخ شده و در نسخه‌های آینده حذف خواهد شد. برای اطلاعات بیشتر، از جمله گزینه‌های پیشنهادی، به بخش بار مفید توسعه‌دهنده مراجعه کنید.

کتابخانه پرداخت صورتحساب گوگل پلی ۲ برای یونیتی

علاوه بر نسخه‌های فعلی جاوا و کاتلین از کتابخانه صورتحساب گوگل پلی ۲، ما نسخه‌ای از این کتابخانه را برای استفاده با یونیتی منتشر کردیم. توسعه‌دهندگان بازی که از API خرید درون‌برنامه‌ای یونیتی استفاده می‌کنند، می‌توانند اکنون آن را ارتقا دهند تا از تمام ویژگی‌های کتابخانه صورتحساب گوگل پلی ۲ بهره‌مند شوند و ارتقاءهای بعدی به نسخه‌های آینده کتابخانه صورتحساب گوگل پلی آسان‌تر شود.

برای کسب اطلاعات بیشتر، به استفاده از پرداخت گوگل پلی با یونیتی مراجعه کنید.

خلاصه تغییرات

انتشار نسخه ۲.۱.۰ کتابخانه پرداخت گوگل پلی و نسخه ۲.۱.۰ افزونه کاتلین (۲۰۱۹-۱۲-۱۰)

نسخه ۲.۱.۰ کتابخانه پرداخت گوگل پلی و افزونه جدید کاتلین اکنون در دسترس هستند. افزونه کاتلین کتابخانه پرداخت گوگل پلی، جایگزین‌های API اصطلاحی برای استفاده از کاتلین ارائه می‌دهد که شامل null-safety و coroutineهای بهتری است. برای مثال‌های کد، به Use the Google Play Billing Library مراجعه کنید.

این نسخه شامل تغییرات زیر است.

خلاصه تغییرات

  • در BillingFlowParams ، setOldSku(String oldSku) منسوخ شده و با setOldSku(String oldSku, String purchaseToken) جایگزین شده است تا ابهام‌زدایی شود، زمانی که چندین حساب کاربری روی دستگاه، sku یکسانی دارند.

کتابخانه پرداخت گوگل پلی نسخه ۲.۰.۳ (۲۰۱۹-۰۸-۰۵)

نسخه ۲.۰.۳ کتابخانه پرداخت گوگل پلی اکنون در دسترس است.

رفع اشکالات

  • اشکالی که باعث می‌شد querySkuDetailsAsync() گهگاه با کد DEVELOPER_ERROR به جای بازگرداندن نتیجه‌ی موفقیت‌آمیز، با شکست مواجه شود، برطرف شد.

کتابخانه پرداخت گوگل پلی نسخه ۲.۰.۲ (۲۰۱۹-۰۷-۰۸)

نسخه ۲.۰.۲ کتابخانه پرداخت گوگل پلی اکنون در دسترس است. این نسخه شامل به‌روزرسانی‌هایی در مستندات مرجع است و عملکرد کتابخانه را تغییر نمی‌دهد.

کتابخانه پرداخت گوگل پلی نسخه ۲.۰.۱ (۲۰۱۹-۰۶-۰۶)

نسخه ۲.۰.۱ کتابخانه پرداخت گوگل پلی اکنون در دسترس است. این نسخه شامل تغییرات زیر است.

رفع اشکالات

  • اشکالی که باعث می‌شد پیام‌های اشکال‌زدایی در برخی موارد به null برگردانده شوند، برطرف شد.
  • مشکل نشت حافظه احتمالی برطرف شد.

نسخه ۲.۰ کتابخانه پرداخت گوگل پلی (۲۰۱۹-۰۵-۰۷)

نسخه ۲.۰ کتابخانه پرداخت گوگل پلی اکنون در دسترس است. این نسخه شامل تغییرات زیر است.

خریدها باید ظرف سه روز تأیید شوند

گوگل پلی از خرید محصولات از داخل برنامه شما (درون برنامه) یا خارج از برنامه شما (خارج از برنامه) پشتیبانی می‌کند. برای اینکه گوگل پلی صرف نظر از محل خرید محصول توسط کاربر، یک تجربه خرید پایدار را تضمین کند، باید تمام خریدهای دریافتی را از طریق کتابخانه صورتحساب گوگل پلی در اسرع وقت پس از اعطای حق به کاربر، تأیید کنید. اگر خریدی را ظرف سه روز تأیید نکنید، کاربر به طور خودکار وجه را دریافت می‌کند و گوگل پلی خرید را لغو می‌کند. برای تراکنش‌های در حال انتظار (جدید در نسخه ۲.۰)، بازه سه روزه از زمانی شروع می‌شود که خرید به حالت PURCHASED رسیده باشد و تا زمانی که خرید در حالت PENDING باشد، اعمال نمی‌شود.

برای اشتراک‌ها، باید هر خریدی را که دارای توکن خرید جدید است، تأیید کنید. این بدان معناست که تمام خریدهای اولیه، تغییرات طرح و ثبت نام‌های مجدد باید تأیید شوند، اما نیازی به تأیید تمدیدهای بعدی نیست. برای تعیین اینکه آیا خریدی نیاز به تأیید دارد یا خیر، می‌توانید فیلد تأیید را در خرید بررسی کنید.

شیء Purchase اکنون شامل یک متد isAcknowledged() است که نشان می‌دهد آیا خرید تأیید شده است یا خیر. علاوه بر این، API توسعه‌دهنده Google Play شامل مقادیر بولی تأیید برای هر دو Purchases.products و Purchases.subscriptions است. قبل از تأیید خرید، حتماً از این متدها برای تعیین اینکه آیا خرید قبلاً تأیید شده است یا خیر، استفاده کنید.

شما می‌توانید با استفاده از یکی از روش‌های زیر، خرید خود را تأیید کنید:

  • برای محصولات مصرفی، از consumeAsync() که در API کلاینت موجود است، استفاده کنید.
  • برای محصولاتی که مصرف نمی‌شوند، از acknowledgePurchase() که در API کلاینت موجود است، استفاده کنید.
  • یک متد جدید acknowledge() نیز در API سرور موجود است.

تابع ()BillingFlowParams.setSku حذف شده است.

متد BillingFlowParams#setSku() که قبلاً منسوخ شده بود، در این نسخه حذف شده است. قبل از رندر کردن محصولات در یک جریان خرید، اکنون باید BillingClient.querySkuDetailsAsync() فراخوانی کنید و شیء SkuDetails حاصل را به BillingFlowParams.Builder.setSkuDetails() ارسال کنید.

برای مثال‌های کد، به «استفاده از کتابخانه پرداخت گوگل پلی» مراجعه کنید.

بار توسعه‌دهنده پشتیبانی می‌شود

نسخه ۲.۰ کتابخانه پرداخت گوگل پلی پشتیبانی از payload توسعه‌دهنده را اضافه می‌کند - رشته‌های دلخواهی که می‌توانند به خریدها پیوست شوند. می‌توانید یک پارامتر payload توسعه‌دهنده را به یک خرید پیوست کنید، اما فقط زمانی که خرید تأیید یا مصرف شود. این برخلاف payload توسعه‌دهنده در AIDL است که در آن payload می‌توانست هنگام راه‌اندازی جریان خرید مشخص شود. از آنجا که اکنون خریدها می‌توانند از خارج از برنامه شما آغاز شوند، این تغییر تضمین می‌کند که شما همیشه فرصتی برای اضافه کردن payload به خریدها دارید.

برای دسترسی به payload در کتابخانه جدید، اشیاء Purchase اکنون شامل یک متد getDeveloperPayload() هستند.

پیشنهادات مداوم

وقتی یک SKU تخفیف‌دار ارائه می‌دهید، گوگل پلی اکنون قیمت اصلی SKU را برمی‌گرداند تا بتوانید به کاربران نشان دهید که تخفیف دریافت می‌کنند.

SkuDetails شامل دو متد جدید برای بازیابی قیمت اصلی SKU است:

  • getOriginalPriceAmountMicros()
    • قیمت اصلی و بدون قالب‌بندی SKU قبل از تخفیف را برمی‌گرداند.
  • getOriginalPrice()
    • قیمت اصلی را با قالب‌بندی ارز اضافی برمی‌گرداند.

تراکنش‌های در انتظار

با نسخه ۲.۰ کتابخانه پرداخت گوگل پلی، شما باید از خریدهایی که قبل از اعطای حق، نیاز به اقدامات اضافی دارند، پشتیبانی کنید. به عنوان مثال، ممکن است کاربر تصمیم بگیرد محصول درون برنامه‌ای شما را با استفاده از پول نقد در یک فروشگاه فیزیکی خریداری کند. این بدان معناست که تراکنش خارج از برنامه شما انجام می‌شود. در این سناریو، شما باید حق را فقط پس از تکمیل تراکنش توسط کاربر اعطا کنید.

برای فعال کردن خریدهای در حال انتظار، تابع enablePendingPurchases() به عنوان بخشی از مقداردهی اولیه برنامه خود فراخوانی کنید.

از Purchase.getPurchaseState() برای تعیین اینکه آیا وضعیت خرید PURCHASED است یا PENDING در انتظار خرید) استفاده کنید. توجه داشته باشید که فقط زمانی که وضعیت خرید PURCHASED ) است، باید مجوز خرید (entitle) را اعطا کنید. شما باید با انجام موارد زیر، به‌روزرسانی‌های وضعیت Purchase را بررسی کنید:

  1. هنگام شروع برنامه، برای بازیابی لیست محصولات مصرف نشده مرتبط با کاربر، تابع BillingClient.queryPurchases() را فراخوانی کنید.
  2. Purchase.getPurchaseState() روی هر شیء Purchase که برگردانده می‌شود، فراخوانی کنید.
  3. متد onPurchasesUpdated() را برای پاسخ به تغییرات در اشیاء Purchase پیاده‌سازی کنید.

علاوه بر این، API توسعه‌دهندگان گوگل پلی شامل یک حالت PENDING برای Purchases.products است. تراکنش‌های در حال انتظار برای اشتراک‌ها پشتیبانی نمی‌شوند.

این نسخه همچنین یک نوع اعلان توسعه‌دهنده‌ی بلادرنگ جدید OneTimeProductNotification معرفی می‌کند. این نوع اعلان شامل یک پیام واحد است که مقدار آن یا ONE_TIME_PRODUCT_PURCHASED یا ONE_TIME_PRODUCT_CANCELED است. این نوع اعلان فقط برای خریدهای مرتبط با اشکال پرداخت با تأخیر، مانند پول نقد، ارسال می‌شود.

هنگام تأیید خریدهای در حال انتظار، حتماً فقط زمانی که وضعیت خرید PURCHASED است و نه PENDING در انتظار) را تأیید کنید.

تغییرات API

نسخه ۲.۰ کتابخانه پرداخت گوگل پلی شامل چندین تغییر در API برای پشتیبانی از ویژگی‌های جدید و شفاف‌سازی قابلیت‌های موجود است.

مصرفAsync

consumeAsync() اکنون به جای purchaseToken یک شیء ConsumeParams می‌گیرد. ConsumeParams شامل purchaseToken و همچنین یک payload اختیاری توسعه‌دهنده است.

The previous version of consumeAsync() has been removed in this release.

queryPurchaseHistoryAsync

To minimize confusion, queryPurchaseHistoryAsync() now returns a PurchaseHistoryRecord object instead of a Purchase object. The PurchaseHistoryRecord object is the same as a Purchase object, except that it reflects only the values returned by queryPurchaseHistoryAsync() and does not contain the autoRenewing , orderId , and packageName fields. Note that nothing has changed with the returned data— queryPurchaseHistoryAsync() returns the same data as before.

BillingResult return values

APIs that previously returned a BillingResponse integer value now return a BillingResult object. BillingResult contains the BillingResponse integer as well as a debug string that you can use to diagnose errors. The debug string uses an en-US locale and is not meant to be shown to end users.

رفع اشکالات

Google Play Billing Library 1.2.2 Release (2019-03-07)

Version 1.2.2 of the Google Play Billing library is now available. This version contains the following changes.

رفع اشکالات

  • Fixed a threading issue introduced in v1.2.1. Background calls no longer block the main thread.

تغییرات دیگر

  • Although using the main thread is still recommended, you can now instantiate the Google Play Billing Library from a background thread.
  • Instantiation has been fully migrated to the background thread to reduce the chance of causing ANRs.

Play Billing Library 1.2.1 Release (2019-03-04)

Version 1.2.1 of the Google Play Billing library is now available. This version contains the following changes.

Major changes

تغییرات دیگر

  • Added public constructors for PurchasesResult and SkuDetailsResult to make testing easier.
  • SkuDetails objects can use a new method, getOriginalJson() .
  • All AIDL service calls are now handled by background threads.

رفع اشکالات

  • Null callback listeners are no longer passed into public APIs.

Google Play Billing Library 1.2 Release (2018-10-18)

Version 1.2 of the Google Play Billing library is now available. This version contains the following changes.

Summary of changes

  • The Google Play Billing Library is now licensed under the Android Software Development Kit License Agreement .
  • Added the launchPriceChangeConfirmationFlow API, which prompts users to review a pending change to a subscription price.
  • Added support for a new proration mode, DEFERRED , when upgrading or downgrading a user's subscription.
  • In the BillingFlowParams class, replaced setSku() with setSkuDetails() .
  • Minor bug fixes and code optimizations.

Price change confirmation

You can now change the price of a subscription in Google Play Console and prompt users to review and accept the new price when they enter your app.

To use this API, create a PriceChangeFlowParams object by using the skuDetails of the subscription product, and then call launchPriceChangeConfirmationFlow() . Implement the PriceChangeConfirmationListener to handle the result when the price change confirmation flow finishes, as shown in the following code snippet:

کاتلین 

val priceChangeFlowParams = PriceChangeFlowParams.newBuilder()
    .setSkuDetails(skuDetailsOfThePriceChangedSubscription)
    .build()

billingClient.launchPriceChangeConfirmationFlow(activity,
        priceChangeFlowParams,
        object : PriceChangeConfirmationListener() {
            override fun onPriceChangeConfirmationResult(responseCode: Int) {
                // Handle the result.
            }
        })

جاوا 

PriceChangeFlowParams priceChangeFlowParams =
        PriceChangeFlowParams.newBuilder()
    .setSkuDetails(skuDetailsOfThePriceChangedSubscription)
    .build();

billingClient.launchPriceChangeConfirmationFlow(activity,
        priceChangeFlowParams,
        new PriceChangeConfirmationListener() {
            @Override
            public void onPriceChangeConfirmationResult(int responseCode) {
                // Handle the result.
            }
        });

The price change confirmation flow displays a dialog containing the new pricing information, asking users to accept the new price. This flow returns a response code of type BillingClient.BillingResponse .

New proration mode

When upgrading or downgrading a user's subscription, you can use a new proration mode, DEFERRED . This mode updates the user's subscription when it next renews. To learn more about how to set this proration mode, see Set proration mode .

New method for setting SKU details

In the BillingFlowParams class, the setSku() method has been deprecated. This change serves to optimize the Google Play Billing flow.

When constructing a new instance of BillingFlowParams in your in-app billing client, we recommend that you instead work with the JSON object directly using setSkuDetails() , as shown in the following code snippet:

In the BillingFlowParams Builder class, the setSku() method has been deprecated. Instead, use the setSkuDetails() method, as shown in the following code snippet. The object passed into setSkuDetails() object comes from the querySkuDetailsAsync() method.

کاتلین 

private lateinit var mBillingClient: BillingClient
private val mSkuDetailsMap = HashMap<String, SkuDetails>()

private fun querySkuDetails() {
    val skuDetailsParamsBuilder = SkuDetailsParams.newBuilder()
    mBillingClient.querySkuDetailsAsync(skuDetailsParamsBuilder.build()
    ) { responseCode, skuDetailsList ->
        if (responseCode == 0) {
            for (skuDetails in skuDetailsList) {
                mSkuDetailsMap[skuDetails.sku] = skuDetails
            }
        }
    }
}

private fun startPurchase(skuId: String) {
    val billingFlowParams = BillingFlowParams.newBuilder()
    .setSkuDetails(mSkuDetailsMap[skuId])
    .build()
}

جاوا 

private BillingClient mBillingClient;
private Map<String, SkuDetails> mSkuDetailsMap = new HashMap<>();

private void querySkuDetails() {
    SkuDetailsParams.Builder skuDetailsParamsBuilder
            = SkuDetailsParams.newBuilder();
    mBillingClient.querySkuDetailsAsync(skuDetailsParamsBuilder.build(),
            new SkuDetailsResponseListener() {
                @Override
                public void onSkuDetailsResponse(int responseCode,
                        List<SkuDetails> skuDetailsList) {
                    if (responseCode == 0) {
                        for (SkuDetails skuDetails : skuDetailsList) {
                            mSkuDetailsMap.put(skuDetails.getSku(), skuDetails);
                        }
                    }
                }
            });
}

private void startPurchase(String skuId) {
    BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder()
            .setSkuDetails(mSkuDetailsMap.get(skuId))
            .build();
}

Play Billing Library 1.1 Release (2018-05-07)

Version 1.1 of the Google Play Billing library is now available. This version contains the following changes.

Summary of changes

  • Added support to specify a proration mode in BillingFlowParams when upgrading/downgrading an existing subscription.
  • The replaceSkusProration boolean flag in BillingFlowParams is no longer supported. Use replaceSkusProrationMode instead.
  • launchBillingFlow() now triggers a callback for failed responses.

Behavior changes

Version 1.1 of the Google Play Billing library contains the following behavior changes.

Developers can set replaceSkusProrationMode in BillingFlowParams class

A ProrationMode provides further details on the type of proration when upgrading or downgrading a user's subscription.

کاتلین 

BillingFlowParams.newBuilder()
    .setSku(skuId)
    .setType(billingType)
    .setOldSku(oldSku)
    .setReplaceSkusProrationMode(replaceSkusProrationMode)
    .build()

جاوا 

BillingFlowParams.newBuilder()
    .setSku(skuId)
    .setType(billingType)
    .setOldSku(oldSku)
    .setReplaceSkusProrationMode(replaceSkusProrationMode)
    .build();

Google Play supports following proration modes:

IMMEDIATE_WITH_TIME_PRORATION Replacement takes effect immediately, and the new expiration time will be prorated and credited or charged to the user. This is the current default behavior.
IMMEDIATE_AND_CHARGE_PRORATED_PRICE Replacement takes effect immediately, and the billing cycle remains the same. The price for the remaining period will be charged.

Note : This option is only available for subscription upgrade.

IMMEDIATE_WITHOUT_PRORATION Replacement takes effect immediately, and the new price will be charged on next recurrence time. The billing cycle stays the same.

replaceSkusProration is no longer supported in BillingFlowParams class

Developers used to be able to set a boolean flag to charge a prorated amount for a subscription upgrade request. Given that we are supporting ProrationMode , which contains more detailed proration instruction, this boolean flag is no longer supported.

launchBillingFlow() now triggers a callback for failed responses

The Billing Library will always trigger the PurhcasesUpdatedListener callback and return a BillingResponse asynchronously. The synchronous return value of BillingResponse is kept as well.

رفع اشکالات

  • Properly exits early in async methods when service is disconnected.
  • Builder param objects no longer mutates built objects.
  • Issue 68087141 : launchBillingFlow() now trigger callback for failed responses.

Google Play Billing Library 1.0 Release (2017-09-19, Announcement )

Version 1.0 of the Google Play Billing library is now available. This version contains the following changes.

Important changes

  • Embedded billing permission inside library's manifest. It's not necessary to add the com.android.vending.BILLING permission inside Android manifest anymore.
  • New builder added to BillingClient.Builder class.
  • Introduced builder pattern for SkuDetailsParams class to be used on methods to query SKUs.
  • Several API methods were updated for consistency (the same return argument names and order).

Behavior changes

Version 1.0 of the Google Play Billing library contains the following behavior changes.

BillingClient.Builder class

BillingClient.Builder is now initialized via the newBuilder pattern:

کاتلین 

billingClient = BillingClient.newBuilder(context).setListener(this).build()

جاوا 

billingClient = BillingClient.newBuilder(context).setListener(this).build();

launchBillingFlow method is now called using a BillingFlowParams class

To initiate the billing flow for a purchase or subscription, the launchBillingFlow() method receives a BillingFlowParams instance initialized with parameters specific to the request:

کاتلین 

BillingFlowParams.newBuilder().setSku(skuId)
        .setType(billingType)
        .setOldSku(oldSku)
        .build()

// Then, use the BillingFlowParams to start the purchase flow
val responseCode = billingClient.launchBillingFlow(builder.build())

جاوا 

BillingFlowParams.newBuilder().setSku(skuId)
                              .setType(billingType)
                              .setOldSku(oldSku)
                              .build();

// Then, use the BillingFlowParams to start the purchase flow
int responseCode = billingClient.launchBillingFlow(builder.build());

New way to query available products

Arguments for queryPurchaseHistoryAsync() and querySkuDetailsAsync() methods were wrapped into a Builder pattern:

کاتلین 

val params = SkuDetailsParams.newBuilder()
params.setSkusList(skuList)
        .setType(itemType)
billingClient.querySkuDetailsAsync(params.build(), object : SkuDetailsResponseListener() {
    ...
})

جاوا 

SkuDetailsParams.Builder params = SkuDetailsParams.newBuilder();
params.setSkusList(skuList)
        .setType(itemType);
billingClient.querySkuDetailsAsync(params.build(), new SkuDetailsResponseListener() {...})

The result is now returned via result code and a list of SkuDetails objects instead of previous wrapper class for your convenience and to be consistent across our API:

کاتلین 

fun onSkuDetailsResponse(@BillingResponse responseCode: Int, skuDetailsList: List<SkuDetails>)

جاوا 

public void onSkuDetailsResponse(@BillingResponse int responseCode, List<SkuDetails> skuDetailsList)

Parameters order changed on onConsumeResponse() method

The order of arguments for onConsumeResponse from the ConsumeResponseListener interface has changed to be consistent across our API:

کاتلین 

fun onConsumeResponse(@BillingResponse responseCode: Int, outToken: String)

جاوا 

public void onConsumeResponse(@BillingResponse int responseCode, String outToken)

Unwrapped PurchaseResult object

PurchaseResult has been unwraped to be consistent across our API:

کاتلین 

fun onPurchaseHistoryResponse(@BillingResponse responseCode: Int, purchasesList: List<Purchase>)

جاوا 

void onPurchaseHistoryResponse(@BillingResponse int responseCode, List<Purchase> purchasesList)

رفع اشکالات

Developer Preview 1 Release (2017-06-12, Announcement )

Developer preview launched, aimed to simplify the development process when it comes to billing, allowing developers to focus their efforts on implementing logic specific to the Android app, such as application architecture and navigation structure.

The library includes several convenient classes and features for you to use when integrating your Android apps with the Google Play Billing API. The library also provides an abstraction layer on top of the Android Interface Definition Language (AIDL) service, making it easier for developers to define the interface between the app and the Google Play Billing API.