Selling digital goods

The Payment Service classes are included in the BlackBerry 10 Native SDK. To download the tools that you need, visit Downloads. To learn how to create, build, and run your first Cascades project, see Create your first app. You'll also need to understand how slots and signals work because the Payment Service uses them to notify and provide results for any requests you make. To learn more about signals and slots, see Signals and slots. Before you begin, you must register your app and its digital goods in BlackBerry World. To learn more, see Registering with BlackBerry World.

The following sections describe everything you need to create in-app purchase opportunities. The code samples in these sections are based on the Payment sample app that's included on the Sample Apps page. To learn more about how to import an existing project into the QNX Momentics IDE, see Import an existing project.

Payment Service classes are included in the bb::platform library. To use these classes in your app, you must add the following to the .pro file in your project:

LIBS += -lbbplatform

You also need to include the Payment Service classes in your main.cpp file:

#include <bb/platform/PaymentManager>
#include <bb/platform/PaymentConnectionMode>
#include <bb/platform/PaymentReply>
#include <bb/platform/PurchaseReply>
#include <bb/platform/CancelSubscriptionReply>
#include <bb/platform/DigitalGoodReply>
#include <bb/platform/ExistingPurchasesReply>
#include <bb/platform/PriceReply>
#include <bb/platform/SubscriptionStatusReply>
#include <bb/platform/SubscriptionTermsReply>
#include <bb/platform/PurchaseReceipt>
#include <bb/platform/DigitalGoodState>

Before you can create in-app purchases, there are a few things you should do first:

PaymentManager::setConnectionMode(PaymentConnectionMode::Test);

// Instantiate a new PaymentManager instance 

PaymentManager* m_paymentManager = new PaymentManager(this);

// Get the window group ID and pass it to the PaymentManager instance.
const QString windowGroupId = 
    bb::cascades::Application::instance()->mainWindow()->groupId();
m_paymentManager->setWindowGroupId(windowGroupId);

// Set the application name so that it shows up in the purchase banner.
m_paymentManager->setApplicationName("The Awesome Store");

// Set the application URL so that it shows up in the purchase banner.
m_paymentManager->setApplicationIconUrl(QUrl("http:///mycompany.com"));

You can initiate a purchase in your app using the requestPurchase() function. You receive a response to this function when a user completes the purchase process (which may include steps such as signing in to a BlackBerry ID account, setting up a preferred payment method, and so on).

When you call the requestPurchase() function, only the ID or SKU of the digital good to be purchased is required; you don't need to provide both. If you do provide both, the ID takes precedence.

When requestPurchase() finishes, the  PaymentManager::purchaseFinished() signal is emitted for your PaymentManager  instance and the PaymentReply::finished()  signal is emitted on the PurchaseReply instance.

In order to analyze the results of the requestPurchase(), you must first use the PaymentReply::isFinished() function to determine if the request finished. If the Payment Service server is unable to finish the request, false is returned. If the Payment Service server is able to finish the request, true is returned and you can check PaymentReply::isError() to determine if the request was successful.

If isError() returns true, you can use errorCode() and errorText() to present a dialog box or toast to your user. If isError() returns false, you can use the PurchaseReply class and the receipt() function or the purchaseMetadata() function to present information about the successful purchase to the user.

The following code sample requests a purchase, passing in an ID and a SKU to requestPurchase(). The response is returned as a PurchaseReply. Then it connects the finished() signal to a handlePurchase() function that has been declared in your MyPaymentApp.hpp and implemented in your MyPayment.cpp to handle the finished() signal that is emitted when the purchase is completed.

void myPaymentApp::purchase(const QString &id, const QString &sku)
{
    //Request a purchase using the ID and SKU of the digital good. 
    const PurchaseReply *reply = m_paymentManager->requestPurchase(id, sku);
    
    // Connect the finished() signal to a slot to handle the purchase.
    connect(reply, 
            SIGNAL(finished()), 
            SLOT(handlePurchase()));
}

You will need a handlePurchase() function, also known as a slot, that determines if the purchase finished and succeeded, and emits the appropriate signals.

