net.rimlib.blackberry.api.paymentsdk
Class PurchaseArgumentsBuilder

java.lang.Object
  net.rimlib.blackberry.api.paymentsdk.PurchaseArgumentsBuilder

public class PurchaseArgumentsBuilder
extends java.lang.Object

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() );
 

Required Arguments

• Digital good ID / Digital good SKU

  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.

Optional Arguments

The optional purchase arguments are used to customize the purchase experience for the end user.

• Digital good name

  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.

• Purchasing app name / Purchasing app icon

  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

  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.

See Also:

PaymentEngine, PurchaseArguments

Field Summary

static java.lang.String	PURCHASE_VENDOR_CONTENT_ID
static java.lang.String	PURCHASE_VENDOR_CUSTOMER_ID
static java.lang.String	REQUESTID_REQUESTOR_PID
static java.lang.String	REQUESTOID_PAYER_DISPLAY_NAME
static java.lang.String	REQUESTOID_REQUESTOR_DISPLAY_NAME
static java.lang.String	REQUESTOID_URL_DISPLAY_NAME_OF_URL
static java.lang.String	REQUESTOID_URL_TO_LAUNCH_VENDOR_APPLICATION

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(java.lang.String digitalGoodId) Sets the ID of the digital good to be purchased.
PurchaseArgumentsBuilder	withDigitalGoodName(java.lang.String digitalGoodName) Sets the name of the digital good to be purchased.
PurchaseArgumentsBuilder	withDigitalGoodSku(java.lang.String digitalGoodSku) Sets the SKU of the digital good to be purchased.
PurchaseArgumentsBuilder	withMetadata(java.lang.String metadata) Sets the metadata to be associated with the purchase.
PurchaseArgumentsBuilder	withProperty(java.lang.String tag, java.lang.String value) Sets additional properties that will be passed to the PS with the given tag and value.
PurchaseArgumentsBuilder	withPurchasingAppIcon(net.rim.device.api.system.Bitmap purchasingAppIcon) Sets the icon of the application requesting the purchase.
PurchaseArgumentsBuilder	withPurchasingAppName(java.lang.String purchasingAppName) Sets the name of the application requesting the purchase.
PurchaseArgumentsBuilder	withVendorCustomerId(java.lang.String vendorid) Sets the PID (From the Vendor's separate BBID for this user), provided by the vendor.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PURCHASE_VENDOR_CUSTOMER_ID

public static final java.lang.String PURCHASE_VENDOR_CUSTOMER_ID

See Also:

Constant Field Values

PURCHASE_VENDOR_CONTENT_ID

public static final java.lang.String PURCHASE_VENDOR_CONTENT_ID

See Also:

Constant Field Values

REQUESTID_REQUESTOR_PID

public static final java.lang.String REQUESTID_REQUESTOR_PID

See Also:

Constant Field Values

REQUESTOID_REQUESTOR_DISPLAY_NAME

public static final java.lang.String REQUESTOID_REQUESTOR_DISPLAY_NAME

See Also:

Constant Field Values

REQUESTOID_PAYER_DISPLAY_NAME

public static final java.lang.String REQUESTOID_PAYER_DISPLAY_NAME

See Also:

Constant Field Values

REQUESTOID_URL_DISPLAY_NAME_OF_URL

public static final java.lang.String REQUESTOID_URL_DISPLAY_NAME_OF_URL

See Also:

Constant Field Values

REQUESTOID_URL_TO_LAUNCH_VENDOR_APPLICATION

public static final java.lang.String REQUESTOID_URL_TO_LAUNCH_VENDOR_APPLICATION

See Also:

Constant Field Values

Constructor Detail

PurchaseArgumentsBuilder

public PurchaseArgumentsBuilder()

Creates a new builder.

Method Detail

withDigitalGoodId

public PurchaseArgumentsBuilder withDigitalGoodId(java.lang.String digitalGoodId)

Sets the ID of the digital good to be purchased.

Parameters:

digitalGoodId - The digital good's ID.

Returns:

A reference to the current builder for method chaining.

withVendorCustomerId

public PurchaseArgumentsBuilder withVendorCustomerId(java.lang.String vendorid)

Sets the PID (From the Vendor's separate BBID for this user), provided by the vendor. For purchase.

Parameters:

The - PID (From the Vendor's separate BBID for this user), provided by the vendor. For purchase. Optional parameter.

Returns:

A reference to the current builder for method chaining.

withDigitalGoodName

public PurchaseArgumentsBuilder withDigitalGoodName(java.lang.String digitalGoodName)

Sets the name of the digital good to be purchased.

Parameters:

digitalGoodName - The digital good's name.

Returns:

A reference to the current builder for method chaining.

withPurchasingAppName

public PurchaseArgumentsBuilder withPurchasingAppName(java.lang.String purchasingAppName)

Sets the name of the application requesting the purchase.

Parameters:

purchasingAppName - The purchasing application's name.

Returns:

A reference to the current builder for method chaining.

withPurchasingAppIcon

public PurchaseArgumentsBuilder withPurchasingAppIcon(net.rim.device.api.system.Bitmap purchasingAppIcon)

Sets the icon of the application requesting the purchase.

Parameters:

purchasingAppIcon - The purchasing application's icon.

Returns:

A reference to the current builder for method chaining.

withMetadata

public PurchaseArgumentsBuilder withMetadata(java.lang.String metadata)

Sets the metadata to be associated with the purchase.

Parameters:

metadata - The metadata to be associated with the purchase.

Returns:

A reference to the current builder for method chaining.

withDigitalGoodSku

public PurchaseArgumentsBuilder withDigitalGoodSku(java.lang.String digitalGoodSku)

Sets the SKU of the digital good to be purchased.

Parameters:

digitalGoodSku - The digital good's SKU.

Returns:

A reference to the current builder for method chaining.

withProperty

public PurchaseArgumentsBuilder withProperty(java.lang.String tag,
                                             java.lang.String value)

Sets additional properties that will be passed to the PS with the given tag and value. Tags and values that are supported and how there are handled will be published by the Payment Server.

Parameters:

tag - The key to sent to server and associated with value.

value - The value to sent to server and associated with key. This tag value pair will be both be passed to the server.

Returns:

A reference to the current builder for method chaining.

Throws:

An - ReservedKeyUsed exception if the tag is already used by the system.

build

public PurchaseArguments build()

Builds a PurchaseArguments object containing all the arguments set with the withXXX methods.

Returns:

A new PurchaseArguments object.