راهنمای تغییرات اشتراک می 2022، راهنمای تغییرات اشتراک مه 2022، راهنمای تغییرات اشتراک مه 2022، راهنمای تغییرات اشتراک مه 2022

سیستم صورت‌حساب Google Play سرویسی است که به شما امکان می‌دهد محصولات و محتوای دیجیتال را در برنامه Android خود بفروشید. با انتشار می 2022، ما نحوه تعریف محصولات اشتراک را تغییر دادیم و این بر نحوه فروش درون برنامه‌ای و مدیریت آن‌ها در باطن شما تأثیر می‌گذارد. اگر برای اولین بار است که با Google Play Billing ادغام می‌شوید، می‌توانید ادغام خود را با خواندن Reading شروع کنید.

اگر قبل از ماه مه 2022 با Google Play Billing اشتراک می‌فروختید، مهم است که بدانید چگونه می‌توانید ویژگی‌های جدید را با حفظ اشتراک‌های موجود خود بپذیرید.

اولین چیزی که باید بدانید این است که همه اشتراک‌ها، برنامه‌ها و ادغام‌های باطن شما دقیقاً مانند قبل از انتشار می 2022 عمل می‌کنند . شما نیازی به تغییر فوری ندارید و می توانید این ویژگی های جدید را به مرور زمان بپذیرید. هر نسخه اصلی کتابخانه صورت‌حساب Google Play به مدت دو سال پس از انتشار پشتیبانی می‌شود. یکپارچه‌سازی‌های موجود با Google Play Developer API مانند گذشته به کار خود ادامه می‌دهند.

در اینجا مروری بر به‌روزرسانی‌های می 2022 است:

• کنسول جدید Google Play به شما امکان می‌دهد اشتراک‌ها، طرح‌های پایه و پیشنهادات را ایجاد و مدیریت کنید. این شامل هر دو اشتراک جدید و مهاجرت شده است.
• Play Developer API حاوی به‌روزرسانی‌هایی برای پشتیبانی از عملکرد جدید رابط کاربری کنسول Google Play در فرم API است. قابل ذکر است که نسخه جدیدی از API خرید اشتراک وجود دارد. از این API برای بررسی وضعیت اشتراک و مدیریت خریدهای اشتراک استفاده کنید.
• نسخه جدید کتابخانه صورت‌حساب Play به برنامه شما امکان می‌دهد از همه ویژگی‌های اشتراک جدید بهره مند شود. هنگامی که برای ارتقاء به نسخه 5 آماده شدید، راهنمایی های موجود در راهنمای مهاجرت را دنبال کنید.

پیکربندی اشتراک ها

مدیریت اشتراک ها از طریق کنسول Google Play

از ماه می 2022، متوجه تفاوت‌هایی در کنسول Google Play خواهید شد.

اکنون یک اشتراک می تواند چندین طرح و پیشنهاد پایه داشته باشد. SKUهای اشتراکی که قبلا ایجاد شده‌اند اکنون به‌عنوان این اشتراک‌ها، طرح‌های پایه و اشیاء پیشنهادی جدید در کنسول Play ظاهر می‌شوند. اگر قبلاً این کار را نکرده‌اید، تغییرات اخیر در اشتراک‌ها را در Play Console برای توضیح اشیاء جدید، از جمله عملکرد و پیکربندی آنها ببینید. همه محصولات اشتراک قبلی شما در این قالب جدید در کنسول Google Play ظاهر می‌شوند. هر SKU اکنون با یک شی اشتراک نشان داده می شود که در صورت وجود، شامل یک طرح پایه واحد و پیشنهاد سازگار با عقب است.

از آنجایی که ادغام‌های قدیمی‌تر انتظار داشتند که هر اشتراک شامل یک پیشنهاد واحد باشد که توسط یک شیء SkuDetails نشان داده می‌شود، هر اشتراک می‌تواند یک طرح یا پیشنهاد پایه سازگار با عقب را داشته باشد. طرح یا پیشنهاد پایه سازگار با عقب‌نشینی به‌عنوان بخشی از یک SKU برای برنامه‌هایی که از روش querySkuDetailsAsync() استفاده می‌کنند، بازگردانده می‌شود. برای اطلاعات بیشتر در مورد پیکربندی و مدیریت پیشنهادات سازگار با عقب، به درک اشتراک‌ها مراجعه کنید وقتی برنامه شما فقط از queryProductDetailsAsync() استفاده می‌کند، و زمانی که نسخه‌های قدیمی‌تری از برنامه شما هنوز خرید نمی‌کنند، دیگر نیازی به استفاده از پیشنهاد سازگار با نسخه قبلی ندارید. .

