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

استخدام "الفوترة في Google Play"

André Cipriani Bandarra

Adriana Jara

تاريخ النشر: 2 كانون الأول (ديسمبر) 2020

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

تتضمّن Google Play Billing API مصطلحات خاصة بها، كما تتضمّن مكونات العميل والخلفية. لا يتناول هذا القسم سوى جزء صغير من واجهة برمجة التطبيقات المخصّص لاستخدام واجهتَي برمجة التطبيقات Digital Goods API وTrusted Web Activity. احرص على قراءة مستندات الفوترة في Google Play وفهم مفاهيمها قبل دمجها في تطبيق إنتاج.

الخطوات الأساسية

لتوفير سلع رقمية من خلال "متجر Play"، عليك ضبط قائمة منتجاتك على "متجر Play" وربط "متجر Play" كطريقة دفع من تطبيقك المتوافق مع الأجهزة الجوّالة (PWA).

يمكنك إجراء ذلك في واجهة "متجر Play" باتّباع الخطوات التالية:

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

يمكنك إضافة منتجاتك باستخدام Play Developers API إذا أردت ذلك.

بعد ضبط الكتالوج، تكون الخطوة التالية هي ضبط عملية الدفع من تطبيق الويب التقدّمي. يجب استخدام مزيج من Digital Goods API وPayment Request API.

استرجاع سعر المنتج باستخدام Digital Goods API

عند استخدام "الفوترة في Google Play"، تأكَّد من أنّ السعر المعروض للمستخدمين يتطابق مع السعر الوارد في بطاقة بيانات المتجر. سيكون من المستحيل مزامنة هذه الأسعار يدويًا، لذلك، تقدّم Digital Goods API طريقة لتطبيق الويب من أجل الاستعلام عن الأسعار من مقدّم الدفع الأساسي:

// The SKU for the product, as defined in the Play Store interface
async function populatePrice(sku) {
  try {
    // Check if the Digital Goods API is supported by the browser.
    if (window.getDigitalGoodsService) {
      // The Digital Goods API can be supported by other Payments provider.
      // In this case, we're retrieving the Google Play Billing provider.
      const service =
          await window.getDigitalGoodsService("https://play.google.com/billing");

      // Fetch product details using the `getDetails()` method.
      const details = await service.getDetails([sku]);

      if (details.length === 0) {
        console.log(`Could not get SKU: "${sku}".`);
        return false;
      }

      // The details contain both the price and the currenncy.
      item = details[0];
      const value = item.price.value;
      const currency = item.price.currency;

      const formattedPrice = new Intl.NumberFormat(navigator.language, {
        style: 'currency', currency: currency }).format(value);

      // Display the price to the user.
      document.getElementById("price").innerHTML = formattedPrice;
    } else {
      console.error("Could not get price for SKU \"" + sku + "\".");
    }
  } catch (error) {
    console.log(error);
  }
  return false;
}

يمكنك رصد مدى توفّر Digital Goods API من خلال التحقّق مما إذا كان getDigitalGoodsService() متاحًا في عنصر window.

بعد ذلك، عليك طلب window.getDigitalGoodsService() باستخدام معرّف "الفوترة في Google Play" كمَعلمة. يؤدي ذلك إلى عرض مثيل خدمة لخدمة "الفوترة في Google Play"، ويمكن للمورّدين الآخرين توفير دعم لـ Digital Goods API واستخدام معرّفات مختلفة.

أخيرًا، يمكنك استدعاء getDetails() على مرجع كائن "الفوترة في Google Play" مع تمرير رمز التخزين التعريفي للسلعة كمَعلمة. تُعرِض الطريقة عنصرًا تفصيليًا يحتوي على كلّ من السعر والقيمة لعملة السلعة التي يمكن عرضها للمستخدم.

بدء مسار الشراء

تتيح Payment Request API عمليات الشراء على الويب، كما تُستخدَم أيضًا لدمج ميزة "الفوترة داخل التطبيقات على Google Play". اطّلِع على مقالة طريقة عمل Payment Request API للحصول على مزيد من المعلومات إذا كنت مبتدئًا في استخدام Payment Request API.

لاستخدام واجهة برمجة التطبيقات مع "الفوترة في Google Play"، عليك إضافة أداة دفع، التي تتضمّن طريقة متوافقة تُعرف باسم https://play.google.com/billing. أضِف رمز التخزين التعريفي كجزء من بيانات الأداة:

const supportedInstruments = [{
  supportedMethods: "https://play.google.com/billing",
  data: {
    sku: sku
  }
}];

بعد ذلك، أنشئ عنصر PaymentRequest كالمعتاد واستخدِم واجهة برمجة التطبيقات كالمعتاد.

const request = new PaymentRequest(supportedInstruments, details);

الإقرار بعملية الشراء

بعد اكتمال المعاملة، يمكنك استخدام Digital Goods API للموافقة على الدفع. يحتوي كائن الاستجابة من PaymentRequest على رمز مميّز يمكنك استخدامه للإقرار بالمعاملة:

const response = await request.show();
const token = response.details.token;
const service = await window.getDigitalGoodsService("https://play.google.com/billing");
await service.acknowledge(token, 'onetime');

لا تملك Digital Goods API وPayment Request API معلومات عن هوية المستخدم. ونتيجةً لذلك، يعود إليك خيار ربط عملية الشراء بالمستخدم في الخلفية الخاصة بك والتأكّد من إمكانية وصوله إلى العناصر التي تم شراؤها. عند ربط عملية الشراء بمستخدم، احرص على حفظ الرمز المميّز لعملية الشراء، لأنّك قد تحتاج إليه للتحقّق مما إذا تم إلغاء عملية الشراء أو ردّ الأموال المدفوعة أو ما إذا كان الاشتراك لا يزال نشطًا. راجِع واجهة برمجة التطبيقات لـ "إشعارات في الوقت الفعلي خاصة بالمطوّرين" وواجهة برمجة التطبيقات Google Play Developer API للاطّلاع على نقاط نهاية للتعامل مع هذه الحالات في الخلفية.

التحقّق من الأذونات الحالية

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

const purchases = await itemService.listPurchases();
for (p of purchases) {
  if (!p.acknowledged) {
    await itemService.acknowledge(p.purchaseToken, 'onetime');
  }
}