Начало работы с Qt Purchasing в QML

Данное руководство предполагает, что вы зарегистрировали продукты приложения в внешнем магазине. Более подробную информацию о регистрации продуктов см. в Регистрация продуктов в Google Play и Регистрация продуктов в App Store

Подготовка приложения

Используйте следующее import утверждение в файлах QML для доступа к типам QML Qt Purchasing:

import QtPurchasing 1.12

Добавьте следующее утверждение в ваш .pro файл, чтобы связать его с библиотекой Qt Purchasing:

QT += purchasing

Регистрация продуктов

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

Store {
    Product {
        identifier: "consumableProduct"
        type: Product.Consumable

        // ...
    }

    Product {
        identifier: "unlockableProduct"
        type: Product.Unlockable

        // ...
    }
}

Как вы можете видеть, есть продукты для одноразового использования и продукты, которые разблокируются. Первые могут быть приобретены неограниченное количество раз одним и тем же пользователем, в то время как вторые — только один раз.

Описание продукта

Для каждого продукта вы должны заполнить identifier, прежде чем продукт можно будет запросить у внешнего магазина. Также следует всегда добавлять обработчик onPurchaseSucceeded и onPurchaseFailed, если вы хотите предоставить возможность покупки продуктов. Если вы также используете функцию восстановления, добавьте обработчик onPurchaseRestored для продуктов, которые разблокируются.

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

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

Store {
    id: store
    Product {
        id: healthPotionProduct
        identifier: "healthPotion"
        type: Product.Consumable

        property bool purchasing: false

        onPurchaseSucceeded: {
            if (!hasAlreadyStoredTransaction(transaction.orderId)) {
                ++healthPotions
                if (!addHealthPotionToPersistentStorage(transaction.orderId)) {
                    popupErrorDialog(qsTr("Unable to write to persistent storage. Please make sure there is sufficient space and restart."))
                } else {
                    transaction.finalize()
                }
            }

            // Reset purchasing flag
            purchasing = false
        }

        onPurchaseFailed: {
            popupErrorDialog(qsTr("Purchase not completed."))
            transaction.finalize()

            // Reset purchasing flag
            purchasing = false
        }
    }
}

Если транзакция не завершена, она будет снова вызвана для той же транзакции при следующем запуске приложения, что предоставит ещё одну возможность сохранить данные. Транзакция для продукта одноразового использования должна быть завершена, прежде чем продукт можно будет снова купить.

Покупка продукта

Чтобы купить продукт, вызовите метод purchase() объекта. Это запускает платформенно-зависимый асинхронный процесс покупки продукта, например, запрашивая пароль пользователя и подтверждение покупки. В большинстве случаев необходимо убедиться, что пользовательский интерфейс приложения не принимает ввод во время обработки запроса на покупку, так как это не обрабатывается автоматически на всех платформах.

Следующий пример добавляет кнопку, которая будет использоваться с примером продукта в предыдущем разделе:

Rectangle {
    id: button
    width: 100
    height: 50

    Text {
        anchors.centerIn: parent
        text: qsTr("Buy health potion for only " + healthPotionProduct.price + "!")
    }

    MouseArea {
        enabled: !healthPotionProduct.purchasing && healthPotionProduct.status === Product.Registered
        anchors.fill: parent
        onClicked: {
            healthPotionProduct.purchasing = true
            healthPotionProduct.purchase()
        }
    }
}

При нажатии кнопки запускается процесс покупки. В какой-то момент в будущем будет вызван обработчик onPurchaseFailed (например, если пользователь отменяет транзакцию) или обработчик onPurchaseSucceeded.

Примечание: Кнопка активна только если статус продукта установлен на Registered. Процесс регистрации продукта асинхронный, поэтому попытки покупок продукта до его успешной регистрации всегда будут неудачными.

Восстановление ранее приобретенных продуктов

Если приложение удалено и затем переустановлено (или установлено тем же пользователем на другом устройстве), вы должны предоставить способ восстановления ранее приобретённых продуктов, которые разблокируются, в внешнем магазине.

Чтобы начать процесс восстановления покупок, вызовите метод restorePurchases() в объекте Store. Это вызовет обработчик onPurchaseRestored для каждого продукта, который разблокируется в приложении, и который был ранее приобретен текущим пользователем.

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

Store {
    id: store

    // ... other products

    Product {
        id: dlcForestOfFooBarProduct
        identifier: "dlcForestOfFooBar"
        type: Product.Unlockable

        property bool purchasing: false

        onPurchaseSucceeded: {
            if (!hasMap("forestOfFooBar.map")) {
                if (!downloadExtraMap("forestOfFooBar.map")) {
                    popupErrorDialog(qsTr("Unable to download The Forest of FooBar map. Please make sure there is sufficient space and restart."))
                } else {
                    transaction.finalize()
                }
            }

            // Reset purchasing flag
            purchasing = false
        }

        onPurchaseFailed: {
            popupErrorDialog(qsTr("Purchase not completed."))
            transaction.finalize()

            // Reset purchasing flag
            purchasing = false
        }

        onPurchaseRestored: {
            if (!hasMap("forestOfFooBar.map")) {
                if (!downloadExtraMap("forestOfFooBar.map")) {
                    popupErrorDialog(qsTr("Unable to download The Forest of FooBar map. Please make sure there is sufficient space and restart."))
                } else {
                    transaction.finalize()
                }
            }
        }
    }
}

Если пользователь купит загружаемое контент и позже установит игру на другое устройство или удалит и переустановит игру, вы можете предоставить способ восстановления покупки, например, следующую кнопку:

Rectangle {
    id: restoreButton
    width: 100
    height: 50

    Text {
        anchors.centerIn: parent
        text: "Restore previously purchased content"
    }

    MouseArea {
        anchors.fill: parent
        onClicked: {
            store.restorePurchases()
        }
    }
}

Восстановление покупок всегда должно выполняться как реакция на пользовательский ввод, так как на некоторых платформах может быть представлен диалог пароля. Вызов метода restorePurchases() запускает асинхронный процесс восстановления. В какой-то момент в будущем, если продукт был ранее куплен, будет вызван обработчик onPurchaseRestored.

Примечание: Хотя функция ведет себя так, как задокументировано на Android, эта функциональность технически не требуется там. Причина в том, что устройство Android управляет всеми покупками, которые разблокируются, без вмешательства приложения. Если приложение удалено и переустановлено (или установлено на другом устройстве) на Android, то для каждого ранее купленного, продукта, который разблокируется, при запуске приложения будет вызван onPurchaseSucceeded.