BlackBerry Java to BlackBerry 10 Cascades Porting Series – Part 14: In App Payment

Cascades

TITLE_IMAGE

Do you have an application built using BlackBerry Java that makes use of the Payment Service APIs? You’ll be happy to know that Cascades support the exact same digital goods types meaning you can provide the same monetization model in BlackBerry 10; you can even use the same digital goods already in your vendor portal. This means less time planning how to monetize your app and less time creating and managing digital goods giving you more time and freedom to develop the rest of the app or letting you finish a few days earlier.

BlackBerry World Client

In BlackBerry OS 7 and lower the Payment Service was included as a separate library which was heavily dependent on the version of BlackBerry World that was installed on the device. This meant that your application would need to query what version of BlackBerry World was installed and, if not at the version required by the library, prompt the user to upgrade the client to a newer version.

In BlackBerry 10 the Payment Service libraries are integrated directly into the OS and the tight coupling with the BlackBerry World client has been removed; meaning you only need to worry about developing.

Vendor Portal

As mentioned above the same digital goods used for BlackBerry OS 7 app releases can be used against any device/OS including BlackBerry 10. To make use of the existing digital goods you simply need to create a new BlackBerry 10 release that references the SKUs of the existing goods. If you are creating a new app altogether then you only need to create the digital goods in the same manner done for your Java apps:

http://docs.blackberry.com/en/developers/deliverables/47831/1278466.jsp

If your BlackBerry Java application has a good user base then I would recommend the above approach, it will allow existing users to download your new BlackBerry 10 version as soon as they upgrade, being visible right in the “My World” section of their BlackBerry World client app when they start up their new BlackBerry 10 device. You will, however, want to upload separate metadata for each platform you are targeting (screenshots, descriptions, keywords etc):

http://devblog.blackberry.com/2012/11/blackberry-app-world-success/

Environment Setup:

Both BlackBerry OS 7 and 10 require an additional library to be added to the project, the difference is that in BlackBerry 7 you need to download and add the library (JAR) to your project, whereas in BlackBerry 10 you only need to reference the library that is integrated with the SDK and OS meaning less work for you and a library that stays updated as you change SDK versions.

Java:

Add the JAR to your project

http://docs.blackberry.com/en/developers/deliverables/40131/Add_Payment_Service_library_to_build_path_1316204_11.jsp

Cascades:

Add the LIB reference to your .PRO file

https://developer.blackberry.com/cascades/documentation/device_platform/paymentservice/selling.html#pat1339516868668

Initializing the Payment Engine/Manager:

The “brains” of the payment service, where all calls are initiated, stems from one object which needs to be instantiated before any further calls can be made. Below are code snippets that show how this instantiation occurs in BlackBerry OS 7 in Java followed by BlackBerry OS 10 using Cascades APIs:

Java:

A prerequisite to using the payment service is to verify that the version of BlackBerry World client on the device is at a sufficient level and, if not, prompting for the update to be installed prior to making any payment calls.

try {
 PaymentEngine.isAppWorldInstalledAndAtCorrectVersion();
} catch (AppWorldUpdateRequired e) {
 PaymentEngine.upDateAppWorld();
 System.exit(0);
}
PaymentEngine engine = PaymentEngine.getInstance();

Cascades:

The payment service in Cascades requires information on which window group the app is using so the payment prompts can be properly drawn overtop.

bb::platform::PaymentManager *m_paymentManager = new PaymentManager();
 bb::cascades::Application::instance()->mainWindow()->groupId();
m_paymentManager->setWindowGroupId(windowGroupId);

The PaymentManager lets you define properties that will be displayed to the user in all purchase requests, specifically the application name and the URL of a custom icon if desired.

m_paymentManager->setApplicationName("The Awesome Store");
m_paymentManager->setApplicationIconUrl(QUrl("http:///mycompany.com/100x100.png"));

Test Mode:

Not available in BBOS

Cascades:

PaymentManager::setConnectionMode(PaymentConnectionMode::Test);

Initiating a Purchase

Java:

PurchaseArgumentsBuilder arguments = new PurchaseArgumentsBuilder()
     .withDigitalGoodId( "1234" )
     .withDigitalGoodName( "My Product" )
     .withDigitalGoodSku( "Ab34t2eC" )
     .withPurchasingAppIcon( bitmapIconImageVariable ); 
     .withPurchasingAppName( "My Application" ); 
     .withMetadada( "Extra info for consumable goods" );
 try 
 {
     PurchaseResult result = engine.purchase(arguments.build());
 }
 …

Cascades:

const PurchaseReply *reply = m_paymentManager->requestPurchase("1234", "Ab34t2eC", "My Product", "Extra info for consumable goods");
connect(reply, SIGNAL(finished()), SLOT(handlePurchase()));

Restoring Past Purchases

Java:

try
 {
     ExistingPurchasesResult result = engine.getExistingPurchases(false/true);
     Purchase[] resultPurchases = result.getPurchases();
 }
 catch (PaymentException e)
 { 
 }

Cascades:

const ExistingPurchasesReply *reply = paymentManager->requestExistingPurchases(false/true);
connect(reply, SIGNAL(finished()), SLOT(handleExistingPurchases()));

If you happen to be new to C++ and would still like to monetize your Cascades application then you will be happy to know that our Payment Services developers have created a nice sample which takes the bulk of the payment calls needed and exposes then through to QML, allowing you to make payment calls without writing a single line of C++ yourself, just copy the important parts from the sample into your own application. This sample can be gitted from here:

https://github.com/blackberry/Cascades-Samples/tree/master/paymentservice

Of course there are a few more calls available through the Payment Service in both Java and Cascades, but the above set provides a solid baseline for the main functions developers using the Payment Service should be aware of. If there is anything else you would like to know about the Payment Service, or have trouble porting the pieces from Java to Cascades, there are a few great options for support:

1)      Support forums: http://supportforums.blackberry.com/t5/Payment-Service/bd-p/pay_serv

2)      BlackBerry Developer Twitter account: @BlackBerryDev

3)      Garett B (Developer Relations Payment Service Expert): @garettBeuk

Happy porting!

About garett

Garett is a member of the Developer Relations team and has been with BlackBerry since 2008. He specializes in app monetization (Payment, Advertising, Analytics SDKs) and Push development. He is one of the individuals involved with the forums (gbeukeboom), Issue Tracker and can be found tweeting from @BlackBerryDev with the ^GB signature.

Join the conversation

Show comments Hide comments
+ -
blog comments powered by Disqus