Release Notes: (1.3.0)
  • iOS arm64 architecture support added.
  • Fix an issue of "About AppleIAP" menu item is not working.

Integration Guide - Apple In-App Purchase (StoreKit) Plugin

Platforms: iOS only
Plugin version: 1.3.0
iOS SDK version: since 4.0

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

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

[2] Click on the menu item of Unity top menu bar: NeatPlug -> AppleIAP -> Patch iOS Configuration. This is for automatically adding iOS SDK frameworks, libraries or patching the Info.plist file (if needed) as long as the Xcode project is generated by Unity.

[3] Find AppleIAPAgent Prefab and AppleIAPListener Prefab in Assets/Plugins/NeatPlug/IAP/AppleIAP/Prefabs/, open the first scene of your game, drag & drop those two prefabs into the scene.

[4] Okay, the integration is almost done here. Now set up your IAP by filling in a few properties of the AppleIAPAgent gameObject which you just dropped in the Hierarchy window. To do this, simply select that gameObject, and look at its properties in the Inspector window, you need to fill in:

· Product Ids - A set of product IDs you want the plugin to automatically retrieve information (title, description, price, ...) for you.

· Show Spinner - Check this if you want a spinner to show up while the purchase is being processed.

· Verify Receipt From Device - Check this if you want the plugin to automatically perform a receipt verification (from device) for you.

· Server Receive Receipt URL - A URL on your server for receiving purchase receipt for further verification and process.

NOTE: It is recommended that you set Server Receive Receipt URL if you want to perform a server-to-server receipt verification (which is securer than verifying from device), or you need additional server-side process for the purchase. e.g. creating subscirption entries, preparing downloadable content, etc... To ensure the receipt is derived from Apple and never tampered with by any other people, you should always verify the posted receipt data with Apple, want to learn more about how to validate a receipt? Click here. For your convenience, we provide you with an example program written in PHP that you can simply download and use: verify-receipt.php.

