دليل التغييرات التي طرأت على الاشتراكات في شهر أيار (مايو) 2022

نظام الفوترة في Google Play هو خدمة تتيح لك بيع المنتجات الرقمية والمحتوى الرقمي في تطبيق Android. في الإصدار الصادر في أيار (مايو) 2022، غيّرنا طريقة تحديد منتجات الاشتراك، ويؤثر ذلك في طريقة بيعها داخل التطبيق وإدارتها في الخلفية. إذا كنت بصدد دمج نظام الفوترة في Google Play للمرة الأولى، يمكنك بدء عملية الدمج من خلال قراءة مقالة الاستعداد.

إذا كنت تبيع اشتراكات باستخدام "الفوترة في Google Play" قبل أيار (مايو) 2022، من المهم معرفة كيفية استخدام الميزات الجديدة مع الحفاظ على اشتراكاتك الحالية.

أول ما يجب معرفته هو أنّ جميع الاشتراكات والتطبيقات وعمليات الدمج في الخلفية الحالية تعمل كما كانت قبل إصدار مايو (أيار) 2022. لست بحاجة إلى إجراء أي تغييرات فورية، ويمكنك استخدام هذه الميزات الجديدة بمرور الوقت. يستمر دعم كل إصدار رئيسي من مكتبة الفوترة في Google Play لمدة عامَين بعد إصداره. ستظل عمليات الدمج الحالية باستخدام Google Play Developer API تعمل كالمعتاد.

في ما يلي نظرة عامة على التعديلات التي أجريناها في أيار (مايو) 2022:

• تتيح لك Google Play Console الجديدة إنشاء الاشتراكات والخطط الأساسية والعروض وإدارتها. ويشمل ذلك الاشتراكات الجديدة والمُنقلة.
• تتضمّن واجهة برمجة التطبيقات Play Developer API تعديلات تتيح استخدام وظائف واجهة مستخدم Google Play Console الجديدة بتنسيق واجهة برمجة التطبيقات. يُرجى العِلم أنّه يتوفّر إصدار جديد من واجهة برمجة التطبيقات Subscription Purchases API. استخدِم واجهة برمجة التطبيقات هذه للتحقّق من حالة الاشتراك وإدارة عمليات شراء الاشتراكات.
• يتيح الإصدار الجديد من Play Billing Library‏ 5 لتطبيقك الاستفادة من جميع ميزات الاشتراك الجديدة. عندما تكون مستعدًا للترقية إلى الإصدار 5، اتّبِع الإرشادات الواردة في دليل نقل البيانات.

إعداد الاشتراكات

إدارة الاشتراكات من خلال Google Play Console

اعتبارًا من أيار (مايو) 2022، ستلاحظ بعض الاختلافات في Google Play Console.

يمكن أن يتضمّن الاشتراك الواحد الآن عدة خطط أساسية و عروض. تظهر الآن رموز التخزين التعريفية للاشتراكات التي تم إنشاؤها سابقًا في Play Console كعناصر الاشتراك والخطة الأساسية والعرض الجديدة هذه. إذا لم يسبق لك الاطّلاع على مقالة التغييرات الأخيرة على الاشتراكات في Play Console، يمكنك الاطّلاع عليها للحصول على أوصاف عن العناصر الجديدة، بما في ذلك وظائفها وطريقة أعدادها. تظهر جميع منتجات الاشتراكات الحالية في Google Play Console بهذا التنسيق الجديد. يتم الآن تمثيل كل رمز تخزين تعريفي باستخدام كائن اشتراك يحتوي على خطة أساسية واحدة وأحد العروض الترويجية المتوافقة مع الأنظمة القديمة، إن وُجد.