void MyPaymentApp::handlePurchase()
{
    bb::platform::PurchaseReply *reply = 
        qobject_cast<bb::platform::PurchaseReply*>(sender());
    Q_ASSERT(reply);

    // Check to see if the request finished. 
    if (reply->isFinished()) {
    	
    	// Emit an error signal if there were errors.
        if (reply->isError()) {

            emit infoResponseError(reply->errorCode(), reply->errorText());

        //Emit a success signal if there were no errors. 
        } else {
            const QString displayString = receiptToString(reply->receipt());

            emit purchaseResponseSuccess(displayString);
        }
    } else {
        qDebug() << "Purchase request did not finish.";
    }

    reply->deleteLater();
}

When you call requestPurchase() the digital good name and the purchase metadata are also optional parameters, and you might use them in the following cases.

void myPaymentApp::purchase(
   const QString &id, const QString &sku, const QString &name)
{
   //Request a purchase using the ID, SKU, and name of the digital good.
   const PurchaseReply *reply = m_paymentManager->requestPurchase(id, sku, name);

   // Connect the finished() signal to a slot to handle the purchase.
   connect(reply,
           SIGNAL(finished()),
           SLOT(handlePurchaseWithName()));
}

void myPaymentApp::purchase(
    const QString &id, const QString &sku, const QString &metadata)
{
    //Request a purchase using the ID, SKU, and metadata of the digital good. 
    const PurchaseReply *reply = m_paymentManager->
        requestPurchase(id, sku, metadata);

    // Connect the finished() signal to a slot to handle the purchase.
    connect(reply, 
            SIGNAL(finished()), 
            SLOT(handlePurchaseWithMetadata()));
}

Your app can use the PurchaseReply class to let your user know what happened during a PaymentManager::requestPurchase(). The PurchaseReply contains a PurchaseReceipt that you can use to display a purchase receipt.

The PurchaseReply class is a subclass of the DigitalGoodReply class which is a subclass of the PaymentReply class. The functions and signals that are inherited from the PaymentReply class are used for checking if a request to PaymentManager finished and succeeded. The following information can be found in the PurchaseReply:

• The isFinished() function is used to determine if the requestPurchase() finished.

• The isError() function is used to determine if the requestPurchase() succeeded. If the purchase was successful, the PurchaseReply object contains the data you requested, and data that is related to the result of the request that you can display in your UI.

• The errorCode() and errorText() functions can be used to present a dialog box or toast to your user if the purchase was not successful..

The functions that are inherited from the DigitalGoodReply class are used to find the ID and SKU of the digital good.

• You can use the digitalGoodId function to find the ID of a digital good that you supplied to requestPurchase(). The ID is empty if you did not supply an ID to requestPurchase().

• You can use the digitalGoodSku to find the SKU of a digital good that you supplied to requestPurchase(). The SKU is empty if you did not supply a SKU to requestPurchase().

The functions in the PurchaseReply class are used to find the receipt for a successful purchase and the metadata associated with the successful purchase.

• If isError() returns false, you can use the receipt() function or the purchaseMetadata() function to present information about the successful purchase to the user.

The following code sample requests a purchase, passing in an ID and a SKU to requestPurchase(). The response is returned as a PurchaseReply. Then it connects the finished() signal to a handlePurchase() function that has been declared in your MyPaymentApp.hpp and implemented in your MyPayment.cpp to handle the finished() signal that is emitted when the purchase is completed.

void MyPaymentApp::handlePurchase()
{
    bb::platform::PurchaseReply *reply = 
        qobject_cast<bb::platform::PurchaseReply*>(sender());
    Q_ASSERT(reply);

    // Check to see if the request finished 
    if (reply->isFinished()) {
    	
    	// Emit an error signal if there were errors.
        if (reply->isError()) {

            emit infoResponseError(reply->errorCode(), reply->errorText());

        //Emit a success signal if there were no errors. 
        } else {
            const QString displayString = receiptToString(reply->receipt());

            emit purchaseResponseSuccess(displayString);
        }
    } else {
        qDebug() << "Purchase request did not finish.";
    }

    reply->deleteLater();
}

You can extract the information from the PurchaseReceipt with a receiptToString function:

