In-App Purchase(Plasma) Programming Guide

Understanding Plasma
What is Plasma?

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:

• plasma.jar: The library JAR file. This is the core of Plasma.
• PlasmaTester: A sample Android application project including source code. Since this application was written especially for Plasma best practice, you can understand how to implement your applications to use Plasma. This sample application is very small and has only one Activity for you to understand easily.
• docs: The directory contains this programming guide document (which you are reading now) and the API reference document of Plasma. The API reference document is in Javadoc layout. To browse the APIs, open index.html file in api directory.

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:

1. Register your items to Samsung Apps Seller Office.
2. Set your application project up to use Plasma.
3. Program your application to work with Plasma.
4. Test and upload your application.

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:

• Title: The title of the item. This is equivalent to item name of ItemInformation class.
• Prices: The price tier for the item in US dollars. This price will be converted to equivalent currency unit for another country.
• Description: The description of the item up to 2000 bytes.
• Item Image: The image of the item. This image will be uploaded to Samsung Apps server and you can retrieve this image by downloading via the image URL value of ItemInformation class.
• Download URL: If you want to make your application to download contents from your own server after user purchased items, you can use this field to store the URL. Note that Plasma does nothing with this field.
• Data1 and Data2: These are user-defined fields. You can use these fields for any metadata you want to store.

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:

1. Run Eclipse and open your application project.
2. In your application project, make a folder named libs (for example) and copy the library JAR file to it. If you prefer to another name for the folder, you can use that.
3. Open Project Properties window. In Libraries tab in Java Build Path, select Add External JARs... and select the library JAR file from the folder you made above. You can find the library JAR file is added to JARs and class folders on the build path list. Select OK to apply.
4. Make sure that the library file is added to your application project in Package Explorer.

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:

• android.permission.INTERNET
• android.permission.READ_PHONE_STATE
• android.permission.GET_ACCOUNTS
• android.permission.SEND_SMS

Below is the content of the manifest file which contains required permissions.

<?xml version="1.0" encoding="utf-8"?>
		<manifest xmlns:android=http://schemas.android.com/apk/res/android
				package="com.yourcompany.yourapplication"
				android:versionCode="1"
				android:versionName="1.0">
			...
			<uses-permission android:name="android.permission.INTERNET">
			</uses-permission>
			<uses-permission android:name="android.permission.READ_PHONE_STATE">
			</uses-permission>
			<uses-permission android:name="android.permission.GET_ACCOUNTS">
			</uses-permission>
			<uses-permission android:name="android.permission.SEND_SMS">
			</uses-permission>
			...
		</manifest>

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.

		import com.samsungapps.plasma.*;
		...
		public class MyApplicationActivity extends Activity implements PlasmaListener {
			...
			public void initPlasma() {
				...
				--plasma = new Plasma(--ITEM_GROUP_ID, this);
				--plasma.setPlasmaListener(this);
				...
			}
			...
		}
		...
		private Plasma --plasma = null;
		private static final String --ITEM_GROUP_ID = "100000007513";

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.

public class MyApplicationActivity extends Activity implements PlasmaListener {
			...
			public void requestItemInformation() {
				...
				--plasma.requestItemInformationList(--transactionId ++, 1, 15);
				...
			}
			...
		}
		...
		private int --transactionId = 0;

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.

public class MyApplicationActivity extends Activity implements PlasmaListener {
			...
			@Override
			public void onItemInformationListReceived(int transactionId,
					int statusCode,
					ArrayList itemInformationList) {
					if(statusCode == Plasma.STATUS_CODE_SUCCESS) {
						for (int i = 0; i < itemInformationList.size(); i++) {
							ItemInformation itemInformation
								= itemInformationList.get(i);
							String itemId = itemInformation.getItemId();
							...
						}
					}
					...
			}
			...
		}

Verifying a Purchase

Plasma’s purchasing process has 3 steps:

1. Purchase request
2. Issuing the purchase ticket
3. Complete purchase

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:

public class MyApplicationActivity extends Activity implements PlasmaListener {
	...
	public void requestPurchaseItem (ItemInformation item) {
		...
		--plasma.requestPurchaseItem(--transactionId ++, item.getItemId());
		...
	}
	...
}
...
private int --transactionId = 0;

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.

public class MyApplicationActivity extends Activity implements PlasmaListener {
	...
	@Override
	public void onPurchaseItemInitialized(int transactionId, 
			int statusCode, 
			PurchaseTicket purchaseTicket) {
if(statusCode == Plasma.STATUS_CODE_SUCCESS) {
		String purchaseID = purchaseTicket.getPurchaseId();
		...
		}
		...
	}
	...
}

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

public class MyApplicationActivity extends Activity implements PlasmaListener {
	...
	@Override
	public void onPurchaseItemFinished(int transactionId, 
			int statusCode, 
			PurchasedItemInformation purchaseItemInformation) {
if(statusCode == Plasma.STATUS_CODE_SUCCESS) {
		String paymentID = purchaseItemInformation.getPaymentId();
		...
		}
		...
	}
	...
}

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.

http://uk-odc.samsungapps.com/appsItemVerifyIAPReceipt.as?param1=0938cd2b3cc9da7085efa7134cd9c39566519cd74234bb3c1abb155417ea1b59¶m2=1159bb732a38139de0f3444c9c6997f2f4f922385753c770c76954eee28c2aba¶m3=e5cf0fd50389f0f0c04b0ff41fe8b994255cc0aeb2ebfeb4d48180a4a341c195&purchaseID=7c0f42f544ede980e6eb50d55d65679f08437bed051f80fcc0ec003d57b19091

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.

< The JSON example of successful result>

{"paymentID":"TPMTID201206190000034687","paymentAmount":"1","itemName":"ITM2","itemID":"000000041131","status":"true","purchaseDate":"2012-06-19
15:13:10","itemDesc":"ITM2"}

< The JSON example of failed result >

{"status":"false"} 

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.

public class MyApplicationActivity extends Activity implements PlasmaListener {
			...
			public void initPlasma() {
				...
				--plasma.setDeveloperFlag(1);
				...
			}
			...
		}

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.

Appendixes
Frequently asked questions

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.

History

• 6 Sep 2011: The draft version of this guide document is written.
• 9 Sep 2011: Proofreading was done.
• 26 Oct 2011: Frequently asked question is updated.
• 28 Jun 2012 : Verification API guide for purchase is updated