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

André Cipriani Bandarra

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

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

ستتعرّف في هذا الدليل على كيفية إضافة دعم "الفوترة في Google Play" إلى تطبيق الويب التقدّمي (PWA) وتجميعه في في "متجر Google Play" على كل من نظام التشغيل ChromeOS و"متجر Play".

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

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

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

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

المتطلبات

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

تعديل مشروع فقاعة المحادثة

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

وتشمل أداة فقاعة تفسيرية الميزة خلف العلم. ضِمن لتفعيله، عليك تعديل إعدادات المشروع في "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"

لا تتوافق واجهة برمجة التطبيقات Digital Goods API حاليًا مع متصفِّح Chrome إلا عند تنفيذ تطبيق الويب التقدّمي (PWA) داخل نشاط الويب الموثوق به، ويمكن اكتشاف ما إذا كان متاحًا عن طريق التحقق من 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);
}

بناء تدفق الشراء

تأخذ دالة إنشاء PaymentRequest معلمتين وهما: قائمة طرق الدفع وقائمة تفاصيل الدفع.

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

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 للتطوير من أجل الاختبار:

  • تأكَّد من استخدام نظام التشغيل Android 9 أو الإصدارات الأحدث مع تفعيل "وضع مطوّر البرامج".
  • ثبِّت الإصدار 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 مكونات من جهة العميل تتم إدارتها. بواسطة واجهة برمجة تطبيقات السلع الرقمية، والمكونات من جهة الخادم.