Получайте платежи через биллинг Google Play с помощью API цифровых товаров и API запроса платежей.

Андре Сиприани Бандарра

Если ваше приложение распространяется через Google Play и вы хотите продавать цифровые товары или предлагать подписки, вам необходимо использовать Google Play Billing . Google Play Billing предлагает инструменты для управления вашим каталогом, ценами и подписками, полезные отчеты и процесс оформления заказа на базе Play Store, который уже знаком вашим пользователям.

Для приложений, созданных с использованием Trusted Web Activity и доставленных через Google Play Store, теперь вы можете использовать API запросов платежей и API цифровых товаров для интеграции с Google Play Billing. Он доступен в Chrome 101 и более поздних версиях для Android и ChromeOS.

В этом руководстве вы узнаете, как добавить поддержку Google Play Billing в свой PWA и упаковать его для распространения в Google Play Store как для ChromeOS, так и для Play Store.

Вы будете использовать два API веб-платформы, чтобы добавить поддержку Play Billing в свой PWA. API цифровых товаров используется для сбора информации о SKU и проверки покупок и прав в Play Store. API запроса платежа используется для настройки Google Play Store в качестве способа оплаты и завершения процесса покупки.

Как монетизировать приложения в Play Store

Существует два способа монетизации вашего приложения с помощью Google Play Billing в Play Store:

  • Покупки в приложении позволяют продавать как долговечные, так и расходные виртуальные товары, такие как дополнительные функции или удаление рекламы.
  • Подписки предлагают вашим пользователям постоянный доступ к контенту или услугам за регулярную плату, например подписку на новости или членство.

Требования

Чтобы настроить биллинг 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.

Функция обнаружения API цифровых товаров и доступности Google Play Billing.

API цифровых товаров в настоящее время поддерживается Chrome только тогда, когда PWA выполняется внутри доверенной веб-активности, и можно определить, доступен ли он, проверив getDigitalGoodsService в объекте window :

if ('getDigitalGoodsService' in window) {
 // Digital Goods API is supported!
}

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

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 в качестве идентификатора и добавив 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 Billing будет игнорировать эти значения и использовать значения, установленные при создании SKU в Play Console, поэтому они могут быть заполнены фиктивными значениями:

const paymentDetails = {
    total: {
        label: `Total`,
        amount: {currency: `USD`, value: `0`}
    }
};

const request = new PaymentRequest(paymentMethods, paymentDetails);

Вызовите show() для объекта запроса платежа, чтобы начать поток платежей. Если обещание выполнено, возможно, платеж прошел успешно. Если это не удалось, пользователь, скорее всего, отменил платеж.

Если обещание выполнено, вам нужно будет подтвердить и подтвердить покупку. Чтобы защититься от мошенничества, этот шаг необходимо реализовать с помощью вашего бэкэнда. Ознакомьтесь с документацией Play Billing, чтобы узнать, как внедрить проверку в свою серверную часть . Если вы не подтвердите покупку, через три дня пользователь получит возмещение, а 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
    }
}

Проверьте статус существующих покупок

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 для разработки

API цифровых товаров можно включить на разрабатываемом устройстве Android для тестирования:

  • Убедитесь, что вы используете Android 9 или более позднюю версию с включенным режимом разработчика .
  • Установите Chrome 101 или новее.
  • Включите следующие флаги в Chrome, перейдя по адресу chrome://flags и выполнив поиск флага по имени:
    • #enable-debug-for-store-billing
  • Убедитесь, что сайт размещен по протоколу https. Использование http приведет к тому, что API станет undefined

На устройстве ChromeOS

API цифровых товаров будет доступен в стабильной версии ChromeOS, начиная с версии 89. А пока можно протестировать API цифровых товаров:

  • Установите приложение из Play Store на устройство.
  • Убедитесь, что сайт размещен по протоколу https. Использование http приведет к тому, что API станет undefined

С тестовыми пользователями и командами контроля качества

Магазин Play Store предоставляет возможности для тестирования, включая тестовые учетные записи пользователей и тестовые SKU. Для получения дополнительной информации ознакомьтесь с документацией по тестированию Google Play Billing .

Куда идти дальше?

Как описано в этом документе, Play Billing API имеет клиентские компоненты, которыми управляет API цифровых товаров, и серверные компоненты.