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

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

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

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

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

• يتيح لك الإصدار الجديد من Google Play Console إنشاء الاشتراكات والخطط الأساسية والعروض وإدارتها. ويشمل ذلك الاشتراكات الجديدة والاشتراكات التي تم نقلها.
• تحتوي Play Developer API على تحديثات لإتاحة وظائف واجهة مستخدم Google Play Console الجديدة على شكل واجهة برمجة تطبيقات. هناك إصدار جديد من واجهة برمجة تطبيقات عمليات شراء الاشتراكات. يمكنك استخدام واجهة برمجة التطبيقات هذه للاطّلاع على حالة الاشتراك وإدارة عمليات شراء الاشتراكات.
• يتيح الإصدار 5 من Play Billing Library الجديد لتطبيقك الاستفادة من جميع ميزات الاشتراك الجديدة. عندما تكون مستعدًا للترقية إلى الإصدار 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 تستخدم عناصر الاشتراك الجديدة فقط. بعد البدء في تعديل اشتراكاتك في وحدة التحكم، لن يعود من الممكن استخدام inappproducts واجهة برمجة التطبيقات للاشتراكات.

إذا سبق لك استخدام واجهة Publishing API قبل أيار (مايو) 2022، لتجنُّب حدوث أي مشاكل، ستظهر الآن أي اشتراكات حالية للقراءة فقط في Google Play Console. وإذا حاولت إجراء تغييرات، قد تتلقى تحذيرًا يوضّح هذا القيد. قبل إجراء المزيد من عمليات تعديل الاشتراكات في وحدة التحكم، عليك تحديث عملية دمج الخلفية لاستخدام نقاط نهاية النشر الجديدة للاشتراك. تتيح لك نقاط النهاية monetization.subscriptions وmonetization.subscriptions.baseplans وmonetization.subscriptions.offers الجديدة إدارة جميع الخطط الأساسية والعروض الترويجية المتاحة. يمكنك الاطّلاع على كيفية ربط الحقول المختلفة من الكيان InAppProduct بالعناصر الجديدة ضِمن monetization.subscriptions في الجدول التالي:

منتج داخل التطبيق	الاشتراك
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 Billing Library

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

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

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

تتضمن Play Billing Library 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 المقابل.

واجهة برمجة تطبيقات عمليات شراء الاشتراكات: معرفة حالة الاشتراك

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

في الإصدار الجديد من واجهة برمجة تطبيقات عمليات شراء الاشتراكات، استخدِم الرمز purchases.subscriptionsv2:get للاطّلاع على حالة شراء الاشتراك. تتوافق واجهة برمجة التطبيقات هذه مع الاشتراكات التي تم نقلها والاشتراكات الجديدة (سواء المدفوعة مسبقًا والتجديد التلقائي) وعمليات الشراء من جميع الأنواع. يمكنك استخدام نقطة النهاية هذه للتحقّق من حالة الاشتراك عند تلقّي الإشعارات. يحتوي الكائن المعروض، SubscriptionPurchaseV2، على حقول جديدة، ولكنه لا يزال يتضمن البيانات القديمة اللازمة لمواصلة إتاحة الاشتراكات الحالية.

حقول SubscriptionPurchaseV2 لخطط الدفع المُسبَق

تمت إضافة حقول جديدة لإتاحة خطط الدفع المُسبق التي يمدِّدها المستخدم بدلاً من تجديدها تلقائيًا. تنطبق جميع الحقول على خطط الدفع المُسبق كما هو الحال مع الاشتراكات التي تتجدّد تلقائيًا، مع الاستثناءات التالية:

• [New field] lineItems[0].prepaid_plan.allowExtendAfterTime: تشير هذه السمة إلى الوقت الذي يُسمح فيه للمستخدم بشراء رصيد آخر من أجل تمديد خطة الدفع المُسبق، حيث يُسمح للمستخدم بإضافة إضافة واحدة فقط غير مستخدَمة في الوقت نفسه.
• [New field] 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.

شراء اشتراك	شراء الاشتراك الإصدار 2
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 لكل اشتراك تم شراؤه.
حمولة المطوّرين	(ما من حقل مكافئ) تم إيقاف حمولة البيانات الخاصة بالمطوّرين
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 العرض الترويجي: (لا يوجد حقل مكافئ) قريبًا
priceChange	lineItems.autoRenewingPlan.priceChangeDetails
profileName، emailAddress، givenName، familyName، profileId	subscribeWithGoogleInfo
acknowledgementState	acknowledgementState (no change)
promotionType، promotionCode	(لا يتوفّر حقل مكافئ) قريبًا
externalAccountId، obfuscatedExternalAccountId، obfuscatedExteranlProfileId	externalAccountIdentifiers

وظائف أخرى لإدارة الاشتراك

على الرغم من ترقية purchases.subscriptions:get إلى purchases.subscriptionsv2:get، لم يتم تغيير بقية وظائف إدارة اشتراك المطوّرين في الوقت الحالي في نقطة النهاية purchases.subscriptions، وبالتالي يمكنك مواصلة استخدام purchases.subscriptions:acknowledge وpurchases.subscriptions:cancel وpurchases.subscriptions:defer وpurchases.subscriptions:refund و{20 }purchases.subscriptions:revoke

واجهة برمجة تطبيقات التسعير

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