Purchasing a product

Before you implement a purchasing scenario in your application, make sure you have the product IDs for the purchase items you want to offer through the application.

To implement a simple product purchasing scenario in your application:

  1. Retrieve the product metadata from Nokia Store. You need the metadata to populate the application's product catalog with purchase items.

    Call the IAPClientPaymentManager.setIAPClientPaymentListener method to set an IAPClientPaymentListener, and then call the IAPClientPaymentManager.getProductData method for the purchase items you want to include in the application's product catalog. You can call the getProductData method for each purchase item separately or for all the purchase items at once (as a list of purchase items). Each getProductData call triggers an asynchronous IAPClientPaymentListener.productDataReceived or IAPClientPaymentListener.productDataListReceived callback, depending on the type of call, with the requested metadata (see the following step).

    The following code snippet sets an IAPClientPaymentListener and requests the metadata for a purchase item whose ID is 123456. The code snippet assumes that the containing class implements IAPClientPaymentListener.

    try {
    // set IAPClientPaymentListener
    IAPClientPaymentManager manager = IAPClientPaymentManager.getIAPClientPaymentManager();
    manager.setIAPClientPaymentListener(this);

    // request metadata for product with ID "123456"
    int status = manager.getProductData("123456");
    if (status != IAPClientPaymentManager.SUCCESS) {
        // do not expect a productDataReceived() callback, handle the failed call
    }
} catch (IAPClientPaymentException e) {
    // handle IAPClientPaymentException from getIAPClientPaymentManager()
}

  2. Display the purchase items to the user.

    Implement the IAPClientPaymentListener.productDataReceived or IAPClientPaymentListener.productDataListReceived method for the metadata callback, retrieve the metadata from the IAPClientProductData object or array returned by the callback, and use the metadata to display the product information in the application UI. How you choose to display the information is up to you. The productDataReceived or productDataListReceived method is called once for each successful IAPClientPaymentManager.getProductData call (see the preceding step).

    The following code snippet implements the productDataReceived method and reads the product title, price, and short description from the IAPClientProductData object.

    public void productDataReceived(int status, IAPClientProductData pd) {

    if (status == IAPClientPaymentListener.OK) {

        String title = pd.getTitle();
        String price = pd.getPrice();
        String sdesc = pd.getShortDescription();

        // update the UI with the product information

    }

}

  3. Implement a buy function in the UI so that the user can purchase the products they want. This can be, for example, a separate Buy button for each purchase item displayed in the product catalog.

    Regardless of how you choose to implement the buy function in the UI, define an IAPClientPaymentManager.purchaseProduct call for each purchase item. When the user chooses to buy a product, the purchaseProduct call for the corresponding purchase item is executed, which in turn triggers the Nokia Store purchase flow.

    The following code snippet triggers the purchase flow for a purchase item whose ID is 123456.

    int purchaseStatus = manager.purchaseProduct("123456", IAPClientPaymentManager.FORCED_AUTOMATIC_RESTORATION);
if (purchaseStatus != IAPClientPaymentManager.SUCCESS) {
    // do not expect a purchaseCompleted() callback, handle the failed call
}

  4. At this point, the In-App Purchase API takes over and starts the payment process with Nokia Store. During this process, your application stays dimmed in the background and does not control the UI. The following steps are described here for informational purposes only:

    1. The API prompts the user to sign in to Nokia Store if they are not already signed in. The API also displays the subsequent dialog where the user can confirm the purchase. The API determines the payment method to be used, which is usually the preferred method specified in the user's Nokia account.

    2. After the purchase is completed, the API sends a purchaseCompleted callback to your application.

    3. After sending the purchaseCompleted callback, the API displays the outcome of the transaction in a dialog. This is either a "Payment successful" message or an informative error message.

    4. After the user has dismissed the transaction outcome dialog by pressing OK, your application regains control of the UI.

  5. If the purchase was successful, grant the user access to the purchased content or service:

    • In case of content protected with built-in DRM, the In-App Purchase API removes the DRM protection automatically. Implement the IAPClientPaymentListener.purchaseCompleted method and use it to call the IAPClientPaymentManager.getDRMResourceAsStream method to access the purchased content and make it available to the user.

      The following code snippet uses the getDRMResourceAsStream method to access the resource.img file of the purchase item with ID 123456.

      public void purchaseCompleted(int status, String purchaseTicket) {
    // Protected resource file
    String resourceFile = "/res/drm/data/resourceid_123456/resource.img";
    if (status == IAPClientPaymentListener.OK) {
        InputStream input = manager.getDRMResourceAsStream(resourceFile);
        // Make the purchased content available to the user in the application UI
    }
}

    • In case of content protected by other means than built-in DRM, or in case of a service, your application must take care of granting the user access to it. Implement the IAPClientPaymentListener.purchaseCompleted method and use it to handle the new content or service.

    • If you are using a back end server to download the content to the user's device, the server must first use the Purchase Ticket Verification API to verify that the product has really been purchased.

© Nokia 2011.