static QString receiptToString(bb::platform::PurchaseReceipt r)
{
  const QString initialPeriod = QString::number(r.initialPeriod());
  const QDateTime startDate = r.startDate();
  const QString startDateStr = startDate.isNull() ? "N/A" : startDate.toString();
  const QDateTime endDate = r.endDate();
  const QString endDateStr = endDate.isNull() ? "N/A" : endDate.toString();
  const QString isSubscr = r.isSubscription() ? "true" : "false";
  const QString itemStateStr = QString::number(static_cast<int>(r.state()));

  const QString displayString = "Date: " + r.date().toString() +
      "\nID/SKU: " + r.digitalGoodId() + "/" + r.digitalGoodSku() +
      "\nPurchaseID/licenseKey: " + r.purchaseId() + "/" + r.licenseKey() +
      "\nMetadata: " + r.purchaseMetadata() +
      "\nItemState/isSubscription?: " + itemStateStr + "/" + isSubscr +
      "\nStart/End: " + startDateStr + "/" + endDateStr +
      "\nInitialPeriod: " + initialPeriod + "\n";

    return displayString;
}

If your app needs a list of digital goods that a user already purchased (to avoid offering a digital good that the user already owns for sale), you can use the PaymentManager::requestExistingPurchases() function. This function retrieves all the purchases that a user made as an ExistingPurchasesReply including purchases that a user made before an upgrade, or purchases that a user made after your app was removed and downloaded again.

The ExistingPurchasesReply class is a subclass of the PaymentReply class. The functions and signals that are inherited from the PaymentReply class are used for checking if a request to PaymentManager finished and succeeded. The following information can be found in the ExistingPurchasesReply:

• The isFinished() function is used to determine if the requestPurchase() finished.

• The isError() function is used to determine whether the requestPurchase() succeeded or not. If the purchase was successful, the PurchaseReply object contains the data you requested, and data that is related to the result of the request that you can display in your UI.

• The errorCode() and errorText() functions can be used to to present a dialog box or toast to your user if the purchase was not successful.

The functions in the ExistingPurchasesReply can be used to get a list of user purchases. This list is returned as a Qlist of PurchaseReceipt objects.

The requestExistingPurchases() function accepts a parameter called forceServerRefresh, which is a Boolean value that indicates whether the list of past purchases should be refreshed from the server when a request is made. A value of true indicates that data is refreshed from the server, and a value of false means that a cached list of purchases is returned.

When requestExistingPurchases() finishes, the  existingPurchasesFinished() signal is emitted for your PaymentManager  instance and the PaymentReply::finished()  signal is emitted on the ExistingPurchasesReply instance.

The following code sample requests the list of existing purchases by using the requestExistingPurchases() function, passing in a Boolean value to refresh the data from the server. The response is returned as a ExistingPurchasesReply. Then it connects the finished() signal to a handleExistingPurchases() function to handle the finished() signal that is emitted when the request is completed. The handleExistingPurchases() function should be declared in your MyPaymentApp.hpp and implemented in your MyPayment.cpp.

void MyPaymentApp::getExistingPurchases(bool refresh)
{
    //Request the existing purchases from the Payment Services server.
    const ExistingPurchasesReply *reply = paymentManager->
        requestExistingPurchases(refresh);

    // Connect the finished() signal to a slot to handle the existing purchases.
    connect(reply, 
            SIGNAL(finished()), 
            SLOT(handleExistingPurchases()));
}

You can also generate a receipt for each purchase using the ExistingPurchasesReply class. Here's a code sample of a function created to find existing purchases and produce a readable string of each receipt. The function which converts the PurchaseReceipt to a displayable string is the same function that was shown in Responding to a purchase.

