Weekend Coder: Utilizing in-app purchases

I have tried a few pricing models, free only, free w/ ads, free version/paid version, etc but the best I've found is using the "freemium" model. The idea behind freemium is the app is initially free but to access additional portions or to gain extra ability in the app is to pay real money. This same methodology can be applied to already paid apps, thus recreating premium plus apps. Not only have I found this as the most financially beneficial but end users seem to like it the best too and it is not that difficult to implement. To add in-app purchases we'll use the BlackBerry Payment Service.

Few things before I get started, this is not an exhaustive sample on in-app purchases, in fact I am only going to go through a purchase of a consumable good. In app purchases have multiple models within it such as subscriptions and non-consumable goods. Implementing the others are much different but I’ll leave that to you to implement based off your own needs.

Though there is already a really good BlackBerry sample here, there are just too many bells and whistles in there that I find to be annoying. This sample will use the PaymentServiceControl.cpp and .hpp files from that sample but I will strip out the unnecessary parts. Plus I'll explain everything along the way. So go ahead and grab those files from the sample mentioned above.

Now that you have the source of that code pulled, let’s create a new project. I called my "PaymentTest." First let’s added the necessary library to our .pro file:

LIBS += -lbbplatform

Next, there are few things we need to add to the main.cpp file of our app, first a couple includes:

#include "PaymentServiceControl.hpp"

#include <bb/platform/PaymentManager>

These includes are to call to the cpp/hpp file we grabbed from BlackBerry's sample and to the built-in Payment Manager API.

Add the platform namespace:

using namespace bb::platform;

Then within the main function a few more lines of code fromt he sample:

PaymentManager::setConnectionMode(PaymentConnectionMode::Test); // Register our class that wraps the C++ PaymentService interface with QML so that we // can make calls into the PaymentService and get results, through QML. qmlRegisterType("com.sample.payment", 1, 0, "PaymentServiceControl");

The setConnectionMode is to toggle between "Test" and "Production"... keep it in Test for now so you can test, and you'll change to production before submitting to BlackBerry World (more on that in a bit). And as you can see from the comment in the sample, the qmlRegisterType is to access the Payment Service from QML.

For this basic example nothing else needs to be done in C++, so we can head over to QML for the rest of the app. Let’s create a testing UI in our main.qml:

import bb.cascades 1.0 Page { Container { Button { text: "Buy 200 Coins" onClicked: { } } Label { id: coinCount text: "0" } } }

So we would like for when we press the button the user can add 200 coins to their coin count Label (and obviously use the payment system to do so). Let’s declare our payment class we defined in our C++ file:

import com.sample.payment 1.0

And add the PaymentServiceControl as an attached object to the Page (taken from main.qml of the BlackBerry sample) and delete out the signal actions for each function. So we’d have the following:

attachedObjects: [ PaymentServiceControl { id: paymentControl property string id property string sku property string name property string metadata onPriceResponseSuccess: { } onPurchaseResponseSuccess: { } onExistingPurchasesResponseSuccess: { } onSubscriptionTermsResponseSuccess: { } onCancelSubscriptionResponseSuccess: { } onCheckStatusResponseSuccess: { } onInfoResponseError: { } } ]

The only function we’ll use is onPurchaseResponseSuccess{} and we want to tie that to our Button:

//... Button { text: "Buy 200 Coins" onClicked: { paymentControl.id = "123456789" paymentControl.sku = "SKU-1" paymentControl.name = "200 Coins" paymentControl.metadata = "200 Coins" paymentControl.getPrice(paymentControl.id, paymentControl.sku) paymentControl.purchase(paymentControl.id, paymentControl.sku, paymentControl.name, paymentControl.metadata) } } //... onPurchaseResponseSuccess: { var coins = Number(coinCount.text); coinCount.text = coins + 200; }

If you’ve done this correctly you should get the following sequence of events:

Few things to note now… We have made a fake app, with fake SKUs for in app purchases, fake ID, and we are running in a test environment. So when you want to go live you need to do the following steps.

1. Change the Payment manager in your main.cpp from Test to Production:

PaymentManager::setConnectionMode (PaymentConnectionMode::Production);

2. Create Digital Goods within Manage Products in your BlackBerry Vendor Portal:

3. Replace the SKU, ID, etc in your main.qml with actual information created from your Vendor account. Note the id will be generated after you create the good, so you will need to go back into the goods and click on it to see the id.

Now if you run the app with these changes it will no longer allow you to make the purchase and get an App World error. That is because it is trying to connect to the Payment server and if your app wasn’t downloaded through BlackBerry World you will get errors. But I assure you, it is ready and once it has been approved everything should work correctly.

Final notes… Realize I have told you no mechanism to save coin counts here so you make sure you do that in you live app or customers will be very mad if they buy coins and they aren’t saved once they close the app. Also be aware of the different license types of your virtual goods. Such as coins would be Consumable meaning the system will allow users to buy them over and over. Where as if you are selling more levels of a game that would be Non-Consumable as once the user has purchased the “level pack” they won’t be allowed to purchase it again.