[iOS + Android] Virtual Currency Support (#502)

Author: fire-at-will

README.md

@@ -54,6 +54,9 @@ This plugin is based on [CapGo's Capacitor plugin](https://www.npmjs.com/package
 <docgen-index>
 
 * [`configure(...)`](#configure)
+* [`getVirtualCurrencies()`](#getvirtualcurrencies)
+* [`invalidateVirtualCurrenciesCache()`](#invalidatevirtualcurrenciescache)
+* [`getCachedVirtualCurrencies()`](#getcachedvirtualcurrencies)
 * [`parseAsWebPurchaseRedemption(...)`](#parseaswebpurchaseredemption)
 * [`redeemWebPurchase(...)`](#redeemwebpurchase)
 * [`setMockWebResults(...)`](#setmockwebresults)
@@ -144,6 +147,49 @@ Sets up Purchases with your API key and an app user id.
 --------------------
 
 
+### getVirtualCurrencies()
+
+```typescript
+getVirtualCurrencies() => Promise<{ virtualCurrencies: PurchasesVirtualCurrencies; }>
+```
+
+Fetches the virtual currencies for the current subscriber.
+
+**Returns:** <code>Promise&lt;{ virtualCurrencies: <a href="#purchasesvirtualcurrencies">PurchasesVirtualCurrencies</a>; }&gt;</code>
+
+--------------------
+
+
+### invalidateVirtualCurrenciesCache()
+
+```typescript
+invalidateVirtualCurrenciesCache() => Promise<void>
+```
+
+Invalidates the cache for virtual currencies.
+
+This is useful for cases where a virtual currency's balance might have been updated
+outside of the app, like if you decreased a user's balance from the user spending a virtual currency,
+or if you increased the balance from your backend using the server APIs.
+
+--------------------
+
+
+### getCachedVirtualCurrencies()
+
+```typescript
+getCachedVirtualCurrencies() => Promise<{ cachedVirtualCurrencies: PurchasesVirtualCurrencies | null; }>
+```
+
+The currently cached {@link <a href="#purchasesvirtualcurrencies">PurchasesVirtualCurrencies</a>} if one is available.
+This value will remain null until virtual currencies have been fetched at
+least once with {@link getVirtualCurrencies} or an equivalent function.
+
+**Returns:** <code>Promise&lt;{ cachedVirtualCurrencies: <a href="#purchasesvirtualcurrencies">PurchasesVirtualCurrencies</a> | null; }&gt;</code>
+
+--------------------
+
+
 ### parseAsWebPurchaseRedemption(...)
 
 ```typescript
@@ -1229,6 +1275,28 @@ Holds parameters to initialize the SDK.
 | **`diagnosticsEnabled`**                        | <code>boolean</code>                                                                    | Enabling diagnostics will send some performance and debugging information from the SDK to RevenueCat's servers. Examples of this information include response times, cache hits or error codes. No personal identifiable information will be collected. The default value is false.                                                                                                                                                                                                       |
 
 
+#### PurchasesVirtualCurrencies
+
+The VirtualCurrencies object contains all the virtual currencies associated to the user.
+
+| Prop      | Type                                                                                              | Description                                                                                                                             |
+| --------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| **`all`** | <code>{ [key: string]: <a href="#purchasesvirtualcurrency">PurchasesVirtualCurrency</a>; }</code> | Map of all VirtualCurrency (<a href="#purchasesvirtualcurrency">`PurchasesVirtualCurrency`</a>) objects keyed by virtual currency code. |
+
+
+#### PurchasesVirtualCurrency
+
+The VirtualCurrency object represents information about a virtual currency in the app.
+Use this object to access information about a virtual currency, such as its current balance.
+
+| Prop                    | Type                        | Description                                                             |
+| ----------------------- | --------------------------- | ----------------------------------------------------------------------- |
+| **`balance`**           | <code>number</code>         | The virtual currency's balance.                                         |
+| **`name`**              | <code>string</code>         | The virtual currency's name.                                            |
+| **`code`**              | <code>string</code>         | The virtual currency's code.                                            |
+| **`serverDescription`** | <code>string \| null</code> | The virtual currency's description defined in the RevenueCat dashboard. |
+
+
 #### CustomerInfo
 
 Type containing all information regarding the customer

android/src/main/java/com/revenuecat/purchases/capacitor/PurchasesPlugin.kt

@@ -32,11 +32,14 @@ import com.revenuecat.purchases.hybridcommon.canMakePayments as canMakePaymentsC
 import com.revenuecat.purchases.hybridcommon.checkTrialOrIntroductoryPriceEligibility as checkTrialOrIntroductoryPriceEligibilityCommon
 import com.revenuecat.purchases.hybridcommon.collectDeviceIdentifiers as collectDeviceIdentifiersCommon
 import com.revenuecat.purchases.hybridcommon.getAppUserID as getAppUserIDCommon
+import com.revenuecat.purchases.hybridcommon.getCachedVirtualCurrencies as getCachedVirtualCurrenciesCommon
 import com.revenuecat.purchases.hybridcommon.getCurrentOfferingForPlacement as getCurrentOfferingForPlacementCommon
 import com.revenuecat.purchases.hybridcommon.getCustomerInfo as getCustomerInfoCommon
 import com.revenuecat.purchases.hybridcommon.getOfferings as getOfferingsCommon
 import com.revenuecat.purchases.hybridcommon.getStorefront as getStorefrontCommon
+import com.revenuecat.purchases.hybridcommon.getVirtualCurrencies as getVirtualCurrenciesCommon
 import com.revenuecat.purchases.hybridcommon.invalidateCustomerInfoCache as invalidateCustomerInfoCacheCommon
+import com.revenuecat.purchases.hybridcommon.invalidateVirtualCurrenciesCache as invalidateVirtualCurrenciesCacheCommon
 import com.revenuecat.purchases.hybridcommon.isAnonymous as isAnonymousCommon
 import com.revenuecat.purchases.hybridcommon.logIn as logInCommon
 import com.revenuecat.purchases.hybridcommon.logOut as logOutCommon
@@ -125,6 +128,25 @@ class PurchasesPlugin : Plugin() {
         call.resolve()
     }
 
+    @PluginMethod(returnType = PluginMethod.RETURN_PROMISE)
+    fun getVirtualCurrencies(call: PluginCall) {
+        if (rejectIfNotConfigured(call)) return
+        getVirtualCurrenciesCommon(getOnResult(call, "virtualCurrencies"))
+    }  
+
+    @PluginMethod(returnType = PluginMethod.RETURN_NONE)
+    fun invalidateVirtualCurrenciesCache(call: PluginCall) {
+        if (rejectIfNotConfigured(call)) return
+        invalidateVirtualCurrenciesCacheCommon()
+        call.resolve()
+    }
+
+    @PluginMethod(returnType = PluginMethod.RETURN_PROMISE)
+    fun getCachedVirtualCurrencies(call: PluginCall) {
+        if (rejectIfNotConfigured(call)) return
+        call.resolveWithMap(mapOf("cachedVirtualCurrencies" to getCachedVirtualCurrenciesCommon()))
+    }
+
     @PluginMethod(returnType = PluginMethod.RETURN_PROMISE)
     fun parseAsWebPurchaseRedemption(call: PluginCall) {
         val urlString = call.getStringOrReject("urlString") ?: return

example/purchase-tester/src/components/FunctionTesterContainer.tsx

@@ -540,6 +540,21 @@ const FunctionTesterContainer: React.FC<ContainerProps> = () => {
     updateLastFunction('isConfigured', isConfiguredResult);
   };
 
+  const getVirtualCurrencies = async () => {
+    const virtualCurrencies = await Purchases.getVirtualCurrencies();
+    updateLastFunction('getVirtualCurrencies', virtualCurrencies);
+  };
+
+  const invalidateVirtualCurrenciesCache = async () => {
+    await Purchases.invalidateVirtualCurrenciesCache();
+    updateLastFunctionWithoutContent('invalidateVirtualCurrenciesCache');
+  };
+
+  const getCachedVirtualCurrencies = async () => {
+    const cachedVirtualCurrencies = await Purchases.getCachedVirtualCurrencies();
+    updateLastFunction('getCachedVirtualCurrencies', cachedVirtualCurrencies);
+  };
+
   const purchaseProductForWinBackTesting = async () => {
     try {
       const products = await Purchases.getProducts({
@@ -946,6 +961,15 @@ const FunctionTesterContainer: React.FC<ContainerProps> = () => {
         <IonButton size="small" onClick={isConfigured}>
           Is configured?
         </IonButton>
+        <IonButton size="small" onClick={getVirtualCurrencies}>
+          Get virtual currencies
+        </IonButton>
+        <IonButton size="small" onClick={invalidateVirtualCurrenciesCache}>
+          Invalidate virtual currencies cache
+        </IonButton>
+        <IonButton size="small" onClick={getCachedVirtualCurrencies}>
+          Get cached virtual currencies
+        </IonButton>
         <IonButton size="small" onClick={purchaseProductForWinBackTesting}>
           Purchase Product for WinBack Testing
         </IonButton>

ios/Plugin/PurchasesPlugin.m

@@ -5,6 +5,9 @@
 // each method the plugin supports using the CAP_PLUGIN_METHOD macro.
 CAP_PLUGIN(PurchasesPlugin, "Purchases",
            CAP_PLUGIN_METHOD(configure, CAPPluginReturnNone);
+           CAP_PLUGIN_METHOD(getVirtualCurrencies, CAPPluginReturnPromise);
+           CAP_PLUGIN_METHOD(invalidateVirtualCurrenciesCache, CAPPluginReturnNone);
+           CAP_PLUGIN_METHOD(getCachedVirtualCurrencies, CAPPluginReturnPromise);
            CAP_PLUGIN_METHOD(parseAsWebPurchaseRedemption, CAPPluginReturnPromise);
            CAP_PLUGIN_METHOD(redeemWebPurchase, CAPPluginReturnPromise);
            CAP_PLUGIN_METHOD(setMockWebResults, CAPPluginReturnNone);

ios/Plugin/PurchasesPlugin.swift

@@ -69,6 +69,29 @@ public class PurchasesPlugin: CAPPlugin, PurchasesDelegate {
         call.resolve()
     }
 
+    @objc func getVirtualCurrencies(_ call: CAPPluginCall) {
+        guard self.rejectIfPurchasesNotConfigured(call) else { return }
+        CommonFunctionality.getVirtualCurrencies(
+            completion: self.getCompletionBlockHandler(
+                call, 
+                wrapperKey: "virtualCurrencies"
+            )
+        )
+    }
+
+    @objc func invalidateVirtualCurrenciesCache(_ call: CAPPluginCall) {
+        guard self.rejectIfPurchasesNotConfigured(call) else { return }
+        CommonFunctionality.invalidateVirtualCurrenciesCache()
+        call.resolve()
+    }
+
+    @objc func getCachedVirtualCurrencies(_ call: CAPPluginCall) {
+        guard self.rejectIfPurchasesNotConfigured(call) else { return }
+        call.resolve([
+            "cachedVirtualCurrencies": CommonFunctionality.getCachedVirtualCurrencies()
+        ])
+    }
+
     @objc func parseAsWebPurchaseRedemption(_ call: CAPPluginCall) {
         guard let urlString = call.getOrRejectString("urlString") else { return }
         let result: [String: Any?]

src/definitions.ts

@@ -19,6 +19,7 @@ import type {
   PurchasesStoreProduct,
   PurchasesStoreProductDiscount,
   PurchasesStoreTransaction,
+  PurchasesVirtualCurrencies,
   PurchasesWinBackOffer,
   REFUND_REQUEST_STATUS,
   Storefront,
@@ -200,6 +201,33 @@ export interface PurchasesPlugin {
    */
   configure(configuration: PurchasesConfiguration): Promise<void>;
 
+  /**
+   * Fetches the virtual currencies for the current subscriber.
+   *
+   * @returns {Promise<{ virtualCurrencies: PurchasesVirtualCurrencies }>} A promise of a {@link PurchasesVirtualCurrencies} object.
+   * The promise will be rejected if configure has not been called yet or if an error occurs while getting the virtual currencies.
+   */
+  getVirtualCurrencies(): Promise<{ virtualCurrencies: PurchasesVirtualCurrencies }>;
+
+  /**
+   * Invalidates the cache for virtual currencies.
+   *
+   * This is useful for cases where a virtual currency's balance might have been updated
+   * outside of the app, like if you decreased a user's balance from the user spending a virtual currency,
+   * or if you increased the balance from your backend using the server APIs.
+   */
+  invalidateVirtualCurrenciesCache(): Promise<void>;
+
+  /**
+   * The currently cached {@link PurchasesVirtualCurrencies} if one is available.
+   * This value will remain null until virtual currencies have been fetched at
+   * least once with {@link getVirtualCurrencies} or an equivalent function.
+   *
+   * @returns {Promise<{ cachedVirtualCurrencies: PurchasesVirtualCurrencies | null }>} The currently cached virtual currencies for the current subscriber.
+   * The promise will be rejected if configure has not been called yet or there's an error.
+   */
+  getCachedVirtualCurrencies(): Promise<{ cachedVirtualCurrencies: PurchasesVirtualCurrencies | null }>;
+
   /**
    * Parses the given URL string into a [WebPurchaseRedemption] object that can be used to redeem web purchases.
    * @param options Set the urlString used to open the App.

src/web.ts

@@ -18,6 +18,7 @@ import type {
   PurchasesPromotionalOffer,
   PurchasesStoreProduct,
   PurchasesStoreTransaction,
+  PurchasesVirtualCurrencies,
   PurchasesWinBackOffer,
   ShouldPurchasePromoProductListener,
   Storefront,
@@ -350,6 +351,22 @@ export class PurchasesWeb extends WebPlugin implements PurchasesPlugin {
     return this.mockReturningFunctionIfEnabled('isConfigured', mockResult);
   }
 
+  getVirtualCurrencies(): Promise<{ virtualCurrencies: PurchasesVirtualCurrencies }> {
+    return this.mockReturningFunctionIfEnabled('getVirtualCurrencies', {
+      virtualCurrencies: this.mockEmptyVirtualCurrencies,
+    });
+  }
+
+  invalidateVirtualCurrenciesCache(): Promise<void> {
+    return this.mockNonReturningFunctionIfEnabled('invalidateVirtualCurrenciesCache');
+  }
+
+  getCachedVirtualCurrencies(): Promise<{ cachedVirtualCurrencies: PurchasesVirtualCurrencies | null }> {
+    return this.mockReturningFunctionIfEnabled('getCachedVirtualCurrencies', {
+      cachedVirtualCurrencies: this.mockEmptyVirtualCurrencies,
+    });
+  }
+
   // Mock helpers
 
   private mockEmptyCustomerInfo: CustomerInfo = {
@@ -373,6 +390,10 @@ export class PurchasesWeb extends WebPlugin implements PurchasesPlugin {
     subscriptionsByProductIdentifier: {},
   };
 
+  private mockEmptyVirtualCurrencies: PurchasesVirtualCurrencies = {
+    all: {},
+  };
+
   private mockTransaction(productIdentifier: string): PurchasesStoreTransaction {
     return {
       productIdentifier: productIdentifier,