Setting up the Payment Service

The Payment Service classes are included in the BlackBerry 10 Native SDK. If you are creating your first app, you can download the tools that you need and learn how to create, build, and run your first Cascades project. 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 the steps that you can follow to create in-app purchase opportunities. The code samples in these sections are based on the QML-based Freemium sample app and the C++ Payment Service sample app. To learn more about how to import an existing project into the Momentics IDE for BlackBerry, 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

If you are developing your app in QML, you must import the bb.platform library in your main.qml file:

import bb.platform 1.2

If you are developing your app in C++, you must include the Payment Service classes:

#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>

Create a payment instance

To create a purchase in your app, you must set up an instance of the PaymentManager. You can request purchases or manage subscriptions in your app with this instance of the PaymentManager.

In QML, you can attach the PaymentManager instance to your UI as an attached object.

import bb.cascades 1.2
import bb.platform 1.2

NavigationPane {
    id: navigationPane

    attachedObjects: [
        PaymentManager {
            id: rootPaymentManager
        }
    ]

In C++, you can create a PaymentManager instance as follows:

PaymentManager* m_paymentManager = new PaymentManager(this);

Set the window group ID

The Payment Service uses the windowGroupId in the background and passes this value to BlackBerry Identity Service. You must set the windowGroupId of your PaymentManager instance so that the Payment Service can show the BlackBerry ID prompt in the correct window group. For more information, see the Identity Service APIs. The window group ID of your Cascades application is set when your application starts.

In QML, you can set the windowGroupId in your main.qml.

    attachedObjects: [
        PaymentManager {
            id: rootPaymentManager
            windowGroupId: Application.mainWindow.groupId
        }
    ]

In C++, you can retrieve the window groupId and set the window group ID for your PaymentManager instance using the setWindowGroupId() function.

// 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 connection mode

By default, your app contacts the Payment Service server for transactions as if your app is in production. If you want to test your app (and you don't want any accidental charges), you should set the connection mode to Test. In test mode, your app doesn't contact the Payment Service server for any transactions. For more information, see Testing in-app purchases.

The connection mode affects all Payment Service requests and is not linked to a PaymentManager instance. You should set the connection mode when your application starts, before any PaymentManager instances are created.

In QML, you can attach a PaymentManager instance to your UI and set the connection mode when the creationCompleted() signal is emitted.

import bb.cascades 1.2
import bb.platform 1.2

NavigationPane {
    id: navigationPane

    attachedObjects: [
        PaymentManager {
            id: rootPaymentManager

        },
        // Add the UI for a store where users
        // see the  digital goods for sale in
        // your app.
        StorePage {
            id: store
        },
        // Add the UI for your game. 
        GamePlay {
            id: game
        }
    ] 

    onCreationCompleted: {
        rootPaymentManager.setConnectionMode(0);
    }
}

In C++, you can set the connection mode in your main.cpp file before you create your UI.

PaymentManager::setConnectionMode(PaymentConnectionMode::Test);

You must not change the connection mode while Payment Service operations are outstanding.

Specify an application icon URL

The application icon is displayed on a banner during the purchase process when an app is in production mode. The icon must be available through an external website, with a URL that uses the "http://..." format. The icon can be any standard format (PNG, GIF, JPEG) but it should be a 100x100 pixel square. If you don't provide an icon, the icon that was registered in BlackBerry World is used and it may be scaled to 100 x 100 pixels. For more information about application icons, see Application icons. If you need to retrieve the icon URL in your code, you can use applicationIconUrl().

You cannot see this banner if you set the connection mode to Test because all transactions are simulated.

You can set the applicationIconUrl when you set up an instance of the PaymentManager.

In QML:

        PaymentManager {
            id: rootPaymentManager
            applicationIconUrl: "http://mycompany.com/100x100.png"
        }

In C++:

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

Last modified: 2013-12-21

comments powered by Disqus