In this tutorial, I will teach how to integrate BlackBerry’s official In-App Purchases plugin for UNITY.
Read EVERYTHING with attention, and pay special attention to the RED paragraphs, which will provide you vital information and save you from future trouble.
This tutorial will follow this order:
- Creation of products at BB’s Vendor Portal
- Import the In-App Purchases plugin into Unity project
- Integrate the plugin into the Demo scene
- Test the integration
Creation of the Products at Vendor Portal
1.1 – Log-in at Vendor Portal
1.2 – Click “Manage Products”
1.3 – Supposing you already created your app at the Vendor Portal, click the + (plus) button at the Goods tab, as seen in the image below
You’ll see the “Add a Virtual Good” screen:
1.4 – Fill the form, and if you have any questions, take a look at the explanations below:
Name is the product’s name that is shown ONLY at the Vendor Portal
SKU is the product identifier which you will put in your script, usually I name it like “NameOfTheGame_NameOfTheProduct” (this SKU is like the Product ID from the iOS App Store and Google Play, standardizing it may be good for your code)
License Type, pay attention to the different types of license:
- Non-consumable: is for permanent products which will be kept save at the player’s account, for instance: characters.
- Consumable: is for consumable products, that may be used just once, like a coin pack. If the user uninstall the app, he will lose that product.
- Subscription: a subscription product can be used while the subscription lasts (7 or 30 days), after that, the product will expire and can no longer be used until the user decide to pay for the subscription again
Price is the product’s price
US Withholding Tax Classification you have to choose how the taxes will be collectedin the USA. For consumable and non-consumable products, I recommend you choosing “One-time”
Canada Withholding Tax Classification I use the same as the US Withholding Tax Classification, “One-time”
License Model for BlackBerry OS and PlayBook I recommend you using “Static”, that is the most common model (it’s the same used in Google Play and iOS App Store) and honestly, I have no idea on how to use the other models, so I can’t risk recommending them.
1.5 – To complete the creation of this product, click Save. If you want to create a few more before continuing this tutorial, click “Save and Add Another” and fill the form again.
Importing the In-App Purchases Plugin into Unity
2.1 – Enter the Asset Store from inside Unity (CTRL+9 on Windows, Command+9 on Mac)
2.2 – Search for “BlackBerry” at the Asset Store
2.3 – Select BlackBerry In-App Purchasing
2.4 – Click Import, to import it into your project
2.5 – Import ALL THE plugin files into your project
Integrating the Plugin
After importing the plugin:
3.1 – Open the Demo scene, named “BlackBerryIAPTestScene”, and located inside the BlackBerry/IAP folder
3.2 – Select the gameObject named “UI” and open the class BlackBerryIAPTest.cs which is inside it
3.4 – The first two variables in this class are strings where you must put the product SKU that you created at the Vendor Portal, if you created 3 products, you must fill the 3 strings with the 3 product SKUs, for instance:
string ITEM_1_SKU = "NameOfTheGame_NameOfTheProduct01"; string ITEM_2_SKU = "NameOfTheGame_NameOfTheProduct02"; string ITEM_3_SKU = "NameOfTheGame_NameOfTheProduct03";
3.5 – Then comes the localTesting variable, which must be set as TRUE while you’re testing the IAPs offline.
*the localTesting variable must be set to FALSE when you build the Submission version of the app, otherwise the users won’t be able to make in-app purchases
3.6 – At the function Start you delegate events from BlackBerryIAP.cs (which is inside the BlackBerryIAP gameObject at the Demo scene). For instance: the PurchaseSuccessful function is delegated to the PurchaseSuccesfulEvent event, which is triggered everytime a purchase is completed.
3.7 – At the OnGui function, you will see Demo scene’s buttons (“Purchase SKU 1”, “Purchase SKU2”, etc).
3.8 – When one of the “Purchase SKU” buttons from OnGui is pressed, he calls the BuySKU function (which is located below OnGui), which requests the product purchase calling BlackBerryIAP.Purchase(sku, null, null, null, null, null, null)
3.9 – When the purchase is completed, the PurchaseSuccessfulEvent event from BlackBerryIAP.cs is triggered, then the PurchaseSuccessful function is called.
3.10 – From inside the PurchaseSuccessful function, you must “tell” WHAT happens when the product purchase is successful. The args.DigitalGoodSku variable inside this function is the SKU string from the product that was purchased.
There are other useful events like:
-ExistingPurchasesSuccessfulEvent, which loads the list of every product that the user purchased.
-GetPriceSuccessfulEvent, which gets the product’s price.
Use those events according to your project’s needs.
This is all you need, now check the test methods below.
Testing In-App Purchases
There are 2 ways to test the In-App Purchases:
Local Testing: doesn’t requires you to upload the game into the Vendor Portal. To do it, you need to:
-Set the localTesting variable from the BlackBerryIAPTest.cs class as TRUE.
-Install the game in your device
-Try to purchase the products
Sandbox: it’s the safer way, because it opens the default BlackBerry World’s purchase pop-up, asking login and user’s payment details. To use it, you need to make 2 things, 1 at your computer, and the other at your BlackBerry smartphone/tablet. Both are explained below:
1. At your computer:
-Build a version with the localTesting variable from the BlackBerryIAPTest.cs class set as FALSE
-Upload this version of your game at the Manage Products page at the Vendor Portal, leaving it with Draft status
-Click Sandbox at the Vendor Portal
-Click “Add New User”
-Fill the form with a BlackBerry World account e-mail which will be used to test the game and the In-App Purchases
2. At your smartphone/tablet:
-Open the BlackBerry World app
-Open the “Settings” at the BlackBerry World app, dragging your finger down from the TOP of your device’s screen
-Tap “Debug/Development Mode”
-Type your game’s ID (which you can find at your app’s “Edit Product” page at the Vendor Portal)
-IF BlackBerry World is up to date, you will see your game’s download page and you will be able to download it. But it can take 2 hours after uploading the game, so if it’s not available right now, give it some time.
-After downloading the game, you just need to make the in-app purchases using the account you created at the Sandbox page, you won’t be charged for that.
REMEMBER: the BlackBerryIAP.cs class must be ALWAYS inside a gameobject named BlackBerryIAP (it can’t be different), which must be ALWAYS inside the scene where your user will make the purchases, otherwise, the PurchaseSuccessful event won’t work and the user won’t receive the product.
I hope to have helped you as I know it’s really hard to profit from BlackBerry plaftorm.
BlackBerry gave us a great free plugin, but a really poor documentation.
Marcelo Barce 