The Google Play Billing Unity plugin will not be receiving updates moving forward. This means that the plugin will remain specific to Google Play Billing Library 3. Additionally, any apps that are updated after November 1, 2022 will no longer be able to use the plugin.

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

استخدام Google Play Billing Library مع Unity

توسّع إضافة Google Play Billing نطاق الخدمات والأصول المضمّنة في Unity، والتي تُعرف باسم Unity IAP، لتزويد لعبتك بجميع أحدث ميزات مكتبة Google Play Billing Library. يوضّح هذا الدليل كيفية إعداد مشروعك لاستخدام المكوّن الإضافي. يوضّح هذا الدليل أيضًا كيفية تنفيذ ميزات Google Play Billing Library في لعبتك باستخدام Unity.

إعداد مكوّن Google Play Billing الإضافي

لإعداد المكوّن الإضافي، أكمل الخطوات الواردة في كلّ من الأقسام المرتبطة التالية:

تفعيل طبقة التجريد في Unity IAP
نزِّل المكوّن الإضافي واستورِده.
ضبط إعدادات الإصدار الخاصة بالإضافة
فعِّل المكوّن الإضافي.

تفعيل طبقة تجريد Unity IAP

تم إنشاء إضافة Google Play Billing على طبقة تجريد مضمّنة في Unity IAP، لذا عليك تفعيل طبقة التجريد هذه قبل تنزيل الإضافة واستيرادها. لتفعيل طبقة تجريد Unity IAP، اتّبِع الخطوات التالية:

أكمِل جميع الخطوات الواردة في البرنامج التعليمي التالي من Unity: إعداد مشروعك لخدمات Unity.
أكمِل جميع الخطوات الواردة في البرنامج التعليمي التالي على Unity: تفعيل خدمة Unity IAP.

تنزيل المكوّن الإضافي واستيراده

يتم شحن المكوّن الإضافي كحزمة Unity بتنسيق .unitypackage. لتنزيل المكوّن الإضافي واستيراده، اتّبِع الخطوات التالية:

نزِّل أحدث إصدار من Google Play Plugins for Unity من صفحة الإصدارات على GitHub في المستودع.
من شريط قائمة Unity، انقر على Assets (مواد العرض) > Import Package (استيراد حزمة) > Custom Package (حزمة مخصّصة).
ابحث عن مكان تنزيل ملف .unitypackage واختَره.
في مربّع الحوار استيراد حزمة Unity، اترك جميع مواد العرض محدّدة وانقر على استيراد.

بعد استيراد الحزمة، تتم إضافة مجلد جديد باسم GooglePlayPlugins (في جذر مجلد Assets) إلى مواد عرض مشروعك. يحتوي هذا المجلد على جميع مواد عرض Google Play Billing Library الخاصة بالمكوّن الإضافي.

ضبط إعدادات الإصدار

بما أنّ المكوّن الإضافي يوسّع نطاق Unity IAP، سيواجه Unity تعارضات ولن يتمكّن من إنشاء حزمة APK لنظام Android ما لم تتم إزالة بعض التبعيات القديمة المتداخلة في Unity IAP من الإصدار. توفّر الإضافة طريقة تلقائية لإزالة المكتبات المتعارضة من مشروعك. لحلّ هذه التعارضات، اتّبِع الخطوات التالية:

من شريط قائمة Unity، اختَر Google > الفوترة في Play > إعدادات الإصدار.
في نافذة "إعدادات الإصدار في Play Billing"، انقر على إصلاح. يؤدي ذلك إلى حل التعارض ونقل ملفات Unity IAP المتعارضة إلى دليل احتياطي. بعد النقر على إصلاح، يتغيّر الزر إلى استعادة، ويمكنك النقر عليه لاستعادة الملفات الأصلية المتعارضة.

تفعيل المكوّن الإضافي

لتفعيل المكوّن الإضافي، استبدِل عملية تنفيذ Unity IAP على Google Play بالمكوّن الإضافي Google Play Billing. على سبيل المثال، عند استخدام Unity IAP Purchaser Script، عليك تغيير StandardPurchaseModule الذي يتم تمريره إلى أداة إنشاء IAP لاستخدام Google.Play.Billing.GooglePlayStoreModule:

// Create a builder using the GooglePlayStoreModule.
var configurationBuilder =
    ConfigurationBuilder.Instance(Google.Play.Billing.GooglePlayStoreModule.Instance());

إذا كانت لعبتك تستخدم النص البرمجي نفسه الخاص بالمشتري على منصات متعددة، عليك إضافة عملية تحقّق من المنصة للتأكّد من أنّ Unity ستواصل استخدام حلّها الخاص بالشراء داخل التطبيق على المنصات الأخرى:

ConfigurationBuilder builder;
if (Application.platform == RuntimePlatform.Android)
{
  builder = ConfigurationBuilder.Instance(
      Google.Play.Billing.GooglePlayStoreModule.Instance());
}
else
{
  builder = ConfigurationBuilder.Instance(StandardPurchasingModule.Instance());
}

