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

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

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

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

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

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

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

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

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

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

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

2. من شريط قوائم Unity، انقر على مواد العرض > استيراد الحزمة > حزمة مخصصة.

   

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 IAP في 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());
}

إذا نشرت لعبتك على متاجر أخرى لتطبيقات 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، ما يتيح لك استخدام واجهات برمجة تطبيقات 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();

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

لتمرير معرّف ملف شخصي مشفّر، استخدِم أداة إنشاء IAP لتعديل إعدادات الوحدة من خلال استدعاء طريقة 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

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

الحمولة في حساب المطوّر غير متوافقة.

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

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

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

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

SubscriptionManager غير متاح

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

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

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

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

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

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

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