با استفاده از Digital Goods API و Payment Request API از طریق Google Play Billing دریافت کنید

آندره سیپریانی بندرا

اگر برنامه شما از طریق Google Play توزیع می‌شود و می‌خواهید کالاهای دیجیتالی بفروشید یا اشتراک ارائه دهید، باید از Google Play Billing استفاده کنید. صورت‌حساب Google Play ابزارهایی را برای مدیریت کاتالوگ، قیمت‌ها و اشتراک‌ها، گزارش‌های مفید و جریان پرداخت ارائه می‌دهد که توسط فروشگاه Play ارائه می‌شود که از قبل برای کاربران شما آشناست.

برای برنامه‌هایی که با استفاده از «فعالیت‌های وب معتمد» ساخته شده‌اند و از طریق «فروشگاه Google Play» ارائه می‌شوند، اکنون می‌توانید از API درخواست پرداخت و API کالاهای دیجیتال برای ادغام با صورت‌حساب Google Play استفاده کنید. در Chrome 101 و بالاتر برای Android و ChromeOS در دسترس است.

در این راهنما، یاد خواهید گرفت که چگونه پشتیبانی Google Play Billing را به PWA خود اضافه کنید و آن را برای توزیع در فروشگاه Google Play برای ChromeOS و Play Store بسته بندی کنید.

برای افزودن پشتیبانی Play Billing به PWA خود از دو API پلتفرم وب استفاده خواهید کرد. Digital Goods API برای جمع‌آوری اطلاعات SKU و بررسی خریدها و حقوق از فروشگاه Play استفاده می‌شود. API درخواست پرداخت برای پیکربندی فروشگاه Google Play به عنوان روش پرداخت و تکمیل جریان خرید استفاده می‌شود.

نحوه کسب درآمد از اپلیکیشن ها در پلی استور

دو راه وجود دارد که برنامه شما می تواند با Google Play Billing در فروشگاه 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 Store آپلود کنید.

قابلیت شناسایی 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;
  }
}

جزئیات یک SKU را بازیابی کنید

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 این مقادیر را نادیده می‌گیرد و از مقادیر تنظیم‌شده هنگام ایجاد SKU در کنسول Play استفاده می‌کند، بنابراین می‌توان آنها را با مقادیر جعلی پر کرد:

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() ممکن است در buyToken فراخوانی شود تا خرید را به‌عنوان مصرف‌شده علامت‌گذاری کند و اجازه دهد دوباره خریداری شود.

با کنار هم قرار دادن همه چیز، یک روش خرید به شکل زیر است:

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}`);
}

ادغام خود را تست کنید

در یک دستگاه اندروید توسعه

امکان فعال کردن Digital Goods API در یک دستگاه اندرویدی توسعه‌یافته برای آزمایش وجود دارد:

  • با فعال بودن حالت برنامه‌نویس، مطمئن شوید که از اندروید 9 یا بالاتر استفاده می‌کنید.
  • Chrome 101 یا جدیدتر را نصب کنید.
  • با رفتن به chrome://flags و جستجوی پرچم بر اساس نام، پرچم‌های زیر را در Chrome فعال کنید:
    • #enable-debug-for-store-billing
  • اطمینان حاصل کنید که سایت با استفاده از پروتکل https میزبانی می شود. استفاده از http باعث می شود که API undefined باشد

در دستگاه ChromeOS

Digital Goods API از نسخه 89 در سیستم عامل ChromeOS پایدار در دسترس خواهد بود. در عین حال، امکان آزمایش Digital Goods API وجود دارد:

  • برنامه خود را از Play Store روی دستگاه نصب کنید.
  • اطمینان حاصل کنید که سایت با استفاده از پروتکل https میزبانی می شود. استفاده از http باعث می شود که API undefined باشد

با کاربران تست و تیم های QA

Play Store امکاناتی را برای آزمایش فراهم می کند، از جمله حساب های آزمایشی کاربر و SKU های آزمایشی. برای اطلاعات بیشتر، اسناد آزمون صورت‌حساب Google Play را بررسی کنید.

بعد کجا برویم؟

همانطور که در این سند بحث شد، Play Billing API دارای اجزای سمت سرویس گیرنده است که توسط Digital Goods API مدیریت می‌شوند و اجزای سمت سرور.