إذا نشرت لعبتك على متاجر أخرى لتطبيقات Android غير "متجر Google Play"، عليك استبدال عملية التنفيذ التلقائية لواجهة برمجة التطبيقات Unity IAP فقط عند اختيار "متجر Google Play":

ConfigurationBuilder builder;
if (Application.platform == RuntimePlatform.Android
       && SelectedAndoidAppStore == AppStore.GooglePlay)
{
  builder = ConfigurationBuilder.Instance(
      Google.Play.Billing.GooglePlayStoreModule.Instance());
}
else
{
  builder = ConfigurationBuilder.Instance(StandardPurchasingModule.Instance());
}

تنفيذ ميزات Google Play Billing Library في لعبتك

توسّع إضافة "الفوترة في Google Play" نطاق خدمات Unity IAP، ما يتيح لك استخدام واجهات برمجة التطبيقات نفسها من Unity لإدارة سير عمل عمليات الشراء الشائعة. يُرجى العِلم أنّ هناك بعض التغييرات الطفيفة في سلوك واجهة برمجة التطبيقات بسبب الاختلافات بين Google Play Billing Library وتنفيذ Unity العادي لميزة "الشراء داخل التطبيق" في متاجر التطبيقات الأخرى. إذا كنت جديدًا على واجهات برمجة التطبيقات Unity IAP، يمكنك الاطّلاع على قسم "إنشاء نص برمجي لعملية شراء" في برنامج Unity IAP التعليمي للحصول على مثال حول كيفية تنفيذ عمليات الشراء الأساسية.

تتضمّن Google Play Billing Library أيضًا بعض الميزات التي لا تتوفّر إلا في "متجر Google Play". يمكنك الوصول إلى هذه الميزات من خلال واجهة موسّعة. يوضّح الجزء المتبقي من هذا القسم كيفية تنفيذ هذه الميزات الفريدة في "مكتبة الفوترة في Google Play" داخل لعبتك.

تفعيل عمليات الشراء المؤجّلة

يتيح Google Play عمليات الشراء المؤجّلة، والتي تُعرف أيضًا باسم المعاملات المعلّقة أو عمليات الشراء المعلّقة، حيث يمكن للمستخدمين إنشاء عملية شراء وإكمالها لاحقًا باستخدام النقد في المتاجر.

لتفعيل عمليات الشراء المؤجّلة، استخدِم أداة إنشاء عمليات الشراء داخل التطبيق لتعديل إعدادات الوحدة من خلال استدعاء الطريقة EnableDeferredPurchase():

// Create a builder using a GooglePlayStoreModule.
var configurationBuilder =
    ConfigurationBuilder.Instance(Google.Play.Billing.GooglePlayStoreModule.Instance());
// Enable deferred purchases
configurationBuilder.Configure<Google.Play.Billing.IGooglePlayConfiguration>()
    .EnableDeferredPurchase();

بعد ذلك، نفِّذ عملية ردّ الاتصال الخاصة بعمليات الشراء المؤجّلة باستخدام إضافات "متجر Play":

// Get the plugin extensions for the Google Play Store.
_playStoreExtensions =
    extensions.GetExtension<Google.Play.Billing.IGooglePlayStoreExtensions>();

// Set the deferred purchases callback.
_playStoreExtensions.SetDeferredPurchaseListener(
    delegate(Product product)
    {
        // Do not grant the item here. Instead, record the purchase and remind
        // the user to complete the transaction in the Play Store.
    });

إرسال أرقام تعريف الحسابات التي تم إخفاء تشويشها إلى Google Play

يمكنك إرسال أرقام تعريف حسابات المستخدمين التي تم تشويشها إلى Google Play لتسهيل رصد إساءة الاستخدام، مثل رصد ما إذا كانت العديد من الأجهزة تجري عمليات شراء من الحساب نفسه خلال فترة زمنية قصيرة.

لتمرير رقم تعريف حساب تم إخفاء تشويشه، استخدِم طريقة SetObfuscatedAccountId() من واجهة برمجة التطبيقات الخاصة بالإضافات:

// Get the plugin extensions for the Google Play Store.
_playStoreExtensions =
    extensions.GetExtension<Google.Play.Billing.IGooglePlayStoreExtensions>();

// Pass an obfuscated account ID.
_playStoreExtensions.SetObfuscatedAccountId(obfuscatedAccountId);

إرسال أرقام تعريف الملفات الشخصية التي تم إخفاء مفاتيح فك تشفيرها إلى Google Play

يمكنك تمرير معرّف ملف شخصي مبهم إلى Google Play لتسهيل رصد الاحتيال، مثل رصد ما إذا كانت أجهزة متعددة تجري عمليات شراء على الحساب نفسه خلال فترة زمنية قصيرة. وهذا يشبه تمرير معرّف حساب مستخدم مشفّر. في كلتا الحالتين، يمثّل المعرّف مستخدمًا واحدًا، ولكن يتيح لك معرّف الملف الشخصي تحديد مستخدم واحد بشكلٍ فريد على مستوى عدّة ملفات شخصية لديه في تطبيق واحد. وبعد إرسال معرّف ملف شخصي مبهم إلى Google Play، يمكنك استرداد هذا المعرّف لاحقًا في إيصال الشراء.

