Usage
Billing Services allows to monetize your app on iOS and Android platforms
Plugin refers Consumable, Non-Consumable and Subscription purchasable items as Billing Products. This makes the api much easier to understand.
Each Billing product can have an Id, Name, Description, SubscriptionInfo(Not null, if its a subscription), Payouts etc.
Once after you setup and add billing products, you can purchase a product by referring them in code.
Before using any of the billing services features, first make sure if it's available on the running platform with IsAvailable method. This returns true if you are allowed to make purchases on the current platform.
BillingServices.IsAvailable()Events
Once you see that billing services are available, you should register for the billing services events.
private void OnEnable()
{
// register for events
BillingServices.OnInitializeStoreComplete += OnInitializeStoreComplete;
BillingServices.OnTransactionStateChange += OnTransactionStateChange;
BillingServices.OnRestorePurchasesComplete += OnRestorePurchasesComplete;
}
private void OnDisable()
{
// unregister from events
BillingServices.OnInitializeStoreComplete -= OnInitializeStoreComplete;
BillingServices.OnTransactionStateChange -= OnTransactionStateChange;
BillingServices.OnRestorePurchasesComplete -= OnRestorePurchasesComplete;
}Event Name
Description
OnInitializeStoreComplete
Event triggered when products are fetched from the store
OnTransactionStateChange
Event triggered when there is a change in state for an ongoing transaction
OnRestorePurchasesComplete
Event triggered once restored products are available
Events are triggered based on an action initiated by the plugin's api calls, asynchronously. For ex: Calling InitializeStore triggers OnInitializeStoreComplete with the product details if it's successful.
Billing Products Presentation
Billing Products details can be changed anytime even after the app is published. So the details need to be fetched from stores before presenting them to the user.
Get Billing Product Details
Note that the order of billing products returned in the event callback can be different from the order you sent. This is intentional. As the products can be removed or added once after your app release in native dashboards, we don't guarantee the order or sort the order in the event callbacks. You need to refer a product with it's Id(GetBillingProductWithId) rather than the array index.
After event registration, you need to call InitializeStore to fetch the complete details of the in-app purchase billing products.
This call fetches the details(you set in iTunes connect and google play) and triggers BillingServices.OnInitializeStoreComplete callback with the details.
BillingServices.InitializeStore();// Register for the BillingServices.OnInitializeStoreComplete event
// ...
private void OnInitializeStoreComplete(BillingServicesInitializeStoreResult result, Error error)
{
if (error == null)
{
// update UI
// show console messages
var products = result.Products;
Debug.Log("Store initialized successfully.");
Debug.Log("Total products fetched: " + products.Length);
Debug.Log("Below are the available products:");
for (int iter = 0; iter < products.Length; iter++)
{
var product = products[iter];
Debug.Log(string.Format("[{0}]: {1}", iter, product));
}
}
else
{
Debug.Log("Store initialization failed with error. Error: " + error);
}
var invalidIds = result.InvalidProductIds;
Debug.Log("Total invalid products: " + invalidIds.Length);
if (invalidIds.Length > 0)
{
Debug.Log("Here are the invalid product ids:");
for (int iter = 0; iter < invalidIds.Length; iter++)
{
Debug.Log(string.Format("[{0}]: {1}", iter, invalidIds[iter]));
}
}
}Product Offers
After fetching the billing products from store with InitializeStore call, Offers property of IBillingProduct contains an array of offers that can be eligible for the corresponding billing product.
Each offer(BillingProductOffer) contains the following details
Id - Offer Id that needs to be usef for redeeming an offer
Category - Category in which this offer falls into. Can be Introductory or Promotional
Pricing Phases - Phases of how the pricing is calculated during the promotion period. On some platforms (ex: Android) there can be more than one pricing phase.
Each Pricing Phase(BillingProductOfferPricingPhase) gives info about the
Payment Mode - Free Trial or PayAsYouGo or PayUpfront
Price - Price applied during the period
Period - Period for which pricing is applied
Repeat Count - How many times this pricing phase is repeated (can be > 1 for PayAsYouGo and 1 for rest)
Handling Purchases
Making a purchase
Once you have the details about pricing and description of a product, you can check if your device is ready to make payments. CanMakePayments returns true when its fine to make purchases. If purchases are not currently allowed, it returns false.
BillingServices.CanMakePayments()Consumable products can be purchased multiple time where as Non-Consumable or Subscription products can be bought only once lifetime or for a period of time. To unlock the content purchased with non-consumable or subscription product you can check if its already bought or not with IsProductPurchased
//product => "Product you got from OnInitializeStoreComplete event (result.Products)"
BillingServices.IsProductPurchased(product);If the product is not purchased or if its a consumable product you can proceed with the purchase by calling BuyProduct. BuyProduct takes the IBillingProduct instance along with BuyProductOptions(optional).
BuyProductOptions is for passing additional info for the purchase. It has
Quantity
Tag
Offer Redeem Details
Quantity : This how much quantity you want to buy. Let's say you want to purchase 10 ammo packs of same iap, you pass 10 as quantity. However, while iOS supports this, android ignores it and only user need to select in their purchase popup ui.
Tag : This is a unique id you can give to the purchase which can be retrieved in the purchased Transaction (IBillingTransaction). This is optional and usually used by native platforms to fightback fraud.
Offer Redeem details : Details required to redeem an offer. Please check Redeem an available offer
BuyProductOptions instance can be created as below
BuyProductOptions options = new BuyProductOptions.Builder().SetQuantity(1)
.SetTag("uuid-identifier")
//.SetOfferRedeemDetails(offerDetails)
.Build();//product => "Product you got from OnInitializeStoreComplete event (result.Products)"
BillingServices.BuyProduct(product, options);
//BillingServices.BuyProduct(product, options:null); //If you want to purchase 1 quantity which is default.BuyProduct shows native purchase dialogs to proceed with the purchase and fires BillingServices.OnTransactionStateChange event callback during the purchase process.
private void OnTransactionStateChange(BillingServicesTransactionStateChangeResult result)
{
var transactions = result.Transactions;
for (int iter = 0; iter < transactions.Length; iter++)
{
var transaction = transactions[iter];
switch (transaction.TransactionState)
{
case BillingTransactionState.Purchased:
Debug.Log(string.Format("Buy product with id:{0} finished successfully.", transaction.Product.Id));
/*
if(transaction.Product.Id.Equals("REMOVE_ADS")) //Note we used Equals instead of "==" which is always safe!
{
Debug.Log("REMOVE_ADS product purchased. Proceed with removing ads");
}
*/
break;
case BillingTransactionState.Failed:
Debug.Log(string.Format("Buy product with id:{0} failed with error. Error: {1}", transaction.Product.Id, transaction.Error));
break;
}
}
}Once you BillingServices.OnTransactionStateChange event fired, you will get a list of transactions that are currently getting processed. You can check if the transaction state is BillingTransactionState.Purchased or BillingTransactionState.Failed.
If its Purchased state, you can proceed with unlocking the content to the user. If Failed, It could be because the user cancelled the payment or due a failed transaction. You can get more details from Error property of a transaction.
Redeem an available offer
Offers that can be applied to a product(IBillingProduct) are fetched after a call to InitializeStore.
Once you have the offers, you can select an offer based on the user profile and redeem it when purchasing.
To pass which offer to apply for redemption, you can set it in options(BuyProductOptions) you pass to BuyProduct call.
Create Offer redeem details based on the platform
private BillingProductOfferRedeemDetails GetOfferRedeemDetails(string offerId)
{
if(string.IsNullOrEmpty(offerId))
{
return null;
}
BillingProductOfferRedeemDetails.Builder builder = new BillingProductOfferRedeemDetails.Builder();
if (Application.platform == RuntimePlatform.Android)
{
builder.SetAndroidPlatformProperties(offerId);
}
else if (Application.platform == RuntimePlatform.IPhonePlayer)
{
builder.SetIosPlatformProperties(offerId, keyId: null, nonce: null, signature: null, timestamp: 0);//Fill in the details here by injecting the values
}
return builder.Build();
}Set the redeem details when building BuyProductOptions
IBillingProduct billingProduct;
//...
BillingProductOfferRedeemDetails offerDetails = GetOfferRedeemDetails("offer-id");
//...
BuyProductOptions options = new BuyProductOptions.Builder().SetQuantity(1)
.SetOfferRedeemDetails(offerDetails)
.Build();
//...
BillingServices.BuyProduct(billingProduct, options); Get previous purchases (Restore Purchases)
There are scenarios where
The user uninstalls your game and re-installs later
The user installs the game on multiple devices
As Non-Consumable or Subscription purchases need to be maintained across devices and installs, you need a way to fetch the old purchases of the user so that you can unlock the content for the user.
This can be achieved through RestorePurchases call.
BillingServices.RestorePurchases();Calling RestorePurchases fetches the old purchase transactions linked to the user account and fires BillingServices.OnRestorePurchasesComplete event with all purchase details.
private void OnRestorePurchasesComplete(BillingServicesRestorePurchasesResult result, Error error)
{
if (error == null)
{
var transactions = result.Transactions;
Debug.Log("Request to restore purchases finished successfully.");
Debug.Log("Total restored products: " + transactions.Length);
for (int iter = 0; iter < transactions.Length; iter++)
{
var transaction = transactions[iter];
Debug.Log(string.Format("[{0}]: {1}", iter, transaction.Product.Id));
}
}
else
{
Debug.Log("Request to restore purchases failed with error. Error: " + error);
}
}Once you get the old purchase transactions, you can unlock the content for the user.
On iOS, it's required to have an explicit button to restore purchases as per Apple guidelines.
It's always good to call Restore Purchases once you are done with InitializeStore call as the user will be available with unlocked content if he/she has purchased any earlier.
Force refresh restore purchases
On some native platforms, restore purchases are cached/synced internally. So calling Restore Purchases will return that cached data.
But if you have a button to restore purchases (a requirement on iOS) and user clicks it multiple times, chances are that he/she finds some data missing. So, to make sure the data is the exact copy of his purchases, plugin offers option to force refresh the details.
BillingServices.RestorePurchases(forceRefresh: true);Subscriptions
Subscriptions are a type of Billing Products which are bounded to time. The time period unit can be either week or month or year.
Fetch Subscription Info (for presentation)
Once you call BillingServices.InitializeStore, if you have subscription billing products, the result in the event callback contains IBillingProduct's with SubscriptionInfo property value.
SubscriptionInfo gives details about
Title - Title of this subscription (if available)
Period - Period for which this subscription is valid
Subscription Status Details
Once after purchasing a subscription with BuyProduct, you receive a transaction(IBillingTransaction) which contains SubscriptionStatus.
Status details offers option to fetch RenewalInfo to know if the product is auto renewed or not.
Advanced
Manually handling transactions (Auto Finish Transactions disabled)
There are scenarios where you want to validate a purchase receipt on your server and unlock the content to the user. If you have such requirement, you need to disable "Auto Finish Transactions" in Billing Services settings and close the transactions manually.
GetTransactions gives the list of all pending transactions and you need to
Process each transaction returned from GetTransactions
Pass the transaction receipt details to your backend server
Set ReceiptVerificationState of the transaction to BillingReceiptVerificationState.Success or BillingReceiptVerificationState.Failed
Call FinishTransactions with the updated transaction verification details
If you have "Auto Finish Transactions" enabled in Essential Kit Settings -> Billing Services, you don't need to call GetTransactions as we handle this automatically.
// Fetch all pending transactions
var transactions = BillingServices.GetTransactions();
// Process each transaction
foreach (var each in transactions)
{
// Verify the receipt with your server - This is an async call usually
// Set the ReceiptVerificationState to Success or Failed
}
// Call Finish Transactions to clear the pending transaction queue
BillingServices.FinishTransactions(transactions);External Receipt Verification
If you would like to validate a receipt externally and allocate the entitlements to the user, you need to follow the below workflow.
Disable Auto Finish Transactions in Billing Settings (Essential Kit Settings)
Once you get a change transaction event, pass the required details to your server
On receiving success or failure response from your server, set ReceiptVerificationState of IBillingTransaction to BillingReceiptVerificationState.Success or BillingReceiptVerificationState.Failed
Call FinishTransactions method with the updated transaction to manually close the transaction
The details that you may require for your external server can be as follows
iOS
JwsRepresentation - Get from IBillingTransaction.Receipt
Android
Purchase Token - Get from IBillingTransaction.Receipt
Signature - Get from IBillingTransaction.RawData (contains signature key and value)
Product Identifier - Get from IBillingTransaction.Product.PlatformId
Purchase Data - Get from IBillingTransaction.RawData (contains transaction key and value)
Platform Specific (Advanced)
Android
Have a look at the below table for the BillingTransaction to Google Play purchase response mapping.
Property Name of BillingTransaction
Mapped Property on Native Platform
Id
INAPP_PURCHASE_DATA.orderId
Receipt
INAPP_PURCHASE_DATA.purchaseToken
Product.Id
INAPP_PURCHASE_DATA.productId
RawData["transaction"] (covert RawData to IDictionary)
INAPP_PURCHASE_DATA
RawData["signature"] (covert RawData to IDictionary)
INAPP_DATA_SIGNATURE
Last updated
Was this helpful?