|How to sell items inside your applications using Samsung In-App Purchase(Plasma) Library|
Sep 13, 2011
In-App Purchase(Plasma) Programming Guide
Plasma is an in-app purchase library for Android-based applications for Samsung Apps.
If you want to sell items inside your applications such as in-game coins, levels and others, you may need to set servers up to communicate with, you may need billing infra to gather payments, you may need to manage interactions with users for authentications, payment and many other things. Plasma will simply handle all those things mentioned above and you don’t need to worry about it.
The only thing you need to do is make your applications include Plasma and communicate with it. For example, with in-app purchase of items, your applications just invoke the purchase method of Plasma and receive the result of the purchase in the method of the listener method. Plasma will show dialogs, communicate with Samsung Apps server and invoke the listener methods to return the result of the request.
This guide will explain you about the process of using Plasma from A to Z. Please read this document thoroughly before you use Plasma.
Contents of the distributed package
Plasma is distributed as a ZIP file package. The file name will looks something like ‘plasma-1.0.0.zip’. This file name means Plasma package version 1.0.0. The ZIP file contains following items:
If anything listed above is missed, please contact Samsung Apps Seller Office.
Applying Plasma to your application
Applying Plasma is not that hard because Plasma is very simple and lightweight. There are 4 steps to follow:
Registering your items to Samsung Apps Seller Office
Before you set up and program your application for Plasma, you need to register item group and items to Samsung Apps seller office. The item group is a collection of items and it will be connected to your application in Samsung Apps Seller Office. For example, if there are 10 kinds of special items you need for your game, you need to create one item group for your game and 10 individual items. Registering is really simple.
Connect to Samsung Apps seller office.
Run a web browser and connect to Samsung Apps Seller Office. The address of Samsung Apps Seller Office is http://seller.samsungapps.com. Log in to Samsung Apps Seller Office. If you don’t have any account for Samsung Apps Seller Office, you can make your own. After you have logged in Samsung Apps Seller Office, select Item in Applications menu.
Register your item group
Click on Add Item Group button. Enter the title and description for your item group and press OK button to add a new item group. After the register is finished, you can see the item group is added in the list. Please remember the value of Item Group ID for later use. That value should be passed to Plasma programmatically.
Register your items to the item group
In the item group list, click on the item group you added above and you will see Item Group ID Detail View. Click on Add Item button to add an item to the item group and Item dialog will pop up. Enter the metadata for your item to the dialog. Each field represents:
After you fill these data, press Confirm button to register and the result popup will be shown. Make it sure that your item is located in the item list.
Setting your application project up to use Plasma
Before making your application to work with Plasma, the application project is required to be configured to use it. To set up, follow the instruction below:
Programming your application to work with Plasma
Programming with Plasma is very similar to programming with Android and other Java libraries. Each function of Plasma can be used as a plain Java method. Before you implement Java codes, you need to attend to the manifest file.
Add permissions to manifest file
Plasma uses some classes and methods which require Android Permission. For example, Plasma retrieves unique device ID from user’s device and sends it to Samsung Apps server when users request purchase items. To add required permissions to your application project, open AndroidManifest.xml and add following permissions:
Below is the content of the manifest file which contains required permissions.
Make an instance of Plasma.
First of all, you need make an instance of Plasma class and construct it by invoking constructor with arguments. The first argument of the constructor is the item group ID which you registered before to Samsung Apps Seller Office and the second one is Activity instance of your application. Plasma shows user interfaces by using the activity instance.
After the instance is initiated, since every request method works asynchronously, you need to set the listener instance for Plasma. The result of the request will be retrieved in the listener asynchronously. In this example, we will implement PlasmaListener in the same class of the application Activity.
Implementing PlasmaListener will be explained later.
In the above code, we are initiating the instance of Plasma with item group ID 100000007513 with this Activity. And this class will also handle the result of every request.
Invoke request methods.
After you set up the instance of Plasma, make your application invoke the methods of Plasma. In this case, for example, we request item information list. The method for requesting item information list is requestItemInformationList.
The first argument is the transaction ID of your request and it will be received with the response for you to distinguish this request from others. The second and third one is start number and end number for your response. Even for the case when the item information list has over 100 items, the following example only requests 15 items from the first one.
Transaction ID will be increased from 0. Managing request by the transaction ID is recommended for stability of your application.
Implement listener interface.
Finally, implement PlasmaListener. You need to implement all the methods defined in PlasmaListener Interface. In each method, the result of the request and the requested data is received as arguments with the transaction ID of the request.
For example, in the following code, the requested item information list is stored in itemInformationList ArrayList. Since we requested 15 item information list from the first one, itemInformationList may contain 15 itemInformations. In those listener methods, you can display or store data of each item by getter methods of ItemInformation instance.
Verifying a Purchase
Plasma’s purchasing process has 3 steps:
The purchase ticket contains the information of one unique purchase transaction. To request a purchase verification on the SamsungApps server, use this information.
Invoking a Purchase Request
A purchase request is handled by the requestPurchaseItem method with an item provided by requestItemInformationList. If the request fails, requestPurchaseItem returns “false”, and if the purchase transaction is successful, returns “true”.
The following code shows how to request a purchase a item:
Implement Listener Interface for Getting a Purchase Ticket
Two listener methods should be implemented to receive a response to a purchase request. The first listener method is onPurchaseItemInitialized, which is called when a purchase transaction is successfully initialized at the start of the purchase.
At this point, the purchase ticket is issued but ticket only means that a purchase transaction has initialized successfully, the purchase is not yet complete.
If a purchase transaction is successfully initialized, the statusCode of onPurchaseItemInitialized is set as Plasma.STATUS_CODE_SUCCESS. However, if initialization fails, onPurchaseItemFinished will not be called. This is explained in the following section.
Implement Listener Interface for Getting a Result of a Purchase
The next interface to be implemented is onPurchaseItemFinished. It is called when a user’s purchase transaction is completed, and the final information about purchase transaction is provided.
The final information means a receipt of a purchase transaction which is completed
Please note again that onPurchaseItemFinished is called only when onPurchaseItemInitialized is successfully processed. statusCode, Plasma_STATUS_CODE_SUCCESS , means the purchasing is successful, and the other cases means the purchasing is failed.
Verifying with Samsung Apps server
After onPurchaseItemFinished is successfully called, you can use PurchaseTicket, onPurchaseItemInitialized method’s argument to verify a purchase on the SamsungApps server. It’s simple process. You can send a query to PurchaseTicket’s VerifyURL address the query can be made with combination of PurchaseTicket’s PurchaseID, Param1, Param2 and Param3.
The below is an example of request.
If a request is processed successfully, the JSON response is received as shown. The status value of “true” means a verifying the purchase is successful and “false’ means it has failed.
If your application uses a server-client model, server-to-server purchase verification explained above is recommended.
Testing and uploading your application
When you have finished making your application work with Plasma, the remaining processes are testing and uploading.
Test your application
Testing your application is the most important process for you to sell your items via Samsung Apps. To save your items from illegal use, you need check your implementation and whether Plasma manages in-app purchase properly or not.
For you to test implementation of your application, Plasma provides a nice testing solution. While you are developing your applications, you need to set the developer flag of Plasma as 1 or -1 by using setDeveloperFlag method. Each value represents ‘always returns success and ‘always returns failure’. For example, if you set the value to 1, Plasma returns always success and a good result for every request.
Since retrieving items before your application is published to Samsung Apps is not possible, requestItemInformationList will fail to retrieve item information lists while you are developing. But by setting developer flag as 1, you can retrieve the list successfully. And for another request of purchase, requestPurchaseItem will succeed even if your test Samsung Apps account does not have any proper payment information, such as credit card. As you would expect this is because a test of purchase does not charge any money.
Note that you need to set the value of developer flag to 0 or remove invocation of the method setDeveloperFlag before you upload your application to Samsung Apps, or your application will be rejected.
Upload your application to Samsung Apps Seller Office.
Uploading applications is a little bit complex process. This document only explains about connecting your item group and items to your application.
To start uploading your application, select Add New Application in Applications menu. Fill the required fields for your application. Among the fields, you can see the field In App Purchase and Select Group ID button in Binary section.
Press Select Group ID button and the Available Item Group ID dialog will pop up. From here you can find your application group ID which you registered in the list. Click on the item group ID which you want to connect to your application. This item group ID must be same as the value which you pass to Plasma instance.
For detailed information about uploading applications to Samsung Apps Seller Office, please refer Seller Office User Guide.
If you faced any problems while working with Plasma, please take a look at our FAQs listed below.
I wrote my own test application but it results 9202 error for every request
Before your application is registered and published, the developer flag of Plasma should be 1 or -1 to test your application. Developer flag could be set by setDeveloperFlag method. Note that you need to remove that invocation or set the developer flag to 0 before you upload your application to Samsung Apps Seller Office.
I don’t like the waiting popup Plasma provides
You can turn the waiting popup off if you want to use your own waiting solution. (Something like full-screen images showing waiting message) Please see setShowProgressDialog in the API reference document.
The UI dialog boxes of Plasma vanish after the screen is rotated or locked
You need to override the configuration change handlers for the screen orientation and for hiding the keyboard. Please refer to the overview page in the API reference documentation.
Everything works with developer flag enabled but I get an error with status code 4002 when I unset the flag and try to make a purchase.
Error code 4002 occurs when the customers attempts to purchase an item that does not exist. The items are not available until the app is certified. Until the certification process is complete, the items are not included in the database and therefore attempting to purchase items will result in a 4002 error if the developer flag "setDeveloperFlag(1)" is not set. Once the certification process is complete, items can be purchased successfully.
When trying to make in-app purchase, I receive the message “No valid payment methods”
This error occurs because Plasma uses a dynamic class loader to check for available payment methods, and Proguard obfuscates the original name of Plasma's payment method class.
The solution is to set an exception on the Plasma related class name, by adding "-keep class com.samsungapps.plasma.*PaymentMethod" to proguard.cfg, the ProGuard configuration file.
Related Contents (2)