void MyPaymentApp::handleExistingPurchases()
{
    bb::platform::ExistingPurchasesReply *reply = 
        qobject_cast<bb::platform::ExistingPurchasesReply*>(sender());
    Q_ASSERT(reply);

    // Check to see if the request finished
    if (reply->isFinished()) {

    	// Emit an error signal if there were errors.

        if (reply->isError()) {

            emit infoResponseError(reply->errorCode(), reply->errorText());

        //Emit a success signal if there were no errors.
 
        } else {

            const QList<PurchaseReceipt> receipts = reply->purchases();

            if (receipts.isEmpty()) {

                emit existingPurchasesResponseSuccess("(No purchases)");

            } else {
                // For each purchase, format a user readable string 
                // that represents the receipt for that purchase.

                QString displayString;
                Q_FOREACH(PurchaseReceipt r, receipts) {
                    displayString += (receiptToString(r) + "\n");
                }
                emit existingPurchasesResponseSuccess(displayString);
            }
        }
    } else {
        qDebug() << "Request existing purchases request did not finish.";
    }

    reply->deleteLater();
}

You can use the following functions in PaymentManager to manage subscriptions in your app:

• The requestSubscriptionTerms() function queries the terms of subscriptions. See also Request the terms of a digital good subscription.
• The requestSubscriptionStatus() function queries the status of subscriptions. See also Check the status of a subscription.
• The requestCancelSubscription() function cancels subscriptions. See also Cancel a subscription.

void MyPaymentApp::getSubscriptionTerms(const QString &id, const QString &sku)
{
    if (id.isEmpty())
        return;

    const SubscriptionTermsReply *reply = 
        m_paymentManager->requestSubscriptionTerms(id, sku);

    connect(reply, 
            SIGNAL(finished()), 
            SLOT(subscriptionTermsReply()));
}

void MyPaymentApp::subscriptionTermsReply()
{
    bb::platform::SubscriptionTermsReply *reply = 
        qobject_cast<bb::platform::SubscriptionTermsReply*>(sender());
    Q_ASSERT(reply);

    // Emit an error signal if there were errors.

    if (reply->isError()) {

        emit infoResponseError(reply->errorCode(), reply->errorText());

    // Emit a success signal if the request succeeded.

    } else {
        qDebug() << "Sub terms response success. Price: " << reply->price() <<
            "\nInitialPeriod: " << reply->initialPeriod() <<
            "\nRenewalPrice: " << reply->renewalPrice() <<
            "\nRenewalPeriod: " << reply->renewalPeriod();

        emit subscriptionTermsResponseSuccess(reply->price(), 
                                              reply->initialPeriod(), 
                                              reply->renewalPrice(), 
                                              reply->renewalPeriod());
    }

    reply->deleteLater();
}

void MyPaymentApp::checkSubscriptionStatus(const QString &id, 
                                           const QString &sku)
{
    if (id.isEmpty())
        return;

    const SubscriptionStatusReply *reply =
        m_paymentManager->requestSubscriptionStatus(id, sku);

    connect(reply,
            SIGNAL(finished()),
            SLOT(subscriptionStatusResponse()));
}

void MyPaymentApp::subscriptionStatusResponse()
{
    bb::platform::SubscriptionStatusReply *reply = 
        qobject_cast<bb::platform::SubscriptionStatusReply*>(sender());
    Q_ASSERT(reply);

    // Emit an error signal if there were errors.

    if (reply->isError()) {

        emit infoResponseError(reply->errorCode(), reply->errorText());

    // Emit a success signal if the request succeeded.

    } else {

        emit checkStatusResponseSuccess(reply->isActive());
    }

    reply->deleteLater();
}

void MyPaymentApp::cancelSubscription(const QString &purchaseId)
{
    if (purchaseId.isEmpty())
        return;

    const CancelSubscriptionReply *reply = 
        m_paymentManager->requestCancelSubscription(purchaseId);

    connect(reply, 
            SIGNAL(finished()), 
            SLOT(cancelSubscriptionResponse()));
}

void MyPaymentApp::cancelSubscriptionResponse()
{
    bb::platform::CancelSubscriptionReply *reply = 
        qobject_cast<bb::platform::CancelSubscriptionReply*>(sender());
    Q_ASSERT(reply);

    // Emit an error signal if there were errors.

    if (reply->isError()) {

        emit infoResponseError(reply->errorCode(), reply->errorText());

    // Emit a success signal if the request succeeded.
    } else {

        emit cancelSubscriptionResponseSuccess(reply->isCanceled());
    }

    reply->deleteLater();
}