تلقّي الدفعات من خلال خدمة "الفوترة في Google Play" باستخدام Digital Goods API وPayment Request API

André Cipriani Bandarra

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

بالنسبة إلى التطبيقات التي تم إنشاؤها باستخدام أنشطة الويب الموثوق بها وتم طرحها من خلال "متجر Google Play"، أصبح بإمكانك الآن استخدام Payment Request API وDigital Goods API للدمج مع الفوترة في Google Play. وتتوفّر الميزة على الإصدار 101 من Chrome والإصدارات الأحدث لأجهزة Android وChromeOS.

في هذا الدليل، ستتعرّف على كيفية إضافة ميزة "الفوترة في Google Play" إلى تطبيقك المتوافق مع الأجهزة الجوّالة على الويب وحزمه لتوزيعه على "متجر Google Play" لكلٍّ من ChromeOS و"متجر Play".

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

كيفية تحقيق الربح من التطبيقات على "متجر Play"

هناك طريقتان يمكن من خلالهما تحقيق الربح من تطبيقك باستخدام "الفوترة في Google Play" على "متجر Play":

  • تتيح عمليات الشراء داخل التطبيق بيع السلع الافتراضية الدائمة والمستهلكة، مثل ميزات إضافية أو إزالة الإعلانات.
  • الاشتراكات: تتيح للمستخدمين الوصول بشكل مستمر إلى محتوى أو خدمات مقابل رسوم متكررة، مثل الاشتراكات في خدمة الأخبار أو العضويات.

المتطلبات

لإعداد "الفوترة في Google Play"، ستحتاج إلى ما يلي:

تعديل مشروع Bubblewrap

إذا لم يكن تطبيق Bubblewrap مثبّتًا، عليك تثبيته. اطّلِع على دليل البدء السريع لمعرفة تفاصيل عن كيفية البدء. إذا كان لديك Bubblewrap، احرص على تحديثه إلى الإصدار 1.8.2 أو إصدار أحدث.

تتوفّر هذه الميزة أيضًا في Bubblewrap. لأجل تفعيلها، عليك تعديل إعدادات المشروع في twa-manifest.json، التي تقع في جذر المشروع وتفعيل كل من alphaDependencies وميزة playBilling:

  ...,
  "enableNotifications": true,
  "features": {
    "playBilling": {
      "enabled": true
    }
  },
  "alphaDependencies": {
    "enabled": true
  },
  ...

بعد تعديل ملف الإعدادات، يمكنك تشغيل bubblewrap update لتطبيق الإعدادات على المشروع، ثم تشغيل bubblewrap build لإنشاء حزمة Android جديدة وتحميل هذه الحزمة إلى "متجر Play".

ميزة رصد مدى توفّر واجهة برمجة التطبيقات Digital Goods API و"الفوترة في Google Play"

لا يتيح Chrome حاليًا استخدام Digital Goods API إلا عند تنفيذ تطبيق الويب التقدّمي داخل نشاط ويب موثوق به، ويمكن معرفة ما إذا كانت واجهة برمجة التطبيقات متاحة من خلال البحث عن getDigitalGoodsService في عنصر window:

if ('getDigitalGoodsService' in window) {
 // Digital Goods API is supported!
}

قد تكون Digital Goods API متاحة في أي متصفّح وتتوافق مع متاجر مختلفة. للتحقّق مما إذا كان نظام التشغيل الأساسي لمتجر معيّن متوافقًا، عليك استدعاء getDigitalGoodsService() مع تمرير معرّف المتجر كمَعلمة. يتم التعرّف على "متجر Google Play" باستخدام السلسلة https://play.google.com/billing:

if ('getDigitalGoodsService' in window) {
  // Digital Goods API is supported!
  try {
    const service =
        await window.getDigitalGoodsService('https://play.google.com/billing');
    // Google Play Billing is supported!

  } catch (error) {
    // Google Play Billing is not available. Use another payment flow.
    return;
  }
}

