|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectnet.rimlib.blackberry.api.payment.PurchaseArgumentsBuilder
public final class PurchaseArgumentsBuilder
Builds a PurchaseArguments
object used for initiating a digital good
purchase via PaymentEngine.purchase(PurchaseArguments)
.
A PurchaseArguments
object is created by instantiating a builder, invoking
any number of the withXXX()
methods to set the desired arguments,
and invoking the build()
method. The withXXX()
methods return a
reference to the builder object so they can be chained together for better
readability as seen in the following example:
PurchaseArgumentsBuilder arguments = new PurchaseArgumentsBuilder() .withDigitalGoodId( "1234" ) .withDigitalGoodName( "My Digital Good" ) .withPurchasingAppName( "My Application" ); PaymentEngine engine = PaymentEngine.getInstance(); engine.purchase( arguments.build() );
Only the ID or SKU of the digital good to be purchased is required to create a
valid PurchaseArguments
object; it is not necessary to provide both.
If both the ID and SKU are provided, then the ID takes precedence; the SKU is only
used if the digital good cannot be located on the Payment Service server based
on the ID. The ID and SKU are set with the withDigitalGoodId(String)
and
withDigitalGoodSku(String)
methods, respectively.
A digital good name should be provided in the case where a single ID/SKU represents
multiple digital goods on the Payment Service server, and a more specific digital
good name should be displayed on the purchase screen. For example, if a game
sells additional levels at a single pricing tier, a generic "My game level" digital
good can be registered in the Vendor Portal for BlackBerry App World
and used for all such levels. However, at purchase time, the game application should
override "My game level" with the name of the level being purchased. In this way,
the end user is aware of exactly what they are purchasing on the purchase confirmation
screen. The digital good name is specified with the withDigitalGoodName(String)
method.
The banner that is displayed along the top of the purchase and BlackBerry ID login
screens displays the name and icon of the application the purchase is being made
from (i.e., the purchasing application). To customize the name and icon that
are displayed, simply provide them as arguments. If the name or icon are not
provided as arguments, then they are retrieved from the purchasing application's
descriptor. However, this may not work for applications that register with the
home screen dynamically. In these cases, it is highly recommended that the purchasing
application explicitly provide a name and icon as part of the purchase arguments.
The purchasing application name and icon are set with the withPurchasingAppName(String)
and withPurchasingAppIcon(Bitmap)
methods, respectively.
Metadata offers the application developer a way to store information about each
purchase on the Payment Service server, and to retrieve that data via
PaymentEngine.getExistingPurchases(boolean)
. For example, assume a book vendor
offers many titles at a single pricing tier, but registers them in the vendor
portal as a single digital good. In this case, the ISBN of the book could be provided
as metadata to uniquely identify the digital good that was purchased. The entire
list of purchased books can then be retrieved at any time by obtaining previous
purchases via the PaymentEngine.getExistingPurchases()
method, filtering
on the book's digital good ID, and finally enumerating the ISBNs in the metadata
of each purchase.
The metadata is set with the withMetadata(String)
method.
PaymentEngine
,
PurchaseArguments
Constructor Summary | |
---|---|
PurchaseArgumentsBuilder()
Creates a new builder. |
Method Summary | |
---|---|
PurchaseArguments |
build()
Builds a PurchaseArguments object containing all the arguments set with the
withXXX methods. |
PurchaseArgumentsBuilder |
withDigitalGoodId(String digitalGoodId)
Sets the ID of the digital good to be purchased. |
PurchaseArgumentsBuilder |
withDigitalGoodName(String digitalGoodName)
Sets the name of the digital good to be purchased. |
PurchaseArgumentsBuilder |
withDigitalGoodSku(String digitalGoodSku)
Sets the SKU of the digital good to be purchased. |
PurchaseArgumentsBuilder |
withMetadata(String metadata)
Sets the metadata to be associated with the purchase. |
PurchaseArgumentsBuilder |
withPurchasingAppIcon(net.rim.device.api.system.Bitmap purchasingAppIcon)
Sets the icon of the application requesting the purchase. |
PurchaseArgumentsBuilder |
withPurchasingAppName(String purchasingAppName)
Sets the name of the application requesting the purchase. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public PurchaseArgumentsBuilder()
Method Detail |
---|
public PurchaseArgumentsBuilder withDigitalGoodId(String digitalGoodId)
digitalGoodId
- The digital good's ID.
public PurchaseArgumentsBuilder withDigitalGoodSku(String digitalGoodSku)
digitalGoodSku
- The digital good's SKU.
public PurchaseArgumentsBuilder withDigitalGoodName(String digitalGoodName)
digitalGoodName
- The digital good's name.
public PurchaseArgumentsBuilder withPurchasingAppName(String purchasingAppName)
purchasingAppName
- The purchasing application's name.
public PurchaseArgumentsBuilder withPurchasingAppIcon(net.rim.device.api.system.Bitmap purchasingAppIcon)
purchasingAppIcon
- The purchasing application's icon.
public PurchaseArgumentsBuilder withMetadata(String metadata)
metadata
- The metadata to be associated with the purchase.
public PurchaseArguments build()
PurchaseArguments
object containing all the arguments set with the
withXXX
methods.
PurchaseArguments
object.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |