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

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

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

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

import QtPurchasing 1.13

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