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

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

إعداد مكوّن الفوترة في Google Play الإضافي

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

1. تفعيل طبقة التجريد في Unity IAP
2. نزِّل المكوّن الإضافي واستورِده.
3. ضبط إعدادات إنشاء المكوّن الإضافي
4. فعِّل المكوّن الإضافي.

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

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

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

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

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

1. نزِّل أحدث إصدار من Google Play Plugins for Unity من صفحة الإصدارات على GitHub في المستودع.

2. من شريط القوائم في Unity، انقر على مواد العرض (Assets) > استيراد حزمة (Import Package) > حزمة مخصّصة (Custom Package).

   

3. ابحث عن مكان تنزيل ملف .unitypackage واختَره.

4. في مربّع الحوار استيراد حزمة Unity، اترك جميع مواد العرض محدّدة وانقر على استيراد.

   

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

ضبط إعدادات الإنشاء

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

1. من شريط القوائم في Unity، اختَر Google > الفوترة في Play > إعدادات الإصدار.

   

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

   

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

لتفعيل المكوّن الإضافي، استبدِل عملية تنفيذ Unity IAP على Google Play بالمكوّن الإضافي لخدمة "الفوترة في Google Play". على سبيل المثال، عند استخدام 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 Billing Library داخل لعبتك.

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

يتيح 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();

بعد ذلك، نفِّذ عملية ردّ الاتصال الخاصة بعمليات الشراء المؤجّلة باستخدام إضافات "متجر Google 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 Billing Library واجهة برمجة تطبيقات بديلة لاستخدامها بدلاً من هذه الطرق. لترقية اشتراك أو الرجوع إلى إصدار سابق منه، استخدِم طريقة UpdateSubscription() مع وضع التناسب:

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

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

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