لتمرير معرّف ملف شخصي تم تشويشه، استخدِم أداة إنشاء عمليات الشراء داخل التطبيق لتعديل إعدادات الوحدة من خلال استدعاء الطريقة SetObfuscatedProfileId():

// Get the plugin extensions for the Google Play Store.
_playStoreExtensions =
    extensions.GetExtension<Google.Play.Billing.IGooglePlayStoreExtensions>();

// Pass an obfuscated profile ID.
_playStoreExtensions.SetObfuscatedProfileId(obfuscatedProfileId);

تأكيد تغييرات أسعار الاشتراكات

يتيح لك Google Play تغيير سعر اشتراك نشط. يجب أن يؤكّد مستخدمو لعبتك أي تغيير في السعر قبل أن يصبح ساريًا. لطلب تأكيد من المستخدمين على تغيير سعر اشتراكهم، استخدِم طريقة ConfirmSubscriptionPriceChange():

// Get the plugin extensions for the Google Play Store.
_playStoreExtensions =
    extensions.GetExtension<Google.Play.Billing.IGooglePlayStoreExtensions>();

_playStoreExtensions.ConfirmSubscriptionPriceChange(productId,
    delegate (bool success)
    {
        // Returns whether the user has accepted the new price or not.
    });

تغييرات في سلوك Unity API

عند استخدام إضافة Google Play Billing، تتشابه معظم واجهات برمجة التطبيقات مع عملية التنفيذ العادية لميزة "الشراء داخل التطبيق" في Unity على متاجر التطبيقات الأخرى. ومع ذلك، هناك بعض الحالات التي ستتغير فيها طريقة عمل واجهات برمجة التطبيقات. يوضّح هذا القسم الاختلافات في السلوك.

حمولة المطوّر غير متاحة

أوقف Google Play نهائيًا استخدام حمولة المطوّر واستبدلها ببدائل أكثر فائدة وملاءمة للسياق. لهذا السبب، لا تتوافق حمولة المطوّر مع هذه الميزة. لمزيد من المعلومات حول البدائل، يمكنك الاطّلاع على صفحة حمولة المطوّر.

يمكنك مواصلة استخدام الواجهات نفسها التي يحدّدها التنفيذ العادي لميزة "الشراء داخل التطبيق" من Unity لمتاجر التطبيقات الأخرى، بما في ذلك IStoreController. عند بدء عملية شراء، سيظل بإمكانك استخدام IStoreController واستدعاء الطريقة InitiatePurchase():

public void InitiatePurchase(Purchasing.Product product, string payload);

ومع ذلك، لن يتم تطبيق أي حمولة تمرّرها (لن تظهر في الإيصال النهائي).

SubscriptionManager غير متاح

توفّر Unity IAP الفئة SubscriptionManager لإدارة الاشتراكات. بما أنّ عملية التنفيذ العادية لعمليات الشراء داخل التطبيق في Unity لهذه الفئة تستخدم حمولة المطوّر، لا تتوافق هذه الفئة مع عمليات الشراء داخل التطبيق. سيظل بإمكانك إنشاء هذه الفئة، ولكن قد تتلقّى بيانات غير موثوقة عند استخدام أي من طرق الحصول على البيانات الخاصة بالفئة.

تتضمّن UpdateSubscription تغييرات بسيطة في واجهة برمجة التطبيقات

لا يتيح مكوّن "الفوترة في Google Play" الإضافي استخدام الطريقتَين SubscriptionManager.UpdateSubscription() وSubscriptionManager.UpdateSubscriptionInGooglePlayStore() لترقية اشتراكاتك وخفض مستوى اشتراكك. إذا كانت لعبتك تستدعي هذه الطرق، سيتم عرض الخطأ GooglePlayStoreUnsupportedException.

توفّر "مكتبة الفوترة في Google Play" واجهة برمجة تطبيقات بديلة لاستخدامها بدلاً من هذه الطرق. لترقية اشتراك أو الرجوع إلى إصدار سابق منه، استخدِم طريقة UpdateSubscription() مع تفعيل وضع التسوية النسبية:

void UpdateSubscription(Product oldProduct, Product newProduct,
           GooglePlayStoreProrationMode prorationMode = GooglePlayStoreProrationMode.Unknown);

يمكنك إما تضمين استدعاء الطريقة هذا في عملية التحقّق من النظام الأساسي أو في كتلة catch عند رصد GooglePlayStoreUnsupportedException.

لمزيد من المعلومات وأمثلة حول كيفية استخدام وضع التناسب، اطّلِع على ضبط وضع التناسب.