استخدام "الفوترة في Google Play" في "النشاط الموثوق به على الويب"

André Cipriani Bandarra

هذا الدليل مخصّص لتطبيقات الويب التي يتم تجميعها كـ نشاط موثوق به على الويب. بالنسبة إلى تطبيقات Android المكتوبة بلغة Kotlin أو Java، يُرجى الاطّلاع على مستندات الفوترة في Google Play.

يجب أن تستخدم التطبيقات على Google Play التي تبيع سلعًا رقمية أو اشتراكات خدمة "الفوترة في Google Play". في "النشاط الموثوق به على الويب"، يمكنك دمجها باستخدام واجهات برمجة التطبيقات التالية على الويب، والمتاحة في الإصدار 101 من Chrome والإصدارات الأحدث على Android وChromeOS:

المتطلبات

لإعداد خدمة "الفوترة في Google Play"، يجب توفُّر ما يلي:

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

تفعيل خدمة "الفوترة في Play" في مشروع Android

إذا أنشأت تطبيقك باستخدام Bubblewrap، فعِّل ميزة playBilling في twa-manifest.json في جذر مشروعك:

"features": {
  "playBilling": {
    "enabled": true
  }
}

بعد ذلك، شغِّل bubblewrap update متبوعًا بـ bubblewrap build، وحمِّل حزمة Android الجديدة إلى "متجر Google Play".

إذا كنت تنشئ تطبيقك في "استوديو Android"، أضِف مكتبة Android Browser Helper Play Billing. للاطّلاع على التغييرات المطلوبة في DelegationService وAndroidManifest.xml، يُرجى مشاهدة العرض التوضيحي لـ twa-play-billing.

التحقّق من توفّر خدمة "الفوترة في Google Play"

يمكنك الاتصال بـ "getDigitalGoodsService()" باستخدام معرّف "متجر Google Play"، https://play.google.com/billing. إذا لم تكن الطريقة متوفّرة أو تعذّر تنفيذ الطلب، استخدِم مسار دفع آخر:

if ('getDigitalGoodsService' in window) {
  try {
    const service =
        await window.getDigitalGoodsService('https://play.google.com/billing');
    // Google Play Billing is available.
  } catch (error) {
    // Google Play Billing isn't available. Use another payment flow.
  }
}

عرض تفاصيل المنتج

استخدِم getDetails() لاسترداد العنوان والوصف والسعر لمعرّفات المنتجات، بحيث تتطابق الأسعار التي تعرضها مع "متجر Google Play":

const details = await service.getDetails(['shiny_sword', 'gem']);
for (const item of details) {
  const localizedPrice = new Intl.NumberFormat(
      navigator.language,
      {style: 'currency', currency: item.price.currency}
  ).format(item.price.value);

  renderProductDetails(
      item.itemId, item.title, localizedPrice, item.description);
}

لا يمكن لواجهة برمجة تطبيقات السلع الرقمية عرض معرّفات منتجاتك. لطلبها من الخلفية، استخدِم Google Play Developer API.

إجراء عملية شراء

أنشِئ PaymentRequest باستخدام https://play.google.com/billing كطريقة الدفع ومعرّف المنتج كـ sku في data. تستخدم الفوترة في Google Play السعر من Play Console، لذا فإنّ total مطلوب ولكن يتم تجاهله.

بعد حلّ show()، أرسِل الرمز المميّز للشراء إلى الخلفية للتحقّق من عملية الشراء والإقرار بها. إذا لم يتم الإقرار بإتمام الشراء في غضون ثلاثة أيام، فسيتم ردّ الأموال تلقائيًا إلى المستخدم وسيلغي Google Play عملية الشراء.

async function makePurchase(service, sku) {
  const paymentMethods = [{
    supportedMethods: 'https://play.google.com/billing',
    data: {sku},
  }];
  // Required by the Payment Request API, but ignored by Google Play Billing.
  const paymentDetails = {
    total: {label: 'Total', amount: {currency: 'USD', value: '0'}},
  };

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

    if (await acknowledgePurchaseOnBackend(purchaseToken, sku)) {
      // Optional: consume the purchase so the user can buy the item again.
      await service.consume(purchaseToken);
      await response.complete('success');
    } else {
      await response.complete('fail');
    }
  } catch (error) {
    // An AbortError usually means the user canceled the purchase.
  }
}

التحقّق من عمليات الشراء التي أجراها مستخدم

استخدِم listPurchases() للعثور على العناصر التي يملكها المستخدم، مثل الاشتراكات النشطة أو عمليات الشراء غير المستهلكة أو الرموز الترويجية التي تم تحصيل قيمتها. تحقَّق من كل عملية شراء في الخلفية، وأكِّد استلام أي عملية شراء لم تؤكّد استلامها:

const purchases = await service.listPurchases();
for (const p of purchases) {
  await verifyOrAcknowledgePurchaseOnBackend(p.purchaseToken, p.itemId);
  // Update the UI with items the user is entitled to.
}

اختبار عملية التكامل

لاختبار التطبيق على جهاز Android قبل نشره على "متجر Google Play"، اتّبِع الخطوات التالية:

  1. استخدام الإصدار 9 من نظام التشغيل Android أو إصدار أحدث مع تفعيل خيارات المطوّرين
  2. في Chrome، انتقِل إلى chrome://flags وفعِّل #enable-debug-for-store-billing.
  3. عرض موقعك الإلكتروني عبر بروتوكول HTTPS واجهة برمجة تطبيقات السلع الرقمية غير متاحة عبر بروتوكول HTTP.

عند تثبيت تطبيقك من "متجر Google Play"، لن تحتاج إلى العلامة. للاختبار باستخدام حسابات اختبارية ومنتجات اختبارية، يُرجى الاطّلاع على اختبار دمج Google Play Billing Library.

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