Currency (IAP)
Integration Guide
Every project may have multiple custom currencies. For example "diamonds" and/or "cash". Aside from these typical game currencies, projects wishing to sell NFTs must integrate a specific currency. The internal name for this currency is "rgn-coin". When the "rgn-coin" is presented in the UI it can have any currency name, for example, "gems".
The "rgn-coin" may only be sold using in-app purchases. For more information on why this approach is used, please refer to the Currency GDG.
Other typical currencies can be added and used in an expected manner - as rewards to the user's account, or sold for in-app purchases.
To sell "rgn-coin" or other custom currency via in-app purchases you need to follow the below process:
- 1.Get the products list from AppStore (iOS) or PlayMarket (Android)
- 2.Get the registered products list from RGN SDK:
- 1.
RGN.Modules.Currency.CurrencyModule.GetInAppPurchaseCurrencyDataAsync
for custom coin currency packs - 2.
RGN.Modules.Currency.CurrencyModule.GetRGNCoinEconomyAsync
for "rgn-coin" packs. Important: you need to sell the "rgn-coin" for exact same tiers as it is specified in the response from this method.
- 3.When the user tries to purchase the coins start the in-app purchase process by using one of the available Unity plugins.
- 4.When the user purchases the coins and the callback for a successful purchase is triggered, you need to verify the receipt locally.
- 5.After successful receipt verification, you need to trigger the RGNCurrency API:
- 1.For custom currencies call the
RGN.Modules.Currency.CurrencyModule.PurchaseCurrencyProductAsync
method. - 2.For "rgn-coin" purchases call the
RGN.Modules.Currency.CurrencyModule.PurchaseRGNCoinAsync
mehtod.
- 6.In case the operation is successfully updated coin currencies balance will be returned in the response.
string id; //IAP identifier
string currencyName; //reward currency name i.e. coin
float price; //price of IAP
int quantity; //reward currency ammount
string type;
string promotionalSticker;
The
GetInAppPurchaseCurrencyDataAsync()
needs to be called only once. You can cache the value CurrencyProductsData
for later use in the PurchaseCurrencyProductAsync
method:using RGN.Modules.Currency;
namespace SomeNamespace
{
internal sealed class RetrieveCurrencyData
{
internal CurrencyProductsData ProductsData { get; private set; }
public async void RetrieveCurrencyDataOnceAsync()
{
ProductsData =
await CurrencyModule.I.GetInAppPurchaseCurrencyDataAsync();
}
}
}
The
CurrencyProductsData
contains two fields: products
and offers
The
products
is a list of RGNStoreProduct
classes:public class CurrencyProduct
{
public string id;
public string currencyName;
public float price;
public int quantity;
public string type;
public string promotionalSticker;
}
The
offers
is a list of CurrencyOffer
classes:public class CurrencyOffer
{
public string productId;
public string offeredProductId;
public double remainingTime;
public float offeringPrice;
public string promotionalMessage;
}
- 1.Call Unity IAP package purchase API and let the user buy the IAP (it is handled by native UI)
- 2.Validate the purchase receipt locally
- 3.On
OnSuccessfullPurchase
event call RGN'sPurchaseCurrencyProductAsync(productId)
:
using System.Collections.Generic;
using RGN.Modules.Currency;
namespace SomeNamespace
{
internal sealed class PurchaseCustomCoin
{
// This is a callback method for IAP plugin after successful
// receipt validation:
public async void HandleSuccessfulPurchaseAsync(string productId)
{
List<Currency> userCurrencyData =
await CurrencyModule.I.PurchaseCurrencyProductAsync(productId);
}
}
}
Here the
productId
is the id that you received in the CurrencyProduct
data.Purchasing
rgn-coin
works a bit differently, it has its own API called PurchaseRGNCoinAsync(string iapUUID)
using RGN.Modules.Currency;
namespace SomeNamespace
{
internal sealed class PurchaseRGNCoin
{
public async void HandleSuccessfulPurchaseAsync()
{
// You can also retrieve the ecomony data
// once the app starts and cache it
RGNCoinEconomy rgnCoinEconomy =
await CurrencyModule.I.GetRGNCoinEconomyAsync();
// TODO: select the right product from the list:
// The list contains multiple 'rgn-coin' product packs
// Every pack has different amount of 'rgn-coin's and
// is sold using different price tier from the store
string iapUUID = rgnCoinEconomy.products[0].uid;
// TODO: before you call this method, you need
// to go to the in-app purchase process
//
// After the in-app purchase successfully finishes
// you need to validate the receipt locally and then
// you can call following method:
System.Collections.Generic.List<Currency> purchaseResponse =
await CurrencyModule.I.PurchaseRGNCoinAsync(iapUUID);
}
}
}
You can get
isoCurrenyCode
and localizedPrice
from Unity IAP product's metadata. More details for Browsing Product Metadata.For now, you'll have to set
isoCurrenyCode & localizedPrice in USD and 0.99, 1.99 or 2.99
Last modified 13d ago