Release Notes: (1.1.0)
  • Added a new property to SamsungIAPItem - formattedPrice.

Integration Guide - Samsung In-App Purchasing Plugin

Platforms: Android only
Plugin version: 1.1.0
IAP API version: 2

Generally you don't have to dive into the documentation from Samsung, simply follow a few steps below to get the plugin integrated in your App in minutes:

[1] Import the SamsungIAPAndroid.unitypackage file to your project;

[2] Click on the menu item of Unity top menu bar: NeatPlug -> SamsungIAP -> Patch Android Configuration. This is for generating a valid AndroidManifest.xml or patching the existing file with SamsungIAP support.

To integrate Samsung IAP, we need to use custom subclass of UnityPlayerActivity to receive onActivityResult call, if you have used another custom activity and have problem getting all neccessary functions working, please contact our support team.

[3] Find SamsungIAPAgent Prefab and SamsungIAPListener Prefab in Assets/Plugins/NeatPlug/IAP/SamsungIAP/Prefabs/, open the first scene of your game, drag & drop those two prefabs into the scene. Select the SamsungIAPAgent gameObject in Hierarchy Window and fill in:

   · Group Id - Your Samsung IAP Group ID.

   · Test Mode - Check this if you want to test IAP in sandbox. (NOTE: unpublished items will fail if test mode is off)

   · Consumable Skus - The consumable skus you want the plugin to automatically query information for you.(12-digits numbers)

   · Nonconsumable Skus - The non-consumable skus you want the plugin to automatically query information for you.(12-digits numbers)

   · Subscription Skus - The subscription skus you want the plugin to automatically query information for you.(12-digits numbers)

   · Server Receive Receipt URL - Supply this param if you want to post the receipt data to your own server.

[4] To deliver your in-app items when a purchase has successfully completed, you need to handle purchase events, to do so:

  Follow the instructions to handle purchase events:

  · Select the dropped SamsungIAPListener gameObject, locate the SamsungIAPListener.cs script, open it and make some modifications.

  These callbacks are exposed in the script, you can supply your own implementations in them.
Show All   
void OnPurchaseCompleted(SamsungIAPReceipt receipt) { ... }
/**
 * Fired when the purchase successfully completed.
 *
 * This is where you should deliver the item to the user.
 *	 
 * @param receipt
 *           SamsungIAPReceipt - An object which contains the purchase information. 
 *                             { sku, purchaseTime, orderId, purchaseToken, 
 *                               purchaseState, packageName, developerPayload }
 */
void OnPurchaseCompleted(SamsungIAPReceipt receipt)
{
    /// Your code here...   
}
void OnPurchaseFailed(string sku, string err) { ... }
/**
 * Fired when the purchase failed.
 *
 * @param sku
 *           string - IAP item identifier, the Product ID you defined at SamsungApps's publisher site.
 *
 * @param err
 *           string - The reason for failure.
 */
void OnPurchaseFailed(string sku, string err)
{
    /// Your code here...
}
void OnPurchaseCancelled(string sku) { ... }
/**
 * Fired when the purchase cancelled by the user.
 *
 * @param sku
 *           string - IAP item identifier, the Product ID you defined at SamsungApps's publisher site.
 */
void OnPurchaseCancelled(string itemId)
{
    /// Your code here...   
}
void OnPurchaseCancelledBySamsung(string sku) { ... }
/**
 * Fired when the purchase cancelled by Samsung.
 *
 * The cancellation is primarily caused by user's credit card validation failure.
 *
 * @param sku
 *           string - IAP item identifier, the Product ID you defined at SamsungApps's publisher site.
 */
void OnPurchaseCancelledBySamsung(string itemId)
{
    /// Your code here...   
}
void OnBillingSupported(bool supported, string response) { ... }
/**
 * Fired when the check for the In-App Billing support is done.
 * 
 * By default, the plugin will check if In-App Billing is supported on current
 * device as soon as App launches. There are a few cases the check may return false:
 * The version of Samsung Software installed on the device is too old, or the
 * user is using the device in the country where In-App Billing is not supported.
 * For other possible cases, please refer to Samsung developer site.
 * 
 * @param supported
 *             bool - true for supported, false for unsupported.
 * 
 * @param response
 *             string - The response code returned from Samsung IAP API.
 * 
 * The response codes are listed here:
 * ##################################################################################################	
 * IAP_RESPONSE_RESULT_OK             0
 * IAP_RESPONSE_RESULT_UNAVAILABLE    2 
 * IAP_ERROR_INITIALIZATION           -1000
 * IAP_ERROR_NEED_APP_UPGRADE         -1001
 * IAP_ERROR_COMMON                   -1002
 * IAP_ERROR_ALREADY_PURCHASED        -1003
 * IAP_ERROR_WHILE_RUNNING            -1004
 * IAP_ERROR_PRODUCT_DOES_NOT_EXIST   -1005
 * IAP_ERROR_CONFIRM_INBOX            -1006
 * IAP_PAYMENT_IS_CANCELED_BY_STORE   -1100
 * IAP_ERROR_NOT_INSTALLED            -1101
 * IAP_ERROR_INVALID_PACKAGE          -1102
 * IAP_ERROR_NOT_LOGGED_IN            -1103
 * IAP_ERROR_UNKNOWN                  -2000
 * ###################################################################################################	
 */
void OnBillingSupported(bool supported, string response)
{
    /// Your code here...   
}
void OnSubscriptionSupported(bool supported, string response) { ... }
/**
 * Fired when the check for subcription support is done.
 * 	
 * NOTE: Subscription is not yet supported in Samsung IAP V3 by the time the plugin was released.
 * The new version of V3 may add the support in the future, this will be added into the plugin timely,
 * so please check our new version of plugin and upgrade when available if you have this requirement.
 *
 * @param supported
 *             bool - true for supported, false for unsupported.
 * 
 * @param response
 *             string - The response code returned from Samsung IAP API.
 */
