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 project. Before you begin, you must register your app and its digital goods in the BlackBerry World vendor portal. 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 following samples:

To learn more about how to import an existing project into the Momentics IDE for BlackBerry, see Import an existing project.

To use the Payment Service APIs in your app, you need to link against the correct library by adding the following line to your project's .pro file:

LIBS += -lbbplatform

To use the Payment Service APIs in your app, you need to link against the correct library by adding the following line to your project's .pro file:

LIBS += -lbbplatform

Create a payment instance

To allow a purchase in your app, you must initialize the Payment Service in your app.

import bb.cascades 1.2
import bb.platform 1.2
NavigationPane {
    id: navigationPane

    // Set up an instance of the PaymentManager
    // as an object that is attached to your UI
    attachedObjects: [
        PaymentManager {
            id: rootPaymentManager
        }
    ]
#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>
// Set up an instance of the PaymentManager
PaymentManager* m_paymentManager = new PaymentManager(this);

Set the window group ID

You must set the window group ID for your payment instance when your app starts, so that the Payment Service can display dialog boxes. The window group ID of your app is initialized when your app starts.

If you are creating a Cascades app, 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.

You can set the windowGroupId in your main.qml.

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

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 for Cascades apps or local for C apps. In test/local 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 made from your app. You should set the connection mode when your app starts, before any in-app purchases are created.

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

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);
    }
}

You can set the connection mode in your main.cpp file before you create your UI.

// Set connection mode to Test before you create your UI
PaymentManager::setConnectionMode(PaymentConnectionMode::Test);

Specify an app icon URL

The app 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 app icons, see Application icons.

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.

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

If you need to retrieve the icon URL in your code, you can use applicationIconUrl().

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

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

If you need to retrieve the icon URL in your code, you can use applicationIconUrl().

Set the app name

When a purchase is initiated, the purchase screens display a banner along the top of the screen. This banner shows the name and icon of the app that the purchase is being made from (your app). If you don't set the app name, the app name that was registered in BlackBerry World is used.

You cannot see this banner if you set the connection mode to test/local because all transactions are simulated. You must set the connection mode to Production.

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

        PaymentManager {
            id: rootPaymentManager
            applicationName: "My Awesome App"
        }

If you need to retrieve the app name in your code, you can use applicationName().

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

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

If you need to retrieve the app name in your code, you can use applicationName().

Last modified: 2014-09-30



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus