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

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

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

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

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

تفعيل طبقة التجريد في عمليات الشراء داخل التطبيق في Unity

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

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

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

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

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

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

   

3. حدِّد المكان الذي نزَّلت فيه ملف .unitypackage واختَره.

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

   

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

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

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

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

   

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

   

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

لتفعيل المكوّن الإضافي، استخدِم المكوّن الإضافي لخدمة "الفوترة في Google Play" بدلاً من تنفيذ عمليات الشراء داخل التطبيق في Unity في Google Play. على سبيل المثال، عند استخدام النص البرمجي لمشتري الشراء داخل التطبيق في Unity، يمكنك تغيير StandardPurchaseModule الذي تم تمريره إلى أداة إنشاء الشراء داخل التطبيق لاستخدام 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());
}

إذا نشرت لعبتك في متاجر تطبيقات أخرى متوافقة مع "متجر Google Play"، عليك استبدال الطريقة التلقائية لعمليات الشراء داخل التطبيق في Unity فقط عند اختيار "متجر 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، بحيث يمكنك استخدام واجهات برمجة تطبيقات Unity نفسها لإدارة سير عمل عمليات الشراء الشائعة. تجدر الإشارة إلى أنّ هناك بعض التغييرات الطفيفة على سلوك واجهة برمجة التطبيقات بسبب الاختلافات بين "مكتبة الفوترة في Google Play" والتنفيذ العادي لعمليات الشراء داخل التطبيق في Unity لمتاجر التطبيقات الأخرى. إذا كنت مبتدئًا في استخدام واجهات برمجة التطبيقات الخاصة بـ Unity IAP، يرجى مراجعة القسم "إنشاء نص برمجي للشراء" في البرنامج التعليمي حول الشراء داخل التطبيق لـ Unity للحصول على مثال حول كيفية تنفيذ عمليات الشراء الأساسية.

وتتضمّن أيضًا "مكتبة الفوترة في Google Play" بعض الميزات الفريدة في "متجر 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، تعمل معظم واجهات برمجة التطبيقات بنفس طريقة تنفيذ الشراء داخل التطبيق القياسي في Unity لمتاجر التطبيقات الأخرى. ومع ذلك، هناك بعض الحالات التي ستعمل فيها واجهات برمجة التطبيقات بشكل مختلف. يصف هذا القسم هذه الاختلافات في السلوك.

حمولة البيانات الخاصة بالمطوّر غير متوافقة

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

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

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

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

لا يمكن استخدام SubscriptionManager.

يوفر الشراء داخل التطبيق في Unity فئة 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);

يمكنك إكمال مكالمة الطريقة هذه بالتحقق من النظام الأساسي أو في مجموعة رموز إذا تم رصد GooglePlayStoreUnsupportedException.

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