Restoring a product

Retrieve a list of restorable products from Nokia Store. You need the list to populate the application's product catalog with restorable purchase items.

Call the IAPClientPaymentManager.setIAPClientPaymentListener method to set an IAPClientPaymentListener, and then call the IAPClientPaymentManager.getRestorableProducts method. The getRestorableProducts call triggers an asynchronous IAPClientPaymentListener.restorableProductsReceived callback with the requested list (see the following step).

The following code snippet sets an IAPClientPaymentListener and requests a list of restorable products. The code snippet assumes that the containing class implements IAPClientPaymentListener.

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

    // Request a list of restorable products
    int status = manager.getRestorableProducts;
    if (status != IAPClientPaymentManager.SUCCESS) {
        // Do not expect a restorableProductsReceived() callback,
        // instead handle the failed call
    }
} catch (IAPClientPaymentException e) {
    // Handle IAPClientPaymentException from getIAPClientPaymentManager()
}

Display the restorable products to the user.

Implement the IAPClientPaymentListener.restorableProductsReceived method for the callback, retrieve the restorable product metadata from the list of IAPClientProductData objects 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 following code snippet implements the restorableProductsReceived method and reads the product title, price, and short description from each returned IAPClientProductData object.

public void restorableProductsReceived(int status, IAPClientProductData[] productDataList) {

    if (status == IAPClientPaymentListener.OK) {

        String title;
        String price;
        String sdesc;

        for (int i=0; i<productDataList.length; i++) {

            title = productDataList[i].getTitle();
            price = productDataList[i].getPrice();
            sdesc = productDataList[i].getShortDescription();

            // Update the UI with the product information

        }

    }

}

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

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

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

int restoreStatus = manager.restoreProduct("123456", IAPClientPaymentManager.DEFAULT_AUTHENTICATION);
if (restoreStatus != IAPClientPaymentManager.SUCCESS) {
    // Do not expect a restorationCompleted() callback,
    // instead handle the failed call
}

At this point, the In-App Purchase API takes over and starts the restoration process with Nokia Store. If the restoration is successful, the In-App Purchase API unlocks the restored content automatically.

If the restoration is successful, grant the user access to the restored content.

Implement the IAPClientPaymentListener.restorationCompleted method and use it to call the IAPClientPaymentManager.getDRMResourceAsStream method to access the restored content and make it available to the user.

The following code snippet uses the getDRMResourceAsStream method to access a purchase item whose ID is 123456.

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

Retrieve a list of restorable products from your back end server based on user and device information. You need the list to populate the application's product catalog with restorable purchase items.

To retrieve information about the current user and device:

1. Call the IAPClientPaymentManager.setIAPClientPaymentListener method to set an IAPClientPaymentListener, and then call the IAPClientPaymentManager.getUserAndDeviceId method. The getUserAndDeviceId call triggers an asynchronous IAPClientPaymentListener.userAndDeviceDataReceived callback with the requested user and device information.

2. Implement the IAPClientPaymentListener.userAndDeviceDataReceived method for the callback, and retrieve the user and device information from the IAPClientUserAndDeviceData object returned by the callback.

3. Send the user and device information to your back end server for purposes of determining which products the user is eligible to restore. The back end server must return a list of restorable products. The back end server implementation is completely up to you.

Display the restorable products to the user, and implement a restore function in the UI so that the user can restore the products they want. How you choose to display the product information and implement the restore function is up to you.

If the restoration is successful, grant the user access to the restored content or service. How you choose to implement this is up to you.

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 and that the user is eligible to restore it.