استرداد تفاصيل رمز التخزين التعريفي

توفّر Digital Goods API getDetails()، ما يسمح باسترداد معلومات مثل عنوان المنتج ووصفه والأهم من ذلك، السعر، من الخلفية الخاصة بالدفعات.

ويمكنك بعد ذلك استخدام هذه المعلومات في واجهة المستخدم وتقديم المزيد من التفاصيل للمستخدم:

const skuDetails = await service.getDetails(['shiny_sword', 'gem']);
for (item of skuDetails) {
  // Format the price according to the user locale.
  const localizedPrice = new Intl.NumberFormat(
      navigator.language,
      {style: 'currency', currency: item.price.currency}
    ).format(item.price.value);

  // Render the price to the UI.
  renderProductDetails(
        item.itemId, item.title, localizedPrice, item.description);
}

إنشاء مسار الشراء

تأخذ الدالة الإنشائية لطلب الدفع مَعلمتَين: قائمة بطرق الدفع وقائمة باطلاعات الدفع.

عند استخدام ميزة "نشاط الويب الموثوق به"، يجب استخدام طريقة الدفع في الفوترة على Google Play، وذلك من خلال ضبط https://play.google.com/billing على أنّه المعرّف، وإضافة رمز التخزين التعريفي (SKU) للمنتجات كأحد عناصر البيانات:

async function makePurchase(service, sku) {
   // Define the preferred payment method and item ID
   const paymentMethods = [{
       supportedMethods: "https://play.google.com/billing",
       data: {
           sku: sku,
       }
   }];

   ...
}

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

const paymentDetails = {
    total: {
        label: `Total`,
        amount: {currency: `USD`, value: `0`}
    }
};

const request = new PaymentRequest(paymentMethods, paymentDetails);

استخدِم show() في عنصر طلب الدفع لبدء عملية الدفع. إذا تمكّن الوعد من التقدّم، قد يعني ذلك أنّه تم إتمام عملية الدفع بنجاح. إذا تعذّر إكمال الدفع، من المرجّح أنّ المستخدم أوقف الدفع.

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

...
const request = new PaymentRequest(paymentMethods, paymentDetails);
try {
    const paymentResponse = await request.show();
    const {purchaseToken} = paymentResponse.details;

    // Call backend to validate and acknowledge the purchase.
    if (await acknowledgePurchaseOnBackend(purchaseToken, sku)) {
        // Optional: tell the PaymentRequest API the validation was
        // successful. The user-agent may show a "payment successful"
        // message to the user.
        const paymentComplete = await paymentResponse.complete('success');
    } else {
        // Optional: tell the PaymentRequest API the validation failed. The
        // user agent may show a message to the user.
        const paymentComplete = await paymentResponse.complete('fail');
    }
} catch(e) {
    // The purchase failed, and we can handle the failure here. AbortError
    // usually means a user cancellation
}
...

اختياريًا، يمكن استدعاء consume() على purchaseToken لوضع علامة على عملية الشراء على أنّها مُستخدَمة والسماح بشرائها مرة أخرى.

عند تجميع كل العناصر معًا، تظهر طريقة الشراء على النحو التالي:

async function makePurchase(service, sku) {
    // Define the preferred payment method and item ID
    const paymentMethods = [{
        supportedMethods: "https://play.google.com/billing",
        data: {
            sku: sku,
        }
    }];

    // The "total" member of the paymentDetails is required by the Payment
    // Request API, but is not used when using Google Play Billing. We can
    // set it up with bogus details.
    const paymentDetails = {
        total: {
            label: `Total`,
            amount: {currency: `USD`, value: `0`}
        }
    };

    const request = new PaymentRequest(paymentMethods, paymentDetails);
    try {
        const paymentResponse = await request.show();
        const {purchaseToken} = paymentResponse.details;

        // Call backend to validate and acknowledge the purchase.
        if (await acknowledgePurchaseOnBackend(purchaseToken, sku)) {
            // Optional: consume the purchase, allowing the user to purchase
            // the same item again.
            service.consume(purchaseToken);

            // Optional: tell the PaymentRequest API the validation was
            // successful. The user-agent may show a "payment successful"
            // message to the user.
            const paymentComplete =
                    await paymentResponse.complete('success');
        } else {
            // Optional: tell the PaymentRequest API the validation failed.
            // The user agent may show a message to the user.
            const paymentComplete = await paymentResponse.complete('fail');
        }
    } catch(e) {
        // The purchase failed, and we can handle the failure here.
        // AbortError usually means a user cancellation
    }
}

