net.rimlib.blackberry.api.payment
Class PaymentEngine

java.lang.Object
  extended by net.rimlib.blackberry.api.payment.PaymentEngine

public final class PaymentEngine
extends Object

API that permits BlackBerry device users to initiate the purchase of digital goods from within your application. For example, this API can be used to allow users to purchase additional levels in a gaming application, music from a radio application, or any other digital good that your application offers. The digital good being purchased must be registered in the Vendor Portal for BlackBerry App World and must be associated with the application from where the purchase option is offered. In order to purchase digital goods, users must have BlackBerry App World 2.1 or higher installed on their devices.

Some of the methods in this class (notably purchase(PurchaseArguments) and getExistingPurchases(boolean)) require user input and interaction with the Payment Service server, and can take a long time to complete. For this reason, if these methods are invoked from the application's event thread, a modal progress dialog is displayed and a separate thread is automatically initiated to handle the network connections and user interaction. If you want to retain control of the UI as your application awaits a response from the Payment Service server, you can invoke these methods on a separate thread.

Before you can invoke any of the methods in PaymentEngine, you must retrieve an instance of the class by invoking getInstance(). If the value of the object is null, in-app purchases are not currently available (occurs if BlackBerry App World 2.1 or higher is not installed). You might want to check to see if in-app purchases are available before you offer purchase options to your users.

Purchases are initiated via the purchase() method. The amount of time that elapses before a response is returned from the Payment Service server depends on how quickly the user completes the purchase process (which may include steps such as signing in with a BlackBerry ID account or setting up a preferred billing method). The purchase() method returns a Purchase object if the purchase attempt succeeds, or throws a PaymentException if the purchase attempt fails.

The purchase() method accepts a PurchaseArguments object as an argument, which contains the information required to send a purchase request to the Payment Service server. Only the ID or SKU of the digital good to be purchased is required in a PurchaseArguments object for a purchase to succeed. You do not have to provide both arguments, and all other arguments are optional. If both the ID and SKU are provided, the ID takes precedence, and the SKU is used only if the digital good could not be located on the Payment Service server based on the ID. See the PurchaseArgumentsBuilder class for definitions of the available purchase arguments and how they affect the purchase process.

If an application requires a list of its digital goods that have already been purchased by the user (for example, to avoid offering users purchase options for digital goods they previously purchased), such a list can be retrieved by invoking the getExistingPurchases() method. This method can require some of the the same user interactions as purchase(), so it can also be a long-running method.

Testing

The Payment Service SDK supports both local and live testing. Local testing is useful if you want to be able to test how your application handles the result of a purchase attempt without making calls to the Payment Service server and without using real currency. The entire purchase process is simulated within the application. The simulated purchase flow also allows you to choose the result of each purchase attempt so that you can verify that your application handles success and failure correctly. To enable local testing, you must invoke setConnectionMode(int) and pass in CONNECTION_MODE_LOCAL as an argument.

Testing against the live Payment Server server is unavailable until after you submit descriptions of your application and the digital goods within your application in the Vendor portal for BlackBerry App World. Until that point, the Payment Service server is unable to recognize the ID or SKU for a digital good when it receives a purchase request from an application.

To test the end-to-end purchase flow without being charged money, you can set up a BlackBerry ID as a test account. The test account allows you to download any applications or digital goods that are associated with your BlackBerry App World vendor account without incurring any costs. Local testing must be turned off for this type of testing, otherwise no network connections will be attempted.

For more information about developing or testing an in-app purchase solution, see the Payment Service SDK Development Guide.

See Also:
Purchase, PurchaseArguments, PurchaseArgumentsBuilder

Field Summary
static int CONNECTION_MODE_LOCAL
          Constant used for enabling local connection mode in the setConnectionMode() method.
static int CONNECTION_MODE_NETWORK
          Constant used for enabling network connection mode in the setConnectionMode() method.
 
Method Summary
 Purchase[] getExistingPurchases(boolean allowRefresh)
          Retrieves a record of the previous successful purchases made by the user from within the calling application.