بما أنّ عمليات الدمج القديمة كانت تتوقّع أن يتضمّن كل اشتراك عرضًا واحدًا، ممثّلاً بكائن SkuDetails، يمكن أن يتضمّن كل اشتراك خطة أساسية أو عرضًا ترويجيًا واحدًا متوافقَين مع الإصدارات القديمة. يتم عرض الخطة الأساسية أو العرض المتوافقَين مع الإصدارات القديمة كجزء من رمز التخزين التعريفي للتطبيقات التي تستخدم طريقة querySkuDetailsAsync() المتوقفة نهائيًا. لمزيد من المعلومات حول ضبط العروض المتوافقة مع الإصدارات القديمة وإدارتها، يُرجى الاطّلاع على مقالة فهم الاشتراكات. وبمجرد أن يستخدم تطبيقك الإصدار queryProductDetailsAsync() فقط، ولم يعد هناك إصدارات قديمة من تطبيقك لا تزال تُجري عمليات شراء، لن تحتاج بعد ذلك إلى استخدام عرض متوافق مع الإصدارات القديمة.

إدارة الاشتراكات من خلال واجهة برمجة التطبيقات Subscriptions Publishing API

تتضمّن Play Developer API وظائف جديدة لشراء الاشتراكات. تستمر واجهة برمجة التطبيقات inappproducts لإدارة رموز التخزين التعريفية في العمل كالمعتاد، بما في ذلك التعامل مع المنتجات والاشتراكات التي يتم شراؤها لمرة واحدة، لذا ليس عليك إجراء أي تغييرات فورية للحفاظ على عملية الدمج.

تجدر الإشارة إلى أنّ Google Play Console لا تستخدم سوى ملفّات تعريف الاشتراك الجديدة. بعد بدء تعديل اشتراكاتك في Console، لن يعود بإمكانك استخدام واجهة برمجة التطبيقات inappproducts للإدارة.

إذا كنت قد استخدمت Publishing API قبل أيار (مايو) 2022، لتجنّب أي مشاكل، تظهر الآن أي اشتراكات حالية على أنّها للقراءة فقط في Google Play Console. إذا حاولت إجراء تغييرات، قد يظهر لك تحذير يوضّح هذا الحدّ. قبل إجراء المزيد من التعديلات على الاشتراكات في Play Console، يجب تعديل عملية الدمج في الخلفية لاستخدام نقاط نهاية نشر الاشتراكات الجديدة. تتيح لك نقاط النهاية الجديدة 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	taxAndComplianceSettings

لا ينطبق تحديث واجهة برمجة التطبيقات هذا إلّا على واجهة برمجة التطبيقات Publishing API (إدارة رموز التخزين التعريفية).

التغييرات في "مكتبة الفوترة في Play"

لتسهيل نقل البيانات تدريجيًا، تتضمّن "مكتبة الفوترة في Play" كل ال methods والكائنات المتاحة في الإصدارات السابقة. لا تزال عناصر SkuDetails ووظائف مثل querySkuDetailsAsync() متوفّرة حتى تتمكّن من الترقية لاستخدام الوظائف الجديدة بدون الحاجة إلى تعديل رمز الاشتراكات الحالي على الفور أيضًا. يمكنك أيضًا التحكّم في العروض المتاحة من خلال هذه الطرق من خلال وضع علامة عليها كعروض متوافقة مع الإصدارات القديمة.

بالإضافة إلى الاحتفاظ بالأساليب القديمة، تتضمّن الآن مكتبة Play Billing Library 5 عنصر ProductDetails جديدًا وطريقة queryProductDetailsAsync() مقابلة له من أجل التعامل مع الكيانات والوظائف الجديدة. أصبحت المنتجات الحالية داخل التطبيقات (عمليات الشراء لمرة واحدة والمنتجات الاستهلاكية) متاحة أيضًا في ProductDetails.

بالنسبة إلى الاشتراك، يعرض ProductDetails.getSubscriptionOfferDetails() قائمة بجميع الخطط الأساسية والعروض التي يكون المستخدم مؤهلاً لشرائها. وهذا يعني أنّه يمكنك الوصول إلى جميع الخطط الأساسية والعروض المؤهَّلة للمستخدم، بغض النظر عن التوافق مع الإصدارات القديمة. getSubscriptionOfferDetails() يردّ null مقابل المنتجات التي لا تتطلّب اشتراكًا. بالنسبة إلى عمليات الشراء لمرة واحدة، يمكنك استخدام getOneTimePurchaseOfferDetails().