[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 AppleIAPListener gameObject, locate the AppleIAPListener.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(AppleIAPReceipt receipt) { ... }
/**
 * Fired when the purchase successfully completed.	
 * 
 * This is where you should deliver the item to the user.
 * 
 * @param receipt
 *           AppleIAPReceipt - An object which contains the purchase information. 
 *                              { productId, transactionDate, transactionId, 
 *                                transactionState, quantity, receiptData }
 */
void OnPurchaseCompleted(AppleIAPReceipt receipt)
{
    /// Your code here...   
}
void OnPurchaseFailed(string productId, string err) { ... }
/**
 * Fired when the purchase failed.
 *
 * @param productId
 *           string - IAP item identifier, the Product ID you defined at iTunesConnect.
 *
 * @param err
 *           string - The reason for failure.
 */
void OnPurchaseFailed(string productId, string err)
{
    /// Your code here...
}
void OnPurchaseCancelled(string productId) { ... }
/**
 * Fired when the purchase cancelled by the user.
 *
 * @param productId
 *           string - IAP item identifier, the Product ID you defined at iTunesConnect.
 */
void OnPurchaseCancelled(string productId)
{
    /// Your code here...   
}
void OnIAPSupported(bool supported) { ... }
/**
 * Fired when the check for the In-App Purchase support is done.	
 */
void OnIAPSupported(bool supported)
{
    /// 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(AppleIAPReceipt receipt) { ... }
/**
 * 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 receipt
 *           AppleIAPReceipt - An object which contains the purchase information. 
 *                              { productId, transactionDate, transactionId, 
 *                                transactionState, quantity, receiptData }	
 */	
void OnOwnedItemReported(AppleIAPReceipt receipt)
{
    /// Your code here...
}
void OnCompletedTransactionsRestored() { ... }
/**
 * Fired when the completed transactions are successfully restored.
 * 
 * NOTE: This event gets triggered only if you call 
 * AppleIAP.Instance().RestoreCompletedTransactions().
 * This event is for informational purpose only, you may want to
 * inform the user of the restore completion here.
 * 
 * If there are any purchased Non-Consumable products, 
 * then AppleIAPListener::OnOwnedItemReported() will be triggered, 
 * you can redeliver the products to the user in that event handler.	
 */
void OnCompletedTransactionsRestored()
{
    /// Your code here...
}
void OnCompletedTransactionsFailedToRestore(string err) { ... }
/**
 * Fired when the completed transactions failed to restore.	
 * 
 * @param err
 *           string - The error message returned from Apple.
 */	
void OnCompletedTransactionsFailedToRestore(string err)
{
    /// Your code here...   
}
void OnReceiptPosted(string productId, string response) { ... }
/**
 * Fired when the receipt data is successfully posted to your server.
 * 
 * Developers who need additional server-side process for the purchase would need this
 * feature, if you don't have any server-side processes, no need to read this.
 * 
 * Posting a returned receipt to your own server is done automatically by the plugin,
 * all you have to do is to simply fill in the "ServerReceiveReceiptURL" property of
 * the AppleIAPAgent gameObject in your first scene. The receipt posting action will
 * happen every time a purchase is successfully completed.
 * 
 * The posting receipt mechanism is for you to easily upload the returned receipt data
 * to your own server for further verification, it is for security purpose.
 * 
 * @param productId
 *           string - IAP item identifier, the productId you defined at iTunesConnect.	
 * 
 * @param response
 *           string - The response from your server.
 * 	
 */	
void OnReceiptPosted(string productId, string response)
{
    /// Your code here...   
}
void OnReceiptFailedToPost(string productId, string response) { ... }
/**
 * Fired when the receipt data failed to be posted.
 * 
 * Developers who need additional server-side process for the purchase would need this
 * feature, if you don't have any server-side processes, no need to read this.
 * 
 * Posting a returned receipt to your own server is done automatically by the plugin,
 * all you have to do is to simply fill in the "ServerReceiveReceiptURL" property of
 * the AppleIAPAgent gameObject in your first scene. The receipt posting action will
 * happen every time a purchase is successfully completed.
 * 
 * The posting receipt mechanism is for you to easily upload the returned receipt data
 * to your own server for further verification, it is for security purpose.
 * 
 * @param productId
 *           string - IAP item identifier, the productId you defined at iTunesConnect.	
 * 
 * @param response
 *           string - The response from your server.
 * 	
 */	
void OnReceiptFailedToPost(string productId, string response)
{
    /// Your code here...   
}

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

Initiate a purchase request:

· AppleIAP.Instance().Purchase(string productId);

NOTE: If you don't supply Product Ids in the properties of AppleIAPAgent gameObject, you need to call AppleIAP.Instance().Initialize(...) to provide that information to plugin.

There are useful public methods that AppleIAP provides, to use them, simply call AppleIAP.Instance().methodName().
Show All   
public void Purchase(string productId, int quantity = 1, Dictionary<string, string> extras = null)
/**
 * Initiate an in-app purchase request to the plugin.
 * 
 * @param productId
 *           string - IAP item identifier, the Product ID you defined at itunesConnect.
 * 
 * @param quantity
 *           int - The quantity of prodcuts to buy.
 * 
 * @param extras
 *           Dictionary - The Extra parameters you want to post the receipt along with.
 *                        (This is only needed if you set "ServerReceiveReceiptURL"
 *                          property of AppleIAPAgent gameObject, that says you want
 *                          the plugin to automatically post the receipt data to your 
 *                          server for further verification)
 * 	
 */
public void Purchase(string productId, int quantity = 1, Dictionary<string, string> extras = null)
public AppleIAPItem GetItemInfo(string productId)
/**
 * 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 AppleIAPListener::OnItemDataReady() to make sure the data
 * has been ready for you to query.
 * 
 * @param productId
 *              string - IAP item identifier, the productId you defined at itunesConnect.
 * 
 * @return
 *              AppleIAPItem - An Apple IAP Item which contains { title, description, price, currencySymbol }
 */
public AppleIAPItem GetItemInfo(string productId)
public float GetItemPrice(string productId)
/**
 * 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 AppleIAPListener::OnItemDataReady() to make sure the data
 * has been ready for you to query.
 * 
 * @param productId
 * 			string - IAP item identifier, the productId you defined at iTunesConnect.
 * 
 * @return 
 * 			float - The price of the item.
 */	
public float GetItemPrice(string productId)
public void RestoreCompletedTransactions()
/**
 * Restore completed transactions.
 * 
 * This is useful when your locally saved purchase records are somehow wiped out on the device,
 * in this case you may want to redeliver the purchased Non-consumable products if any.
 * 
 * NOTE: Since Apple requires the user to authenticate before restoring completed transactions,
 * this task cannot be done automatically when App starts. You would need to add a button something like
 * "Restore Completed Transactions", to provide the user with a way to restore his / her original 
 * purchases.
 * 
 */
public void RestoreCompletedTransactions()

[6] Test your In-App Purchase functionality. Before you can test, you should set up the corresponding Product IDs at iTunesConnect, and at least one Test Account should be created. Test in the sandobx environmenet and make sure all IAP functions work fine. Also it would be helpful for you to address issues if you take a look at the xcode debug console 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!