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.
We suggest utilizing Unity's IAP Package to handle the in-app purchase process on Android and iOS.
To sell "rgn-coin" or other custom currency via in-app purchases you need to follow the below process:
  1. 1.
    Get the products list from AppStore (iOS) or PlayMarket (Android)
  2. 2.
    Get the registered products list from RGN SDK:
    1. 1.
      RGN.Modules.Currency.CurrencyModule.GetInAppPurchaseCurrencyDataAsync for custom coin currency packs
    2. 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. 3.
    When the user tries to purchase the coins start the in-app purchase process by using one of the available Unity plugins.
  4. 4.
    When the user purchases the coins and the callback for a successful purchase is triggered, you need to verify the receipt locally.
  5. 5.
    After successful receipt verification, you need to trigger the RGNCurrency API:
    1. 1.
      For custom currencies call the RGN.Modules.Currency.CurrencyModule.PurchaseCurrencyProductAsync method.
    2. 2.
      For "rgn-coin" purchases call the RGN.Modules.Currency.CurrencyModule.PurchaseRGNCoinAsync mehtod.
  6. 6.
    In case the operation is successfully updated coin currencies balance will be returned in the response.

Add in-app products information using the RGN Dev Dashboard

In the RGN Dev Dashboard, you can add your in-app purchases with the following details:
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;

API call:

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;
}

Buy IAP custom coin currency product

  1. 1.
    Call Unity IAP package purchase API and let the user buy the IAP (it is handled by native UI)
  2. 2.
    Validate the purchase receipt locally
  3. 3.
    On OnSuccessfullPurchase event call RGN's PurchaseCurrencyProductAsync(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.

Purchase rgn-coin IAP

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