static PaymentEngine getInstance()
          Retrieves an instance of the PaymentEngine class, or null if the BlackBerry device does not have BlackBerry App World 2.1 or higher installed.
 Purchase purchase(PurchaseArguments arguments)
          Initiates the purchase of a digital good.
 void setConnectionMode(int mode)
          Sets the connection mode used in the application.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CONNECTION_MODE_LOCAL

public static final int CONNECTION_MODE_LOCAL
Constant used for enabling local connection mode in the setConnectionMode() method.

See Also:
Constant Field Values

CONNECTION_MODE_NETWORK

public static final int CONNECTION_MODE_NETWORK
Constant used for enabling network connection mode in the setConnectionMode() method.

See Also:
Constant Field Values
Method Detail

getInstance

public static PaymentEngine getInstance()
Retrieves an instance of the PaymentEngine class, or null if the BlackBerry device does not have BlackBerry App World 2.1 or higher installed.

Returns:
An instance of PaymentEngine or null.

purchase

public Purchase purchase(PurchaseArguments arguments)
                  throws IllegalArgumentException,
                         PaymentException
Initiates the purchase of a digital good. Purchases can be initiated by using either the ID or the SKU of the digital good to be purchased, but it is not necessary to provide both. If customization of the name or icon for the digital good is desired, they can be provided with the PurchaseArguments.

Parameters:
arguments - Contains information about the digital good to be purchased.
Returns:
A Purchase object containing information about the successful purchase.
Throws:
IllegalArgumentException - if both the ID and SKU are null or zero-length.
IllegalApplicationException - if the purchase failed because it was initiated by an application that was not installed via BlackBerry App World.
DigitalGoodNotFoundException - if the purchase failed because a record of the digital good was not found on the Payment Service server.
UserCancelException - if the purchase failed because it was canceled by the user.
PaymentServerException - if the purchase failed because of a problem with the Payment Service server.
PaymentException - if the purchase failed because of an unknown reason.

getExistingPurchases

public Purchase[] getExistingPurchases(boolean allowRefresh)
                                throws PaymentException
Retrieves a record of the previous successful purchases made by the user from within the calling application. If allowRefresh is true, the list of existing purchases is retrieved from the Payment Service server, which has the potential to be a long running operation. If speed is of a higher importance than accuracy and/or user interaction is not desired (for example, in cases where this method is being executed by a background thread), you can set allowRefresh to false to have this method immediately return the purchase results cached on the BlackBerry device (possibly an empty list) without querying the Payment Service server.

Parameters:
allowRefresh - True if the application should refresh the list of purchases from the Payment Service server. False if the application should only retrieve the purchases cached on the device.
Returns:
The existing purchases.
Throws:
IllegalApplicationException - if the purchase retrieval failed because it was initiated by an application that was not installed via BlackBerry App World.
UserCancelException - if the purchase retrieval failed because it was canceled by the user.
PaymentServerException - if the purchase retrieval failed because of a problem with the Payment Service server.
PaymentException - if the purchase retrieval failed because of an unknown reason.

setConnectionMode

public void setConnectionMode(int mode)
                       throws IllegalArgumentException
Sets the connection mode used in the application. If connection mode is set to local, the application does not contact the Payment Service server for any transactions. For purchases, a simulated purchase screen is displayed, allowing the user to choose the result of the purchase. For retrieving existing purchases, only simulated successful purchases are returned. This mode is useful for testing how your application handles the possible results without requiring network connections or currency. THIS MODE SHOULD NOT BE USED IN PRODUCTION CODE.

If connection mode is set to network, purchases and retrievals of existing purchases proceed normally, contacting the Payment Service server as necessary. This is the default connection mode, and applications in production should not modify it.

Parameters:
mode - The new connection mode. Must be one of the CONNECTION_MODE_* constants.
Throws:
IllegalArgumentException - if mode is not one of the CONNECTION_MODE_* constants.


Copyright © 2010 Research In Motion Limited. All Rights Reserved.