Developing your application

You can call DigitalGoods.get() to retrieve a list of all the digital goods available for purchase within your application.

You can retrieve available SKUs for your application by invoking DigitalGoods.get(DigitalGoodsListingListener listener), which uses a callback listener. When invoking this asynchronous method, consider the following points:

• To prevent garbage collection, assign the callback object to a class field so that the calling application maintains a reference for the listener. This will prevent garbage collection.
• Do not use a synchronous wrapper because it blocks the event thread, and the callback does not return.

Invoking get() returns an array of DigitalGood objects through the Success method of the DigitalGoodsListingListener. Each result in the array contains details about a purchase, such as the SKU, vendor, name of the digital good, short and long descriptions, and the PriceSet of the digital good. Details of the digital good are stored locally on the BlackBerry device.

private DigitalGoodsListingListener listener;
public void getChildItems() {
    listener = new DigitalGoodsListingListener() {
            
        public void error( String message, int errorCode ) {
            // Handle error
        }
        
        public void success( DigitalGood[] digitalGoods ) {
            // Handle the digital goods
        }
    };
        
    DigitalGoods.get(listener);
}

The process for purchasing digital goods is designed to be consistent for each payment type and for all BlackBerry device users.

1. A user clicks a purchase option for digital goods in your application.

   
   

   
   
   

2. The application creates a PurchaseArguments object which contains information about the digital goods.

   PurchaseArgumentsBuilder arguments = new PurchaseArgumentsBuilder()
       .withDigitalGoodSku( "abc123" )
       .withDigitalGoodName( "Adventures of a BlackBerry Java Developer" )
       .withPurchasingAppName( "My eBooks" )
       .withMetadata ( "ISBN 34560202010" );

3. The application invokes PaymentEngine.purchase(PurchaseArguments) to initiate the purchase request and send information about the digital goods to the Payment Service server.

   try 
   {
       PurchaseResult purchaseResult = engine.purchase(arguments.build());
   } 
   catch (PaymentException e) 
   {
       Dialog.inform(e.getMessage());
   }

4. If the user isn't logged in using a BlackBerry ID account, the application prompts the user to provide login information without requiring that the user leave the application.

   
   

   
   
   

5. The application prompts the user to confirm the purchase using the default payment type. The user can change the payment type or set up a new payment type.

   
   

   
   
   

6. The Payment Service server verifies that the digital goods are valid and processes the purchase through the payment provider.
7. Depending on the results of the purchase attempt, one of the following events occurs:
   • If the purchase request is successful, the Payment Service server returns a PurchaseResult object to the application that contains details about the successful purchase. If the application utilizes a content server, the Payment Service server can send information about the successful purchase to the content server as well.
   • If the purchase request is unsuccessful, the application throws an exception. For information about handling exceptions, view the API reference for the Payment Service SDK.
8. If the purchase attempt is successful, the application provides the digital goods to the user in the manner that you designed.

Before you present BlackBerry device users with purchase options, you can verify that in-app purchases are available. You can use the PaymentEngine.isAppWorldInstalledAndAtCorrectVersion() method to check for the presence of the minimum required version of the BlackBerry World storefront. If the required version isn't available, your application can't invoke any of the Payment Service APIs.

You may want to design your application to restrict users from seeing purchase options for digital goods if they don't have BlackBerry World 3.1 installed on their devices. You can also catch the AppWorldUpdateRequired exception that can be thrown, and then prompt the user to upgrade their BlackBerry World client to the latest version by calling the PaymentEngine.upDateAppWorld() method.

The following code sample demonstrates how to create a PaymentEngine object, and verify that in-app purchases are supported on the device.

try{
	if (PaymentEngine.isAppWorldInstalledAndAtCorrectVersion()) {
		PaymentEngine engine = PaymentEngine.getInstance();
		//code that is executed if in-app payments are available
    }
} catch(AppWorldUpdateRequired awur) {
	//launches browser for user to upgrade their BlackBerry App World client
    PaymentEngine.upDateAppWorld();
}

You can retrieve information about past purchases by invoking PaymentEngine.getExistingPurchases(boolean allowRefresh) for a synchronous call, or PurchaseHistory.get(PurchaseHistoryListingListener listener) for an asynchronous call. A record of past purchases is necessary if you want to customize your application to reflect past purchases, or if you want to implement a subscription model that initiates recurring purchases.

Invoking getExistingPurchases() returns an ExistingPurchasesResult object. You can retrieve an array of Purchase objects that represent existing purchases by invoking ExistingPurchasesResult.getPurchases(). Each result in the array contains details about a purchase, such as the SKU, digital good ID, metadata and the date of the purchase.

