קבלת תשלומים דרך חיוב ב-Google Play באמצעות Digital Goods API ו-Payment Request API

אנדרה צ'יפריאני בנדרה
אנדרה צ'יפריאני בנדרה
Twitter GitHub Glitch Mastodon דף הבית

אם האפליקציה שלכם מופצת דרך Google Play, ואתם רוצים למכור מוצרים דיגיטליים או להציע מינויים, עליכם להשתמש בחיוב ב-Google Play. בחיוב ב-Google Play יש כלים לניהול הקטלוג, המחירים והמינויים, דוחות שימושיים ותהליכי תשלום שמופעל על ידי חנות Play שהמשתמשים כבר מכירים.

עכשיו תוכלו לשלב את Payment Request API ואת Digital Goods API עם החיוב ב-Google Play באפליקציות שפותחו באמצעות Trusted Web Activity. היא זמינה ב-Chrome מגרסה 101 ואילך ל-Android ול-ChromeOS.

במדריך הזה נסביר איך להוסיף תמיכה בחיוב ב-Google Play לאפליקציית ה-PWA שלכם, ולארוז אותה להפצה בחנות Google Play גם ל-ChromeOS וגם לחנות Play.

כדי להוסיף תמיכה בחיוב ב-Play ל-PWA, יהיה עליך להשתמש בשני ממשקי API של פלטפורמת אינטרנט. ה-Digital Goods API משמש לאיסוף מידע על מק"טים ולבדוק אם יש רכישות והרשאות בחנות Play. ה-Payment Request API משמש להגדרה של חנות Google Play כאמצעי התשלום ולהשלמת תהליך הרכישה.

איך לייצר הכנסות מאפליקציות בחנות Play

יש שתי דרכים שבהן האפליקציה שלכם יכולה לייצר הכנסות באמצעות חיוב ב-Google Play בחנות Play:

  • רכישות מתוך האפליקציה מאפשרות למכור מוצרים וירטואליים עמידים ומתכלים, כמו תכונות נוספות או להסיר מודעות.
  • מינויים: אתם יכולים להציע למשתמשים גישה קבועה לתוכן או לשירותים בתשלום קבוע, כמו מינויים לחדשות או מינויים.

דרישות

כדי להגדיר חיוב ב-Google Play, צריך:

עדכון הפרויקט של בועות

אם לא התקנת את בועות הבועה, יהיה עליך להתקין אותו. לפרטים כיצד להתחיל, קראו את המדריך למתחילים. אם כבר יש לכם את התכונה 'אריזה בועות', הקפידו לעדכן לגרסה 1.8.2 ואילך.

התכונה 'ניילון בועות' תופיע גם מאחורי דגל. כדי להפעיל אותה, צריך לשנות את הגדרות הפרויקט דרך twa-manifest.json, שנמצאת ברמה הבסיסית (root) של הפרויקט, ולהפעיל גם את 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 רק כשה-PWA מופעל במסגרת פעילות Trusted Web. ניתן לזהות אם הוא זמין באמצעות חיפוש של 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 ואילך ושמצב הפיתוח מופעל.
  • מתקינים את Chrome מגרסה 101 ואילך.
  • כדי להפעיל את הדגלים הבאים ב-Chrome, מנווטים אל chrome://flags ומחפשים את הדגל לפי שם:
    • #enable-debug-for-store-billing
  • יש לוודא שהאתר מתארח בפרוטוקול https. השימוש ב-http יגרום ל-API להיות undefined

במכשיר ChromeOS

Digital Goods API יהיה זמין בגרסה יציבה של ChromeOS החל מגרסה 89. בינתיים, אפשר לבדוק את ה-Digital Goods API:

  • מתקינים את האפליקציה מחנות Play במכשיר.
  • יש לוודא שהאתר מתארח בפרוטוקול https. השימוש ב-http יגרום ל-API להיות undefined

עם משתמשי בדיקה וצוותי בקרת איכות

חנות Play מציעה כסף לבדיקה, כולל חשבונות לבדיקה של משתמשים ומק"טים לבדיקה. מידע נוסף זמין במסמכי התיעוד בנושא בדיקת חיוב ב-Google Play.

מה השלב הבא?

כפי שצוין במסמך הזה, ה-Play Billing API כולל רכיבים בצד הלקוח שמנוהלים על ידי Digital Goods API וגם רכיבים בצד השרת.