Release Notes: (1.5.0)
  • Fixed an issue that causes item information cannot be retrieved if the item is a subscription.

Integration Guide - Google In-App Billing (V3) Plugin

Platforms: Android only
Plugin version: 1.5.0
IAB API version: 3

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

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

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

To integrate Google IAB V3, 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 GoogleIABAgent Prefab and GoogleIABListener Prefab in Assets/Plugins/NeatPlug/IAP/GoogleIAB/Prefabs/, open the first scene of your game, drag & drop those two prefabs into the scene. Select the GoogleIABAgent gameObject in Hierarchy Window and fill in the public "Public Key" field with the base64 encoded public key you copied from Google Play publisher account. (Home -> Edit Profile -> Licensing & In-app Billing -> Copy your public key); Fill in Consumable Skus, Nonconsumable Skus and Subscription Skus, these properties are intended for registering your skus that need to be queried automatically when App starts. If you want the receipt data to be posted to your server once a successful purchase is made, supply "Server Receive Receipt URL" property. [Learn more]

NOTE: IAB V3 provides the function of querying sku details including item price, title etc, so it is now possible for you to display dynamic prices in your app. However all items have to be "managed" in V3, that says every single item can be "consumed" and you have to decide when to consume them. To make the usage consistent to other App stores, a feature is provided in our plugin to still make the difference of Consumable and Nonconsumable in your app. For more information, please read the details in [5].

[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 GoogleIABListener gameObject, locate the GoogleIABListener.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(GoogleIABReceipt receipt) { ... }
/**
 * Fired when the purchase successfully completed.
 *
 * This is where you should deliver the item to the user.
 *	 
 * @param receipt
 *           GoogleIABReceipt - An object which contains the purchase information. 
 *                             { sku, purchaseTime, orderId, purchaseToken, 
 *                               purchaseState, packageName, developerPayload }
 */
void OnPurchaseCompleted(GoogleIABReceipt 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 Google Play'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 Google Play's publisher site.
 */
void OnPurchaseCancelled(string itemId)
{
    /// Your code here...   
}
void OnPurchaseCancelledByGoogle(string sku) { ... }
/**
 * Fired when the purchase cancelled by Google.
 *
 * The cancellation is primarily caused by user's credit card validation failure.
 *
 * @param sku
 *           string - IAP item identifier, the Product ID you defined at Google Play's publisher site.
 */
void OnPurchaseCancelledByGoogle(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 Google Play 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 Google android developer site.
 * 
 * @param supported
 *             bool - true for supported, false for unsupported.
 * 
 * @param response
 *             string - The response code returned from Google IAB API.
 * 
 * The response codes are listed here:
 * ##################################################################################################	
 * BILLING_RESPONSE_RESULT_OK                   0   Success
 * 
 * BILLING_RESPONSE_RESULT_USER_CANCELED        1   User pressed back or canceled a dialog
 * 
 * BILLING_RESPONSE_RESULT_BILLING_UNAVAILABLE  3   Billing API version is not supported for 
 *                                                  the type requested
 * 
 * BILLING_RESPONSE_RESULT_ITEM_UNAVAILABLE     4   Requested product is not available for purchase
 * 
 * BILLING_RESPONSE_RESULT_DEVELOPER_ERROR      5   Invalid arguments provided to the API. This error 
 *                                                  can also indicate that the application was not 
 *                                                  correctly signed or properly set up for In-app 
 *                                                  Billing in Google Play, or does not have the 
 *                                                  necessary permissions in its manifest
 * 
 * BILLING_RESPONSE_RESULT_ERROR                6   Fatal error during the API action
 * 
 * BILLING_RESPONSE_RESULT_ITEM_ALREADY_OWNED   7   Failure to purchase since item is already owned
 * 
 * BILLING_RESPONSE_RESULT_ITEM_NOT_OWNED       8   Failure to consume since item is not owned
 * ###################################################################################################
 */
void OnBillingSupported(bool supported, string response)
{
    /// Your code here...   
}
void OnSubscriptionSupported(bool supported, string response) { ... }
/**
 * Fired when the check for subcription support is done. 
 *
 * @param supported
 *             bool - true for supported, false for unsupported.
 * 
 * @param response
 *             string - The response code returned from Google IAB 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 Google Play'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 Google Play's publisher site.	
 */
void OnItemAlreadyOwned(string sku)
{
    /// Your code here...
}
void OnItemConsumed(string sku) { ... }
/**
 * Fired when the purchased item successfully consumed.
 * 
 * @param sku
 *           string - IAP item identifier, the sku you defined at Google Play's publisher site.	
 * 	
 */
void OnItemConsumed(string sku)
{
    /// Your code here...
}
void OnItemFailedToConsume(string sku) { ... }
/**
 * Fired when the purchased item failed to be consumed.
 * 
 * @param sku
 *           string - IAP item identifier, the sku you defined at Google Play's publisher site.	
 * 	 
 */
void OnItemFailedToConsume(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 GoogleIAB.Instance().Purchase(string sku) function in your code to initiate a purchase request.

  Initiate a purchase request:

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

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

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

  There are useful public methods that GoogleIAB provides, to use them, simply call GoogleIAB.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 Google Play'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 Purchase(string sku, PurchaseType type, string payload = null)
/**
 * Initiate a purchase request to the plugin.
 *
 * @param sku
 *           string - IAP item identifier, the Product ID you defined at Google Play's publisher site.
 *
 * @param type
 *           PurchaseType - The type of purchase. 
 *                          {Consumable_AutoConsume, Consumable_ManuallyConsume, NonConsumable, Subscription}
 *                          This parameter is used to force the item purchase type to be the specified value
 *                          regardless of settings in GoogleIABAgent properties: Consumable Product Skus and
 *                          Nonconsumable Product Skus. 
 *
 *
 * @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, PurchaseType type, 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 GoogleIABListener::OnItemDataReady() to make sure the data
 * has been ready for you to query.
 * 
 * @param sku
 * 			string - IAP item identifier, the sku you defined at Google Play's publisher site.
 * 
 * @return 
 * 			GoogleIABItem - A Google IAB 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 GoogleIABListener::OnItemDataReady() to make sure the data
 * has been ready for you to query.
 * 
 * @param sku
 * 			string - IAP item identifier, the sku you defined at Google Play's publisher site.
 * 
 * @return 
 * 			float - The price of the item
 */
public void GetItemPrice(string sku)
public void Consume(string sku)
/**
 * Consume a product.
 * 
 * This provides flexibility for consuming a Consumable_ManuallyConsume product.
 * 
 * @param sku
 *           string - IAP item identifier, the Product ID you defined at Google Play's publisher site.
 * 			 
 */
public void Consume(string sku)
public GoogleIABPurchaseInfo 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 Google Play's publisher site.
 * 
 * @return
 *       GoogleIABPurchaseInfo - A Google IAB purchae info obj which contains 
 *                 {sku, orderId, purchaseToken, purchaseState, purchaseTime, developerPayload}
 * 
 */
public GoogleIABPurchaseInfo GetPurchaseInfo(string sku)

[6] Test your In-App Billing functionality. Before you can test, you should set up the corresponding Product IDs at Google Play publisher site. (Home -> Your App -> In-app Products and Subscriptions -> Create New In-app Product) 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.

[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!