The allowRefresh parameter is a Boolean value that indicates whether the application can retrieve the records of purchases from the Payment Service server, or that the application can only retrieve records that are stored on the BlackBerry device. To retrieve records from the Payment Service, log in using a BlackBerry ID. To retrieve records from the BlackBerry device, you do not need to log in. You may choose to query the Payment Service server after a device switch because records of purchases might not be stored on the BlackBerry device. An indeterminate progress dialog appears while the user's purchase history is retrieved from the Payment Service server.

try
{
    ExistingPurchasesResult result = engine.getExistingPurchases(true);
    Purchase[] resultPurchases = result.getPurchases();
}
catch (PaymentException e)
{
    //code that is executed if an exception is thrown
}

private PurchaseHistoryListingListener listener;
public void getPurchaseHistory() {
    listener = new PurchaseHistoryListingListener() {
            
        public void error( String message, int errorCode ) {
            // Handle error
        }
        
        public void success( Purchase[] purchases ) {
            // Handle the purchases
        }
    };
    
    PurchaseHistory.get(listener);
}

Before initiating a purchase by invoking PaymentEngine.purchase(), create a PurchaseArguments object to represent the digital goods. The Payment Service API provides a builder class for creating a PurchaseArguments object on the device.

You can invoke the appropriate methods on the PurchaseArgumentsBuilder object depending on the information that you provide with the purchase request. For a purchase to be authenticated, you must provide either the SKU or the ID for the digital goods. The SKU is a value that you specify when you register the digital goods in the vendor portal for the BlackBerry World storefront. You can invoke DigitalGoods.get() to retrieve the SKUs for the digital goods. To determine which SKUs are available during runtime, call DigitalGoods.get(). The ID is an identifier that is assigned to your digital goods in the vendor portal.

If the purchase request is successful, a PurchaseResult object is returned, which contains information about the purchase. If the purchase is unsuccessful, an exception is thrown.

PurchaseArgumentsBuilder arguments = new PurchaseArgumentsBuilder()
    .withDigitalGoodId( "1234" )
    .withDigitalGoodName( "My Product" )
    .withDigitalGoodSku( "Ab34t2eC" )
    .withPurchasingAppName( "My Application" );
try 
{
    PurchaseResult result = engine.purchase(arguments.build());
} 
catch (IllegalArgumentException iae) 
{
    //code that is executed if an exception is thrown
} 
catch (PaymentException pe) 
{
    //code that is executed if an exception is thrown
}

If you choose to offer subscription-based digital goods in your application, you can use the Payment Service API to manage the subscriptions.

If you sell your application as a subscription on the BlackBerry World storefront, the Payment Service confirms the validity of each user subscription. You can invoke purchase history methods to return objects that represent the parent application. These methods verify the user's current subscription status to determine whether the user should continue using the application.

The Payment Service API provides a number of exceptions that help give you fine-grained control over how your application handles errors that might occur during the in-app purchase process. You should make sure to catch the appropriate exceptions when you invoke the purchase() and getExistingPurchases() methods. Each method can throw a number of different exceptions, but you might not need to catch all of them unless you want to process each exception differently. The UserCancelException class, PaymentServerException class, DigitalGoodNotFoundException class, and IllegalApplicationException class are all subclasses of the PaymentException class, so if you configure your application to catch only PaymentException, you can process all the exceptions the same way.

There are cases where you will want to handle exceptions differently. For example, if a BlackBerry device user cancels a purchase, you may want to display a particular message, or if a purchase fails because of a problem with the Payment Service, you might want to retry the purchase. Each exception has a human-readable error message that you can display by invoking getMessage() on the exception.

For descriptions of all the exceptions that can occur, view the API reference for the Payment Service SDK.

1. Import the required classes and interfaces.

   import net.rimlib.blackberry.api.paymentsdk.*;
   import net.rim.device.api.ui.*;
   import net.rim.device.api.ui.component.*;
   import net.rim.device.api.ui.container.*;

2. Create the application framework by extending the UiApplication class. In main(), create an instance of the new class and invoke enterEventDispatcher() to enable the application to receive events. In the application constructor, invoke pushScreen() to display the custom screen for the application. In the following code sample, the PurchaseDemoScreen class, described in step 3, represents the custom screen.

   public class PurchaseDemo extends UiApplication
   {
       public static void main(String[] args) 
       {
           PurchaseDemo theApp = new PurchaseDemo();
           app.enterEventDispatcher();  
       }
       public PurchaseDemo() 
       {   
           pushScreen(new PurchaseDemoScreen());
       }
   }