الاطّلاع على حالة عمليات الشراء الحالية

تتيح لك Digital Goods API التحقّق مما إذا كان لدى المستخدم أيّ أذونات حالية (عمليات شراء داخل التطبيق لم يتم استخدامها بعد أو اشتراكات جارية) من عمليات الشراء السابقة التي سبق له إجراؤها، سواء على جهاز آخر أو من عملية تثبيت سابقة أو تم تحصيل قيمتها من رمز ترويجي أو في آخر مرة فتح فيها التطبيق.


const service =
     await window.getDigitalGoodsService('https://play.google.com/billing');
...
const existingPurchases = await service.listPurchases();
for (const p of existingPurchases) {
    // Update the UI with items the user is already entitled to.
    console.log(`Users has entitlement for ${p.itemId}`);
}

هذه أيضًا فرصة جيدة للتحقق من عمليات الشراء التي تم إجراؤها سابقًا ولكن لم يتم الردّ عليها. ننصحك بالاعتراف بعمليات الشراء في أقرب وقت ممكن لضمان أن تظهر أذونات المستخدمين بشكل صحيح في تطبيقك.

const service =
     await window.getDigitalGoodsService("https://play.google.com/billing");
...
const existingPurchases = await service.listPurchases();
for (const p of existingPurchases) {
    await verifyOrAcknowledgePurchaseOnBackend(p.purchaseToken, p.itemId);

    // Update the UI with items the user is already entitled to.
    console.log(`Users has entitlement for ${p.itemId}`);
}

اختبار عملية الدمج

على جهاز Android مخصّص للتطوير

يمكنك تفعيل Digital Goods API على جهاز Android مخصّص للتطوير من أجل الاختبار:

  • تأكَّد من استخدام الإصدار 9 من نظام التشغيل Android أو إصدار أحدث مع تفعيل وضع المطوِّر.
  • ثبِّت الإصدار 101 من Chrome أو إصدارًا أحدث.
  • فعِّل الميزات التجريبية التالية في Chrome من خلال الانتقال إلى chrome://flags والبحث عن الميزة التجريبية بالاسم:
    • #enable-debug-for-store-billing
  • تأكَّد من أنّ الموقع الإلكتروني مستضاف باستخدام بروتوكول https. سيؤدي استخدام http إلى أن تكون واجهة برمجة التطبيقات undefined

على جهاز ChromeOS

ستتوفّر واجهة برمجة التطبيقات Digital Goods API على الإصدار الثابت من ChromeOS اعتبارًا من الإصدار 89. في الوقت الحالي، يمكنك اختبار Digital Goods API:

  • ثبِّت تطبيقك من "متجر Play" على الجهاز.
  • تأكَّد من أنّ الموقع الإلكتروني مستضاف باستخدام بروتوكول https. سيؤدي استخدام http إلى أن تكون واجهة برمجة التطبيقات undefined

مع المستخدمين التجريبيين وفرق تأكيد الجودة

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

ما هي الخطوة التالية؟

كما هو موضّح في هذا المستند، تتضمّن واجهة برمجة التطبيقات Play Billing API مكونات من جهة العميل تديرها واجهة برمجة التطبيقات Digital Goods API ومكونات من جهة الخادم.