void OnSubscriptionSupported(bool supported, string response)
{
    /// Your code here...
}
void OnItemDataReady() { ... }
/**
 * Fired when the item data is ready to query.
 * Do your item query then if you need.
 */
void OnItemDataReady()
{
    /// Your code here...
}
void OnOwnedItemReported(string sku) { ... }
/**
 * Fired when receiving an owned item report event.
 * 
 * This indicates that the item type is "NonConsumable" and the user has already 
 * owned the item. By default the plugin gets notified with the event every time your 
 * app launches, it is suggested that you should redeliver the item to the user here 
 * if the locally saved data record cannot be found. (Probably the user cleared the 
 * PlayerPrefs data or a new device is being used) 
 * 
 * @param sku
 *           string - IAP item identifier, the sku you defined at SamsungApps's publisher site.	
 */
void OnOwnedItemReported(string sku)
{
    /// Your code here...
}
void OnItemAlreadyOwned(string sku) { ... }
/**
 * Fired if the user has already owned this NonConsumable item when a corresponding
 * purchase is attempted.
 *
 * This indicates that the item type is "NonConsumable" and the user has already owned
 * the item. This event is only triggered in case you ignored the default automatic
 * owned item reporting happened in OnOwnedItemReported() at app launches, but 
 * you are not suggested to do so since requiring the user who has already purchased 
 * the NonConsumable item to perform the purchase again, and tell the user "You have already
 * owned the item", is obviously causing confusion.
 *
 * In most cases you should only play with the "OnOwnedItemReported()" event.
 * But you can use this where you really need it to be that way.
 *
 * @param sku
 *           string - IAP item identifier, the sku you defined at SamsungApps's publisher site.	
 */
void OnItemAlreadyOwned(string sku)
{
    /// Your code here...
}
void OnReceiptPosted(string response) { ... }
/**
 * Fired when the receipt is successfully posted to server.
 * 
 * @param response
 *           string - The response from your server.
 * 	
 */
void OnReceiptPosted(string response)
{
    /// Your code here...
}
void OnFailedToPostReceipt(string err) { ... }
/**
 * Fired when the receipt data failed to be posted.
 * 
 * @param err
 *           string - The error string.	
 * 	 
 */
void OnFailedToPostReceipt(string err)
{
    /// Your code here...
}

[5] Call SamsungIAP.Instance().Purchase(string sku) function in your code to initiate a purchase request.

  Initiate a purchase request:

  · SamsungIAP.Instance().Purchase(string sku);

  NOTE: If you don't supply Consumable Product Skus and Nonconsumable Product Skus in the properties of SamsungIAPAgent gameObject, you

            need to call SamsungIAP.Instance().Initialize(...) to provide that information to plugin.

  There are useful public methods that SamsungIAP provides, to use them, simply call SamsungIAP.Instance().methodName().
Show All   
public void Purchase(string sku, string payload = null)
/**
 * Initiate a purchase request to the plugin.
 *
 * @param sku
 *           string - IAP item identifier, the Product ID you defined at SamsungApps's publisher site.
 *
 * @param payload (optional)
 *          string -  a developer payload that is associated with a given purchase,
 *          if null, no payload is sent. Developer Payload is a developer-specified
 *          string that contains supplemental information about a purchase.
 *          This parameter is optional.
 */
public void Purchase(string sku, string payload = null)
public void GetItemInfo(string sku)
/**
 * Get the specified item information.
 * 
 * The item information is retrieved at app launch and it is cached in plugin for better performance.
 * You should always call this function in SamsungIAPListener::OnItemDataReady() to make sure the data
 * has been ready for you to query.
 * 
 * @param sku
 * 			string - IAP item identifier, the sku you defined at SamsungApps's publisher site.
 * 
 * @return 
 * 			SamsungIAPItem - A Samsung IAP Item which contains { title, description, price, type }
 */
public void GetItemInfo(string sku)
public void GetItemPrice(string sku)
/**
 * Get the price of specified item.
 * 
 * The item information is retrieved at app launch and it is cached in plugin for better performance.
 * You should always call this function in SamsungIAPListener::OnItemDataReady() to make sure the data
 * has been ready for you to query.
 * 
 * @param sku
 * 			string - IAP item identifier, the sku you defined at SamsungApps's publisher site.
 * 
 * @return 
 * 			float - The price of the item
 */
public void GetItemPrice(string sku)
public SamsungIAPPurchaseInfo GetPurchaseInfo(string sku)
/**
 * Get the purchase information if there is an owned item (An item owned and not yet consumed).
 * 
 * Return null if there isn't an owned item with the sku specified.
 * 
 * @param sku
 *       string - IAP item identifier, the sku you defined at SamsungApps's publisher site.
 * 
 * @return
 *       SamsungIAPPurchaseInfo - A Samsung IAP purchae info obj which contains 
 *                 {sku, orderId, purchaseToken, purchaseState, purchaseTime, developerPayload}
 * 
 */
public SamsungIAPPurchaseInfo GetPurchaseInfo(string sku)

[6] Test your In-App Billing functionality. Before you can test, you should set up the corresponding Product IDs at SamsungApps publisher site. Also it would be helpful for you to address issues if you take a look at the logcat output to find the debug / error / warning messages.

IMPORTANT: Don't forget to turn off test mode before you build your release binary for appstore submission.

[EOF] If you encounter any problems while integrating the plugin, please do not hesitate to shoot us an email at support@neatplug.com, we will be helping you as soon as possible.Thanks for choosing NeatPlug solutions!