تتضمّن "مكتبة الفوترة في Play" الإصدار 5 أيضًا طُرقًا جديدة وقديمًا لبدء عملية الشراء. إذا تم ضبط عنصر BillingFlowParams الذي تم تمريره إلى BillingClient.launchBillingFlow() باستخدام عنصر SkuDetails، يستخرج النظام معلومات عرض البيع من الخطة الأساسية أو العرض المتوافقَين مع الإصدارات القديمة ويطابقان رمز التخزين التعريفي. إذا تم ضبط عنصر BillingFlowParams الذي تم تمريره إلى BillingClient.launchBillingFlow() باستخدام عناصر ProductDetailsParams، والتي تتضمّن ProductDetails و String التي تمثّل رمز العرض المحدد للعرض الذي يتم شراؤه، يستخدم النظام بعد ذلك هذه المعلومات لتحديد المنتج الذي يحصل عليه المستخدم.

تعرِض queryPurchasesAsync() جميع عمليات الشراء التي يملكها المستخدم. للإشارة إلى نوع المنتج المطلوب، يمكنك تمرير قيمة BillingClient.SkuType، كما هو الحال في الإصدارات القديمة، أو كائن QueryPurchasesParams يحتوي على قيمة BillingClient.ProductType تمثّل عناصر الاشتراك الجديدة.

ننصحك بتحديث تطبيقاتك إلى الإصدار 5 من المكتبة قريبًا حتى تتمكّن من الاستفادة من ميزات الاشتراك الجديدة هذه.

إدارة حالة الاشتراك

يصف هذا القسم التغييرات الأساسية التي تم إجراؤها على مكوّنات الخلفية في عملية دمج نظام الفوترة في Google Play والتي يجب تنفيذها لنقل بياناتك إلى الإصدار 5.

الإشعارات في الوقت الفعلي الخاصة بالمطوّرين

قريبًا، لن يحتوي كائن SubscriptionNotification على subscriptionId. إذا كنت تعتمد على هذا الحقل لتحديد منتج الاشتراك، عليك تعديله للحصول على هذه المعلومات من حالة الاشتراك باستخدام purchases.subscriptionv2:get بعد تلقّي الإشعار. سيتضمّن كل عنصر SubscriptionPurchaseLineItem في مجموعة lineItems التي يتم عرضها كجزء من حالة الشراء productId المقابل.

Subscriptions Purchases API: الحصول على حالة الاشتراك

في الإصدارات السابقة من واجهة برمجة التطبيقات Subscriptions Purchases API، كان بإمكانك الاستعلام عن حالة الاشتراك باستخدام purchases.subscriptions:get. لم يتم تغيير هذه النهاية ولا تزال تعمل مع عمليات شراء الاشتراكات المتوافقة مع الإصدارات القديمة. لا تتيح نقطة النهاية هذه أي وظائف جديدة تم إصدارها في أيار (مايو) 2022.

في الإصدار الجديد من واجهة برمجة التطبيقات Subscriptions Purchases API، استخدِم purchases.subscriptionsv2:get للحصول على حالة شراء الاشتراك. تتوافق واجهة برمجة التطبيقات هذه مع الاشتراكات التي تم نقلها والاشتراكات الجديدة (كلاهما من النوعَين الدفع المُسبَق والتجديد التلقائي) وعمليات الشراء بجميع أنواعها. يمكنك استخدام هذه النهاية للتحقّق من حالة الاشتراك عند تلقّي الإشعارات. يحتوي العنصر الذي تم إرجاعه، وهو 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.

SubscriptionPurchase	SubscriptionPurchaseV2
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 لكل من الاشتراكات التي تم شراؤها.
developerPayload	(لا يتوفّر حقل مكافئ) تم إيقاف الحمولة البرمجية للمطوّر نهائيًا
paymentState	(لا يتوفّر حقل مكافئ) يمكنك استنتاج حالة الدفع من 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 كما كنت تفعل من قبل.

Pricing API

استخدِم نقطة نهاية monetization.convertRegionPrices لحساب الأسعار على مستوى منطقة معيّنة كما تفعل من خلال Play Console. تقبل هذه الطريقة سعرًا واحدًا بأي ملف ‎ملف عملة يتيحها Play، وتُظهر الأسعار المحوَّلة (بما في ذلك معدّل الضريبة التلقائي عند الاقتضاء) لجميع المناطق التي يتيح فيها Google Play إجراء عمليات الشراء.