سیستم پرداخت گوگل پلی سرویسی است که به شما امکان میدهد محصولات و محتوای دیجیتال را در برنامه اندروید خود بفروشید. با انتشار نسخه مه 2022، نحوه تعریف محصولات اشتراکی را تغییر دادهایم و این بر نحوه فروش درون برنامهای و مدیریت آنها در بکاند شما تأثیر میگذارد. اگر برای اولین بار است که با پرداخت گوگل پلی ادغام میشوید، میتوانید ادغام خود را با خواندن بخش «آماده شدن» آغاز کنید.
اگر قبل از ماه مه ۲۰۲۲ با استفاده از Google Play Billing اشتراک میفروشید، مهم است که بدانید چگونه ضمن حفظ اشتراکهای فعلی خود، ویژگیهای جدید را نیز به کار بگیرید.
اولین چیزی که باید بدانید این است که تمام اشتراکها، برنامهها و ادغامهای بکاند موجود شما درست مانند قبل از انتشار مه ۲۰۲۲ عمل میکنند . نیازی به ایجاد تغییرات فوری نیست و میتوانید این ویژگیهای جدید را به مرور زمان به کار بگیرید. هر نسخه اصلی کتابخانه پرداخت گوگل پلی به مدت دو سال پس از انتشار پشتیبانی میشود. ادغامهای موجود با API توسعهدهندگان گوگل پلی همچنان مانند قبل عمل میکنند.
در اینجا مروری بر بهروزرسانیهای ماه مه ۲۰۲۲ داریم:
- کنسول جدید گوگل پلی به شما امکان میدهد اشتراکها، طرحهای پایه و پیشنهادات را ایجاد و مدیریت کنید. این شامل اشتراکهای جدید و اشتراکهای منتقلشده میشود.
- API توسعهدهندگان Play شامل بهروزرسانیهایی برای پشتیبانی از قابلیتهای جدید رابط کاربری کنسول Google Play در قالب API است. نکته قابل توجه، نسخه جدیدی از API خرید اشتراک است. از این API برای بررسی وضعیت اشتراک و مدیریت خریدهای اشتراک استفاده کنید.
- نسخه ۵ کتابخانه جدید پرداخت گوگل پلی به برنامه شما اجازه میدهد از تمام ویژگیهای جدید اشتراک بهرهمند شود. وقتی آماده ارتقا به نسخه ۵ شدید، دستورالعملهای موجود در راهنمای مهاجرت را دنبال کنید.
پیکربندی اشتراکها
مدیریت اشتراکها از طریق کنسول گوگل پلی
از ماه مه ۲۰۲۲، متوجه برخی تفاوتها در کنسول گوگل پلی خواهید شد.
اکنون یک اشتراک میتواند چندین طرح پایه و پیشنهاد داشته باشد. SKU های اشتراکی که قبلاً ایجاد شدهاند، اکنون در کنسول Play به عنوان این اشیاء جدید اشتراک، طرح پایه و پیشنهاد ظاهر میشوند. اگر قبلاً این کار را نکردهاید، برای توضیحات اشیاء جدید، از جمله عملکرد و پیکربندی آنها، به تغییرات اخیر در اشتراکها در کنسول Play مراجعه کنید. همه محصولات اشتراکی موجود شما در کنسول Google Play با این قالب جدید ظاهر میشوند. هر SKU اکنون توسط یک شیء اشتراک نمایش داده میشود که شامل یک طرح پایه واحد و پیشنهاد سازگار با نسخههای قبلی، در صورت وجود، است.
از آنجایی که ادغامهای قدیمیتر انتظار داشتند هر اشتراک شامل یک پیشنهاد واحد باشد که توسط یک شیء SkuDetails نمایش داده میشد، هر اشتراک میتواند یک طرح یا پیشنهاد پایه سازگار با نسخههای قبلی داشته باشد. طرح یا پیشنهاد پایه سازگار با نسخههای قبلی به عنوان بخشی از یک SKU برای برنامههایی که از متد querySkuDetailsAsync() که اکنون منسوخ شده است استفاده میکنند، بازگردانده میشود. برای اطلاعات بیشتر در مورد پیکربندی و مدیریت پیشنهادهای سازگار با نسخههای قبلی، به بخش درک اشتراکها مراجعه کنید. هنگامی که برنامه شما فقط از queryProductDetailsAsync() استفاده میکند و هنگامی که هیچ نسخه قدیمیتری از برنامه شما هنوز خرید انجام نمیدهد، دیگر نیازی به استفاده از یک پیشنهاد سازگار با نسخههای قبلی ندارید.
مدیریت اشتراکها از طریق API انتشار اشتراکها
رابط برنامهنویسی کاربردی توسعهدهندگان Play شامل قابلیتهای جدیدی برای خرید اشتراک است. رابط برنامهنویسی کاربردی inappproducts برای مدیریت SKU همچنان مانند قبل کار میکند، از جمله مدیریت محصولات خریداریشده یکبارمصرف و اشتراکها، بنابراین نیازی به ایجاد تغییرات فوری برای حفظ یکپارچگی خود ندارید.
با این حال، توجه به این نکته مهم است که کنسول گوگل پلی فقط از موجودیتهای اشتراک جدید استفاده میکند. به محض اینکه شروع به ویرایش اشتراکهای خود در کنسول کنید، دیگر نمیتوان از API inappproducts برای اشتراکها استفاده کرد .
اگر قبل از ماه مه ۲۰۲۲ از Publishing API استفاده کردهاید، برای جلوگیری از هرگونه مشکل، هرگونه اشتراک موجود اکنون به صورت فقط خواندنی در کنسول Google Play ظاهر میشود. اگر سعی در ایجاد تغییرات داشته باشید، ممکن است هشداری در مورد این محدودیت دریافت کنید. قبل از ویرایش بیشتر اشتراکها در کنسول، باید ادغام backend خود را برای استفاده از نقاط پایانی جدید Subscription Publishing بهروزرسانی کنید. نقاط پایانی جدید monetization.subscriptions ، monetization.subscriptions.baseplans و monetization.subscriptions.offers به شما امکان میدهند تمام طرحها و پیشنهادات پایه موجود را مدیریت کنید. میتوانید در جدول زیر ببینید که چگونه فیلدهای مختلف از موجودیت InAppProduct به اشیاء جدید زیر monetization.subscriptions میشوند:
| محصول InApp | اشتراک |
|---|---|
packageName | packageName |
sku | productId |
status | basePlans[0].state |
prices | basePlans[0].regionalConfigs.price |
listings | فهرستها |
defaultPrice | بدون معادلسازی |
subscriptionPeriod | basePlans[0].autoRenewingBasePlanType.billingPeriodDuration |
trialPeriod | طرحهای پایه[0]. پیشنهادات[0]. فازها[0]. پیکربندیهای منطقهای[0]. رایگان |
gracePeriod | basePlans[0].autoRenewingBasePlanType.gracePeriodDuration |
subscriptionTaxesAndComplianceSettings | تنظیمات مالیات و انطباق |
این بهروزرسانی API مورد نیاز فقط برای API انتشار (مدیریت SKU) اعمال میشود.
تغییرات کتابخانه پرداخت Play
برای پشتیبانی از مهاجرت تدریجی، کتابخانهی پرداخت Play شامل تمام متدها و اشیاء موجود در نسخههای قبلی است. اشیاء و توابع SkuDetails مانند querySkuDetailsAsync() هنوز وجود دارند، بنابراین میتوانید بدون نیاز به بهروزرسانی فوری کد اشتراکهای موجود، برای استفاده از قابلیتهای جدید ارتقا دهید. همچنین میتوانید با علامتگذاری آنها به عنوان سازگار با نسخههای قبلی، کنترل کنید که کدام پیشنهادات از طریق این متدها در دسترس هستند.
علاوه بر حفظ متدهای قدیمی، کتابخانه صورتحساب Play 5 اکنون شامل یک شیء جدید ProductDetails و یک متد queryProductDetailsAsync() متناظر برای مدیریت موجودیتها و قابلیتهای جدید است. محصولات درون برنامهای موجود (خریدهای یکبار مصرف و اقلام مصرفی) نیز اکنون توسط ProductDetails پشتیبانی میشوند.
برای اشتراک، ProductDetails.getSubscriptionOfferDetails() فهرستی از تمام طرحها و پیشنهادهای پایهای که کاربر واجد شرایط خرید آنهاست را برمیگرداند. این بدان معناست که شما میتوانید به تمام طرحها و پیشنهادهای پایهای که برای کاربر واجد شرایط هستند، صرف نظر از سازگاری با نسخههای قبلی، دسترسی داشته باشید. تابع getSubscriptionOfferDetails() برای محصولات غیر اشتراکی null را برمیگرداند. برای خریدهای یکباره، میتوانید getOneTimePurchaseOfferDetails() استفاده کنید.
کتابخانه صورتحساب Play 5 همچنین شامل هر دو روش جدید و قدیمی برای راهاندازی جریان خرید است. اگر شیء BillingFlowParams ارسال شده به BillingClient.launchBillingFlow() با استفاده از یک شیء SkuDetails پیکربندی شده باشد، سیستم اطلاعات پیشنهاد فروش را از طرح پایه یا پیشنهاد سازگار با نسخههای قبلی که مربوط به SKU است، استخراج میکند. اگر شیء BillingFlowParams ارسال شده به BillingClient.launchBillingFlow() با استفاده از اشیاء ProductDetailsParams پیکربندی شده باشد، که شامل ProductDetails و یک String است که نشان دهنده توکن پیشنهاد خاص برای پیشنهاد خریداری شده است، سیستم سپس از آن اطلاعات برای شناسایی محصولی که توسط کاربر خریداری میشود استفاده میکند.
queryPurchasesAsync() تمام خریدهای متعلق به کاربر را برمیگرداند. برای نشان دادن نوع محصول درخواستی، میتوانید مانند نسخههای قدیمیتر، یک مقدار BillingClient.SkuType یا یک شیء QueryPurchasesParams که حاوی مقدار BillingClient.ProductType است و نشاندهندهی موجودیتهای اشتراک جدید است، ارسال کنید.
توصیه میکنیم برنامههای خود را به نسخه ۵ کتابخانه بهروزرسانی کنید تا بتوانید از این ویژگیهای اشتراک جدید بهرهمند شوید.
مدیریت وضعیت اشتراک
این بخش تغییرات اولیه در اجزای backend یکپارچهسازی سیستم پرداخت Google Play را که برای مهاجرت به نسخه ۵ باید پیادهسازی شوند، شرح میدهد.
اعلانهای توسعهدهنده در لحظه
به زودی شیء SubscriptionNotification دیگر حاوی subscriptionId نخواهد بود. اگر برای شناسایی محصول اشتراکی به این فیلد تکیه میکنید، باید پس از دریافت اعلان، با استفاده از purchases.subscriptionv2:get آن را بهروزرسانی کنید تا این اطلاعات را از وضعیت اشتراک به دست آورید. هر عنصر SubscriptionPurchaseLineItem در مجموعه lineItems که به عنوان بخشی از وضعیت خرید بازگردانده میشود، شامل productId مربوطه خواهد بود.
API خرید اشتراکها: دریافت وضعیت اشتراک
در نسخههای قبلی API خرید اشتراکها، میتوانستید وضعیت اشتراک را با استفاده از purchases.subscriptions:get پرسوجو کنید. این نقطه پایانی بدون تغییر مانده و همچنان برای خریدهای اشتراک سازگار با نسخههای قبلی کار میکند. این نقطه پایانی از هیچ قابلیت جدیدی که در ماه مه 2022 منتشر شده است، پشتیبانی نمیکند .
در نسخه جدید API خرید اشتراکها، purchases.subscriptionsv2:get برای دریافت وضعیت خرید اشتراک استفاده کنید. این API با اشتراکهای منتقلشده، اشتراکهای جدید (هم پیشپرداخت و هم تمدید خودکار) و انواع خریدها سازگار است. میتوانید از این نقطه پایانی برای بررسی وضعیت اشتراک هنگام دریافت اعلانها استفاده کنید. شیء برگرداندهشده، SubscriptionPurchaseV2 ، شامل فیلدهای جدید است، اما همچنان شامل دادههای قدیمی است که برای ادامه پشتیبانی از اشتراکهای موجود مورد نیاز است.
فیلدهای SubscriptionPurchaseV2 برای طرحهای پیشپرداخت
فیلدهای جدیدی برای پشتیبانی از طرحهای پیشپرداخت اضافه شدهاند که به جای تمدید خودکار، توسط کاربر تمدید میشوند. همه فیلدها برای طرحهای پیشپرداخت نیز مانند اشتراکهای تمدید خودکار اعمال میشوند، به جز موارد استثنای زیر:
- [فیلد جدید] lineItems[0].prepaid_plan.allowExtendAfterTime : نشان میدهد که چه زمانی به کاربر اجازه داده میشود برای تمدید طرح پیشپرداخت خود، یک اعتبار دیگر خریداری کند، زیرا هر کاربر مجاز است فقط یک اعتبار مصرف نشده در هر زمان داشته باشد.
- [فیلد جدید] SubscriptionState : وضعیت شیء اشتراک را مشخص میکند. برای طرحهای پیشپرداخت، این مقدار همیشه
ACTIVE،PENDINGیاCANCELEDاست. - lineItems[0].expiryTime : این فیلد همیشه برای طرحهای پیشپرداخت وجود دارد.
- paused_state_context : این فیلد هرگز وجود ندارد، زیرا طرحهای پیشپرداخت نمیتوانند متوقف شوند.
- lineItems[0].auto_renewing_plan : برای طرحهای پیشپرداخت ارائه نمیشود.
- cancel_state_context : برای طرحهای پیشپرداخت وجود ندارد، زیرا این فیلد فقط برای کاربرانی اعمال میشود که بهطور فعال اشتراک را لغو میکنند.
- lineItems[0].productId : این فیلد جایگزین
subscriptionIdاز نسخههای قبلی میشود.
فیلدهای SubscriptionPurchaseV2 برای اشتراکهای دورهای
purchases.subscriptionv2 شامل فیلدهای جدیدی است که جزئیات بیشتری در مورد اشیاء اشتراک جدید ارائه میدهند. جدول زیر نشان میدهد که چگونه فیلدها از نقطه پایانی اشتراک قدیمی به فیلدهای مربوطه در purchases.subscriptionv2 نگاشت میشوند.
| اشتراکخرید | اشتراکخرید نسخه ۲ |
|---|---|
countryCode | regionCode |
orderId | latestOrderId |
| (فیلد معادل ندارد) | lineItems.offerPhase (مرحله فعلی را مشخص میکند: دوره آزمایشی رایگان، قیمت مقدماتی، نسبت قیمت به قیمت، قیمت پایه) |
| (فیلد معادل ندارد) | lineItems (لیست SubscriptionPurchaseLineItem ) که نشان دهنده محصولات خریداری شده با خرید است |
| (فیلد معادل ندارد) | lineItems.offerDetails.basePlanId |
| (فیلد معادل ندارد) | lineItems.offerDetails.offerId |
| (فیلد معادل ندارد) | lineItems.offerDetails.offerTags |
startTimeMillis | startTime |
expiryTimeMillis | lineItems.expiryTime (هر اشتراکی که در خرید به دست میآید، expiryTime مخصوص به خود را دارد) |
| (فیلد معادل ندارد) | subscriptionState ( وضعیت اشتراک را نشان میدهد) |
| (فیلد معادل ندارد) | pausedStateContext (فقط در صورتی وجود دارد که وضعیت اشتراک SUBSCRIPTION_STATE_PAUSED باشد) |
autoResumeTimeMillis | pausedStateContext.autoResumeTime |
| (فیلد معادل ندارد) | canceledStateContext (فقط در صورتی وجود دارد که وضعیت اشتراک SUBSCRIPTION_STATE_CANCELED باشد) |
| (فیلد معادل ندارد) | testPurchase (فقط در خریدهای تستر دارای مجوز موجود است) |
autoRenewing | lineItems.autoRenewingPlan.autoRenewEnabled |
priceCurrenceCode ، priceAmountMicros | lineItems.autoRenewingPlan.recurringPrice |
introductoryPriceInfo | lineItems.offerPhase.introductoryPriceاین اطلاعات همچنین در offer مربوط به هر یک از اشتراکهای خریداری شده قابل مشاهده است. |
| developerPayload | (فیلد معادلی وجود ندارد) payload توسعهدهنده منسوخ شده است |
| پرداخت ایالتی | (فیلد معادل ندارد) شما میتوانید وضعیت پرداخت را از subscriptionState استنباط کنید:
|
cancelReason ، userCancellationTimeMillis ، cancelSurveyResult | canceledStateContext |
linkedPurchaseToken | linkedPurchaseToken (بدون تغییر) |
purchaseType | تست: از طریق testPurchaseتبلیغات: signupPromotion |
priceChange | lineItems.autoRenewingPlan.priceChangeDetails |
profileName ، emailAddress ، givenName ، familyName ، profileId | subscribeWithGoogleInfo |
acknowledgementState | acknowledgementState (no change) |
promotionType ، promotionCode | signupPromotion |
externalAccountId ، obfuscatedExternalAccountId خارجی، obfuscatedExteranlProfileId | externalAccountIdentifiers |
سایر عملکردهای مدیریت اشتراک
در حالی که purchases.subscriptions:get به purchases.subscriptionsv2:get ارتقا یافته است، بقیه توابع مدیریت اشتراک توسعهدهندگان فعلاً در نقطه پایانی purchases.subscriptions بدون تغییر باقی میمانند، بنابراین میتوانید مانند قبل به استفاده از purchases.subscriptions:acknowledge ، purchases.subscriptions:cancel ، purchases.subscriptions:defer ، purchases.subscriptions:refund و purchases.subscriptions:revoke ادامه دهید.
API قیمتگذاری
از نقطه پایانی monetization.convertRegionPrices برای محاسبه قیمتهای منطقهای، همانطور که از طریق کنسول Play انجام میدهید، استفاده کنید. این روش یک قیمت واحد را با هر ارزی که Play از آن پشتیبانی میکند، میپذیرد و قیمتهای تبدیلشده (از جمله نرخ مالیات پیشفرض در صورت وجود) را برای همه مناطقی که Google Play از خریدها پشتیبانی میکند، برمیگرداند.