קבלת תשלומים דרך חיוב ב-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. היא זמינה ב-Chrome מגרסה 101 ואילך ל-Android ול-ChromeOS.

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

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

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

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

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

דרישות

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

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

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

ב-בועות יש גם את התכונה שמאחורי דגל. לחשבון כדי להפעיל אותו, צריך לשנות את הגדרות הפרויקט בtwa-manifest.json, נמצאים ברמה הבסיסית (root) של הפרויקט ומפעילים את alphaDependencies וגם את playBilling פיצ'ר:

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

כשקובץ התצורה מעודכן, מריצים את הפקודה bubblewrap update כדי להחיל את ההגדרה על ואז bubblewrap build, כדי ליצור חבילת Android חדשה ולהעלות את הקובץ חבילה לחנות Play.

תכונה שמזהה את ה-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);
}

יצירת תהליך הרכישה

ה-constructor של 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() באובייקט של הבקשה לתשלום. אם ההבטחה מצליחה שייתכן שהתשלום יבוצע בהצלחה. אם הפעולה נכשלת, סביר להניח שהמשתמש ביטל את התשלום.

אם ההבטחה מצליחה, יהיה עליך לאמת את הרכישה ולאשר אותה. כדי להגן מפני הונאה, צריך להטמיע את השלב הזה באמצעות הקצה העורפי. כדאי לעיין איך מטמיעים את האימות בקצה העורפי אם לא אישרת את הרכישה, אחרי שלושה ימים, המשתמש יקבל החזר כספי ו-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() באסימון purchase כדי לסמן שהרכישה נוצלה ולאפשר את הרכישה שלו שוב.

כשמשלבים את כל הפרטים, שיטת הרכישה נראית כך:

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

עם משתמשי בדיקה וצוותי QA

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

לאן ממשיכים?

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