3. Create the framework for the custom screen by extending the MainScreen class and implementing FieldChangeListener.

   private static class PurchaseDemoScreen extends MainScreen implements FieldChangeListener
   {
       public PurchaseDemoScreen()
       {
   
       }
   }

4. In PurchaseDemoScreen, declare the application's instance variables and create an instance of the PaymentEngine class by invoking getInstance().

   private ButtonField buyButton;
   private ButtonField displayButton;
   private BasicEditField digitalGoodName;
   private BasicEditField digitalGoodSku;
   
   private PaymentEngine engine = PaymentEngine.getInstance();

5. In the screen constructor, create an if statement to check whether the PaymentEngine object is created successfully (meaning that in-app purchases are available). Within the else statement, create an error message to indicate that in-app purchases are unavailable.

   if (engine != null)
   {
   
   }
   else
   {
       errorMessage = new RichTextField("Sorry, in-app purchases are unavailable");
       add(errorMessage);
   }

6. Within the if statement, create the UI for the application. The UI features two BasicEditField objects that allow the user to type a SKU and a name for digital goods, and two ButtonField objects that either initiate a purchase or display a record of past purchases. Set change listeners on the buttons.

   digitalGoodName = new BasicEditField("Digital Good Name:  ", "Sample Good");
   add(digitalGoodName);
   
   digitalGoodSku = new BasicEditField("Digital Good SKU:   ", "abc123");
   add(digitalGoodSku);
           		
   HorizontalFieldManager hfm = new HorizontalFieldManager();
   add(hfm);
    		
   buyButton = new ButtonField("Buy");
   buyButton.setChangeListener(this);
   hfm.add(buyButton);
           		
   displayButton = new ButtonField("Display Purchases");
   displayButton.setChangeListener(this);
   hfm.add(displayButton);

7. In PurchaseDemoScreen, override fieldChanged() to customize the behavior that is invoked when a user clicks a button.

   public void fieldChanged(Field field, int context)
   {
   
   }

8. Within fieldChanged() create an if statement that checks which button is clicked.

   if (field == buyButton)
   {
   
   }
   else if (field == displayButton)
   {
   
   }

9. Within the if statement, which is executed if the user clicks Buy, invoke getText() on the BasicEditField objects to obtain the current SKU and name. Create a PurchaseArguments object by using the PurchaseArgumentsBuilder class and invoke the appropriate methods to pass the SKU and the name as arguments.

   String name = digitalGoodName.getText();
   String sku = digitalGoodSku.getText();
           		
   PurchaseArgumentsBuilder arguments = new PurchaseArgumentsBuilder()
       .withDigitalGoodSku( sku )
       .withDigitalGoodName( name )
       .withMetadata( name )
       .withPurchasingAppName( "Payment Service SDK Demo" );

10. In a try/catch block, invoke purchase() and pass the PurchaseArguments object as a parameter. Catch the appropriate exceptions.

    try 
    {
        PurchaseResult purchase = engine.purchase(arguments.build());
        Dialog.inform("Purchase of " +purchase.getMetadata()+ " is successful.");
    }
    catch (IllegalArgumentException e) 
    {
        Dialog.inform(e.getMessage());
    }
    catch (PaymentException e) 
    {
        Dialog.inform(e.getMessage());
    }

11. Within the else if statement, which is executed if the user clicks Display Purchases, invoke PurchaseHistoryListingListener with an anonymous class to execute the method's callback. Verify that the Purchase objects are not empty by invoking getExistingPurchases(). Create an if statement that deletes any records of past purchases that are already displayed on the screen. Create a for loop that prints the SKU and the name of the digital goods from the updated record of past purchases. Invoking PurchaseHistory.get() returns an array of purchase history objects through the success method of the PurchaseHistoryListeningListener. Pass the listener to PurchaseHistory.get().

    purchaseHistoryListener = new PurchaseHistoryListingListener() {
    
      public void error( String message, int errorCode ) {
        Dialog.inform( message );
      }
    
      public void success( Purchase[] purchases ) {
        if( purchases.length != 0 ) {
          if( getFieldCount() > 3 ) {
            deleteRange( 3, ( getFieldCount() - 3 ) );
          }
          for( int i = 0; i < purchases.length; i++ ) {
            RichTextField purchaseRecord = new RichTextField( "Name: " +purchases[ i ].getMetadata()+ " SKU: " + purchases[ i ].getDigitalGoodSku() );
            add( purchaseRecord );
          }
        } else {
          Dialog.inform( "No existing purchases" );
        }
      }
    };
    
    PurchaseHistory.get(purchaseHistoryListener);