مدیریت اشتراک ها از طریق API انتشارات اشتراک

Play Developer API دارای عملکرد جدیدی برای خرید اشتراک است. inappproducts API برای مدیریت SKU مانند گذشته به کار خود ادامه می دهد، از جمله رسیدگی به محصولات خرید یکباره و اشتراک ها، بنابراین برای حفظ یکپارچگی خود نیازی به ایجاد تغییرات فوری ندارید.

با این حال، توجه به این نکته مهم است که کنسول Google Play فقط از موجودیت های اشتراک جدید استفاده می کند. وقتی شروع به ویرایش اشتراک‌های خود در کنسول کنید، دیگر نمی‌توان از inappproducts API برای اشتراک‌ها استفاده کرد .

اگر قبل از می 2022 از Publishing API استفاده کرده‌اید، برای جلوگیری از هر گونه مشکلی، همه اشتراک‌های موجود اکنون به‌عنوان فقط خواندنی در کنسول Google Play ظاهر می‌شوند. اگر بخواهید تغییراتی ایجاد کنید، ممکن است هشداری دریافت کنید که این محدودیت را توضیح می دهد. قبل از ویرایش بیشتر اشتراک‌ها در کنسول، باید ادغام باطن خود را برای استفاده از نقاط پایانی انتشار اشتراک جدید به‌روزرسانی کنید. نقاط پایانی monetization.subscriptions ، monetization.subscriptions.baseplans و monetization.subscriptions.offers جدید به شما این امکان را می دهند که همه طرح ها و پیشنهادات پایه موجود را مدیریت کنید. می‌توانید نحوه نقشه‌برداری فیلدهای مختلف از موجودیت InAppProduct به اشیاء جدید تحت monetization.subscriptions را در جدول زیر ببینید:

InAppProduct	اشتراک
packageName	packageName
sku	productId
status	basePlans[0].state
prices	basePlans[0].regionalConfigs.price
listings	لیست ها
defaultPrice	بدون معادل سازی
subscriptionPeriod	basePlans[0].autoRenewingBasePlanType.billingPeriodDuration
trialPeriod	basePlans[0].offers[0].phases[0].regionalConfigs[0].free
gracePeriod	basePlans[0].autoRenewingBasePlanType.gracePeriodDuration
subscriptionTaxesAndComplianceSettings	taxAndCompliance Settings

این به‌روزرسانی API مورد نیاز فقط برای Publishing API (مدیریت SKU) اعمال می‌شود.

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

برای پشتیبانی از انتقال تدریجی، کتابخانه صورت‌حساب Play شامل تمام روش‌ها و اشیاء موجود در نسخه‌های قبلی است. اشیاء و توابع SkuDetails مانند querySkuDetailsAsync() هنوز وجود دارند، بنابراین می‌توانید برای استفاده از عملکرد جدید بدون نیاز به به‌روزرسانی فوری کد اشتراک‌های موجود، ارتقا دهید. همچنین می‌توانید با علامت‌گذاری آن‌ها به‌عنوان سازگار با عقب، کنترل کنید که کدام پیشنهادها از طریق این روش‌ها در دسترس هستند.

علاوه بر حفظ روش‌های قدیمی، Play Billing Library 5 اکنون شامل یک شی ProductDetails جدید و یک متد queryProductDetailsAsync() مربوطه برای مدیریت موجودیت‌ها و عملکردهای جدید است. محصولات درون‌برنامه‌ای موجود (خریدهای یک‌باره و مواد مصرفی) اکنون توسط ProductDetails نیز پشتیبانی می‌شوند.

برای یک اشتراک، ProductDetails.getSubscriptionOfferDetails() فهرستی از همه طرح های پایه را برمی گرداند و به کاربر پیشنهاد می دهد که واجد شرایط خرید باشد. این بدان معنی است که شما می توانید بدون در نظر گرفتن سازگاری با عقب، به همه طرح ها و پیشنهادات پایه واجد شرایط برای کاربر دسترسی داشته باشید. getSubscriptionOfferDetails() برای محصولات غیر اشتراکی null برمی گرداند. برای خریدهای یک‌باره، می‌توانید از getOneTimePurchaseOfferDetails() استفاده کنید.

