|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectnet.rimlib.blackberry.api.payment.PaymentEngine
public final class PaymentEngine
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.
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.
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 |
---|
public static final int CONNECTION_MODE_LOCAL
setConnectionMode()
method.
public static final int CONNECTION_MODE_NETWORK
setConnectionMode()
method.
Method Detail |
---|
public static PaymentEngine getInstance()
PaymentEngine
class, or null
if the BlackBerry device does not have BlackBerry App World 2.1 or higher
installed.
PaymentEngine
or null
.public Purchase purchase(PurchaseArguments arguments) throws IllegalArgumentException, PaymentException
PurchaseArguments
.
arguments
- Contains information about the digital good to be purchased.
Purchase
object containing information about the
successful purchase.
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.public Purchase[] getExistingPurchases(boolean allowRefresh) throws PaymentException
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.
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.
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.public void setConnectionMode(int mode) throws IllegalArgumentException
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.
mode
- The new connection mode. Must be one of the CONNECTION_MODE_*
constants.
IllegalArgumentException
- if mode
is not one of the CONNECTION_MODE_*
constants.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |