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

André Cipriani Bandarra

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

Для приложений, созданных с использованием Trusted Web Activities и доставленных через 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 цифровых товаров используется для сбора информации об артикулах и проверки покупок и прав в Play Store. API запроса платежа используется для настройки Google Play Store в качестве способа оплаты и для завершения процесса покупки.

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

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

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

Требования

Для настройки Google Play Billing вам понадобится:

• Аккаунт разработчика Google Play и аккаунт продавца Google Payment , связанные друг с другом .
• Листинг в Play Store с выпуском для публичного, закрытого или внутреннего тестирования .
• Для создания и настройки продуктов и подписок вашего приложения в Play Store.
• Проект, созданный Bubblewrap , с рабочей конфигурацией ссылок на цифровые активы .

Обновление проекта 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 выполняется внутри Trusted Web Activity, и определить его доступность можно, проверив 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 принимает два параметра: список способов оплаты и список платежных реквизитов.

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

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

const request = new PaymentRequest(paymentMethods, paymentDetails);

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

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

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

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

• Взгляните на пример Питера Конна по адресу https://github.com/PEConn/beer
• Ознакомьтесь с документацией Play по проверке покупки .
• Рассмотрите возможность использования одной из клиентских библиотек API разработчика Google Play , которые доступны на нескольких языках .
• Если вы реализуете модель подписок в своем приложении, ознакомьтесь с документацией по подпискам Play Billing .
• Реализуйте уведомления для разработчиков в режиме реального времени (RTDN) и подпишитесь на уведомления, чтобы ваш бэкэнд получал уведомления об изменении состояния подписки, а не опрашивал ее статус в Play.
• Реализуйте linkedPurchaseToken , чтобы предотвратить дублирование подписок. Прочитайте эту запись в блоге о том, как правильно это реализовать.