Play Billing Library 5 همچنین شامل روش‌های جدید و قدیمی برای راه‌اندازی جریان خرید است. اگر شی BillingFlowParams ارسال شده به BillingClient.launchBillingFlow() با استفاده از یک شیء SkuDetails پیکربندی شود، سیستم اطلاعات پیشنهاد را برای فروش از طرح یا پیشنهاد اولیه سازگار با عقب‌افتاده که با SKU مطابقت دارد استخراج می‌کند. اگر شی BillingFlowParams به BillingClient.launchBillingFlow() با استفاده از اشیاء ProductDetailsParams پیکربندی شود که شامل ProductDetails و String است که نشان دهنده کد پیشنهادی خاص برای پیشنهاد خریداری شده است، سیستم سپس از آن اطلاعات برای شناسایی محصولی که توسط کاربر خریداری شده است استفاده می کند.

queryPurchasesAsync() تمام خریدهای متعلق به کاربر را برمی گرداند. برای نشان دادن نوع محصول درخواستی، می‌توانید مانند نسخه‌های قدیمی‌تر، یک مقدار BillingClient.SkuType یا یک شی QueryPurchasesParams که حاوی یک مقدار BillingClient.ProductType است که موجودیت‌های اشتراک جدید را نشان می‌دهد، ارسال کنید.

توصیه می کنیم به زودی برنامه های خود را به نسخه 5 کتابخانه به روز کنید تا بتوانید از این ویژگی های اشتراک جدید بهره ببرید.

مدیریت وضعیت اشتراک

این بخش تغییرات اولیه اجزای پشتیبان یکپارچه سازی سیستم صورتحساب Google Play را که برای انتقال به نسخه 5 باید اجرا شوند، توضیح می دهد.

اعلان‌های برنامه‌نویس در زمان واقعی

به زودی شیء SubscriptionNotification دیگر حاوی شناسه اشتراک نخواهد بود. اگر برای شناسایی محصول اشتراک به این فیلد متکی هستید، باید پس از دریافت اعلان، این اطلاعات را از وضعیت اشتراک با استفاده از purchases.subscriptionv2:get به‌روزرسانی کنید. هر عنصر SubscriptionPurchaseLineItem در مجموعه lineItems که به عنوان بخشی از وضعیت خرید بازگردانده می‌شود، شامل productId مربوطه خواهد بود.

API خرید اشتراک ها: دریافت وضعیت اشتراک

در نسخه‌های قبلی Subscriptions Purchases API، می‌توانید با استفاده از purchases.subscriptions:get وضعیت اشتراک را جویا شوید. این نقطه پایانی بدون تغییر است و برای خریدهای اشتراک سازگار با عقب مانده به کار خود ادامه می دهد. این نقطه پایانی از هیچ عملکرد جدیدی که در می 2022 منتشر شده است پشتیبانی نمی کند .

در نسخه جدید Subscriptions Purchases 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 : برای طرح های پیش پرداخت وجود ندارد.
• canceled_state_context : برای طرح‌های پیش‌پرداخت وجود ندارد، زیرا این قسمت فقط برای کاربرانی اعمال می‌شود که فعالانه اشتراک را لغو می‌کنند.
• lineItems[0].productId : این فیلد جایگزین subscriptionId از نسخه‌های قبلی می‌شود.

فیلدهای SubscriptionPurchaseV2 برای اشتراک های تکراری

purchases.subscriptionv2 حاوی فیلدهای جدیدی است که جزئیات بیشتری درباره اشیاء اشتراک جدید ارائه می دهد. جدول زیر نحوه فیلدها از نقشه نقطه پایانی اشتراک قدیمی به فیلدهای مربوطه در purchases.subscriptionv2 را نشان می‌دهد.

اشتراک خرید	اشتراک خرید V2
countryCode	regionCode
orderId	latestOrderId
(بدون فیلد معادل)	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 , introductoryPriceInfo	(بدون فیلد معادل) این اطلاعات را می توان در basePlan / offer برای هر یک از اشتراک های خریداری شده یافت.
توسعه دهنده Payload	بار برنامه‌نویس (بدون فیلد معادل) منسوخ شده است
دولت پرداخت	(بدون فیلد معادل) می توانید وضعیت پرداخت را از subscriptionState استنباط کنید: پرداخت در انتظار است: SUBSCRIPTION_STATE_PENDING (خریدهای جدید با تراکنش معلق) SUBSCRIPTION_STATE_IN_GRACE_PERIOD SUBSCRIPTION_STATE_ON_HOLD پرداخت دریافت شده است: SUBSCRIPTION_STATE_ACTIVE آزمایشی رایگان: (بدون فیلد معادل) ارتقا / تنزل معوق: SUBSCRIPTION_STATE_PENDING
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 از خریدها پشتیبانی می‌کند، برمی‌گرداند.