Merge pull request #423 from qonversion/feature/dev-643-deferred-purchases-listener

Add DeferredPurchasesListener, deprecate EntitlementsUpdateListener

Author: NickSxti

android/src/main/java/com/qonversion/reactnativesdk/QonversionModule.kt

@@ -299,6 +299,11 @@ class QonversionModule(reactContext: ReactApplicationContext) : NativeQonversion
         emitOnEntitlementsUpdated(mappedEntitlements)
     }
 
+    override fun onDeferredPurchaseCompleted(purchaseResult: BridgeData) {
+        val mappedPurchaseResult = EntitiesConverter.convertMapToWritableMap(purchaseResult)
+        emitOnDeferredPurchaseCompleted(mappedPurchaseResult)
+    }
+
     companion object {
         const val NAME = "RNQonversion"
     }

ios/RNQonversion.mm

@@ -317,6 +317,14 @@ - (void)qonversionDidReceiveUpdatedEntitlements:(NSDictionary<NSString *,id> * _
     }
 }
 
+- (void)qonversionDidCompleteDeferredPurchase:(NSDictionary<NSString *,id> * _Nonnull)purchaseResult {
+    @try {
+        [self emitOnDeferredPurchaseCompleted:purchaseResult];
+    } @catch (NSException *exception) {
+        QNR_LOG_EXCEPTION("qonversionDidCompleteDeferredPurchase", exception);
+    }
+}
+
 - (void)shouldPurchasePromoProductWith:(NSString * _Nonnull)productId {
     @try {
         [self emitOnPromoPurchaseReceived:productId];

ios/RNQonversionImpl.swift

@@ -13,6 +13,7 @@ import React
 public protocol QonversionEventDelegate {
     func shouldPurchasePromoProduct(with productId: String)
     func qonversionDidReceiveUpdatedEntitlements(_ entitlements: [String: Any])
+    func qonversionDidCompleteDeferredPurchase(_ purchaseResult: [String: Any])
 }
 
 class QonversionEventHandler: QonversionEventListener {
@@ -25,6 +26,10 @@ class QonversionEventHandler: QonversionEventListener {
     func qonversionDidReceiveUpdatedEntitlements(_ entitlements: [String: Any]) {
         delegate?.qonversionDidReceiveUpdatedEntitlements(entitlements)
     }
+
+    func qonversionDidCompleteDeferredPurchase(_ purchaseResult: [String: Any]) {
+        delegate?.qonversionDidCompleteDeferredPurchase(purchaseResult)
+    }
 }
 
 @objc

src/QonversionApi.ts

@@ -5,6 +5,7 @@ import Offerings from './dto/Offerings';
 import IntroEligibility from './dto/IntroEligibility';
 import User from './dto/User';
 import type {EntitlementsUpdateListener} from './dto/EntitlementsUpdateListener';
+import type {DeferredPurchasesListener} from './dto/DeferredPurchasesListener';
 import type {PromoPurchasesListener} from './dto/PromoPurchasesListener';
 import RemoteConfig from "./dto/RemoteConfig";
 import RemoteConfigList from "./dto/RemoteConfigList";
@@ -239,9 +240,28 @@ export interface QonversionApi {
    * with {@link Qonversion.initialize}.
    *
    * @param listener listener to be called when entitlements update
+   * @deprecated Use {@link setDeferredPurchasesListener} instead.
    */
   setEntitlementsUpdateListener(listener: EntitlementsUpdateListener): void;
 
+  /**
+   * Provide a listener to be notified about deferred purchase completions.
+   *
+   * Deferred purchases happen when transactions require additional steps to complete,
+   * such as SCA (Strong Customer Authentication), Ask to Buy, or other pending transactions.
+   * This listener will be called when such purchases are finalized.
+   *
+   * Make sure you provide this listener for being up-to-date with deferred purchase completions.
+   * Also, please, consider that this listener should live for the whole lifetime of the application.
+   *
+   * You may set deferred purchases listener both *after* Qonversion SDK initializing
+   * with {@link QonversionApi.setDeferredPurchasesListener} and *while* Qonversion initializing
+   * with {@link Qonversion.initialize}.
+   *
+   * @param listener listener to be called when a deferred purchase completes
+   */
+  setDeferredPurchasesListener(listener: DeferredPurchasesListener): void;
+
   /**
    * iOS only. Does nothing if called on Android.
    *

src/QonversionConfig.ts

@@ -1,12 +1,15 @@
 import {EntitlementsCacheLifetime, Environment, LaunchMode} from './dto/enums';
 import type {EntitlementsUpdateListener} from './dto/EntitlementsUpdateListener';
+import type {DeferredPurchasesListener} from './dto/DeferredPurchasesListener';
 
 class QonversionConfig {
   readonly projectKey: string;
   readonly launchMode: LaunchMode;
   readonly environment: Environment;
   readonly entitlementsCacheLifetime: EntitlementsCacheLifetime;
+  /** @deprecated Use {@link deferredPurchasesListener} instead. */
   readonly entitlementsUpdateListener: EntitlementsUpdateListener | undefined;
+  readonly deferredPurchasesListener: DeferredPurchasesListener | undefined;
   readonly proxyUrl: string | undefined;
   readonly kidsMode: boolean;
 
@@ -16,14 +19,16 @@ class QonversionConfig {
     environment: Environment = Environment.PRODUCTION,
     entitlementsCacheLifetime: EntitlementsCacheLifetime = EntitlementsCacheLifetime.MONTH,
     entitlementsUpdateListener: EntitlementsUpdateListener | undefined = undefined,
-    proxyUrl: string | undefined,
-    kidsMode: boolean = false
+    deferredPurchasesListener: DeferredPurchasesListener | undefined = undefined,
+    proxyUrl: string | undefined = undefined,
+    kidsMode: boolean = false,
   ) {
     this.projectKey = projectKey;
     this.launchMode = launchMode;
     this.environment = environment;
     this.entitlementsCacheLifetime = entitlementsCacheLifetime;
     this.entitlementsUpdateListener = entitlementsUpdateListener;
+    this.deferredPurchasesListener = deferredPurchasesListener;
     this.proxyUrl = proxyUrl;
     this.kidsMode = kidsMode;
   }

src/QonversionConfigBuilder.ts

@@ -1,5 +1,6 @@
 import {EntitlementsCacheLifetime, Environment, LaunchMode} from './dto/enums';
 import type {EntitlementsUpdateListener} from './dto/EntitlementsUpdateListener';
+import type {DeferredPurchasesListener} from './dto/DeferredPurchasesListener';
 import QonversionConfig from './QonversionConfig';
 
 class QonversionConfigBuilder {
@@ -14,9 +15,11 @@ class QonversionConfigBuilder {
   private environment: Environment = Environment.PRODUCTION;
   private entitlementsCacheLifetime: EntitlementsCacheLifetime = EntitlementsCacheLifetime.MONTH;
   private entitlementsUpdateListener: EntitlementsUpdateListener | undefined = undefined;
+  private deferredPurchasesListener: DeferredPurchasesListener | undefined = undefined;
   private proxyUrl: string | undefined = undefined;
   private kidsMode: boolean = false;
 
+
   /**
    * Set current application {@link Environment}. Used to distinguish sandbox and production users.
    *
@@ -51,12 +54,31 @@ class QonversionConfigBuilder {
    *
    * @param entitlementsUpdateListener listener to be called when entitlements update.
    * @return builder instance for chain calls.
+   * @deprecated Use {@link setDeferredPurchasesListener} instead.
    */
   setEntitlementsUpdateListener(entitlementsUpdateListener: EntitlementsUpdateListener): QonversionConfigBuilder {
     this.entitlementsUpdateListener = entitlementsUpdateListener;
     return this;
   }
 
+  /**
+   * Provide a listener to be notified about deferred purchase completions.
+   *
+   * Deferred purchases happen when transactions require additional steps to complete,
+   * such as SCA (Strong Customer Authentication), Ask to Buy, or other pending transactions.
+   * This listener will be called when such purchases are finalized.
+   *
+   * Make sure you provide this listener for being up-to-date with deferred purchase completions.
+   * Also, please, consider that this listener should live for the whole lifetime of the application.
+   *
+   * @param listener listener to be called when a deferred purchase completes.
+   * @return builder instance for chain calls.
+   */
+  setDeferredPurchasesListener(listener: DeferredPurchasesListener): QonversionConfigBuilder {
+    this.deferredPurchasesListener = listener;
+    return this;
+  }
+
   /**
    * Provide a URL to your proxy server which will redirect all the requests from the app
    * to our API. Please, contact us before using this feature.
@@ -93,8 +115,9 @@ class QonversionConfigBuilder {
       this.environment,
       this.entitlementsCacheLifetime,
       this.entitlementsUpdateListener,
+      this.deferredPurchasesListener,
       this.proxyUrl,
-      this.kidsMode
+      this.kidsMode,
     )
   }
 }

src/dto/DeferredPurchasesListener.ts

@@ -0,0 +1,12 @@
+import PurchaseResult from './PurchaseResult';
+
+export interface DeferredPurchasesListener {
+
+  /**
+   * Called when a deferred purchase completes.
+   * For example, when pending purchases like SCA, Ask to buy, etc., are approved and finalized.
+   * Provides the full purchase result with entitlements and store transaction details.
+   * @param purchaseResult the result of the completed deferred purchase.
+   */
+  onDeferredPurchaseCompleted(purchaseResult: PurchaseResult): void;
+}

src/dto/EntitlementsUpdateListener.ts

@@ -1,5 +1,8 @@
 import Entitlement from './Entitlement';
 
+/**
+ * @deprecated Use {@link DeferredPurchasesListener} instead.
+ */
 export interface EntitlementsUpdateListener {
 
   /**

src/index.ts

@@ -4,6 +4,7 @@ export { default as QonversionConfig } from './QonversionConfig';
 export { default as QonversionConfigBuilder } from './QonversionConfigBuilder';
 
 export type { EntitlementsUpdateListener } from './dto/EntitlementsUpdateListener';
+export type { DeferredPurchasesListener } from './dto/DeferredPurchasesListener';
 export * from './dto/enums';
 export { default as IntroEligibility } from './dto/IntroEligibility';
 export { default as Offering } from './dto/Offering';

src/internal/QonversionInternal.ts

@@ -8,6 +8,7 @@ import Product from "../dto/Product";
 import PurchaseResult from "../dto/PurchaseResult";
 import {isAndroid, isIos} from "./utils";
 import type {EntitlementsUpdateListener} from '../dto/EntitlementsUpdateListener';
+import type {DeferredPurchasesListener} from '../dto/DeferredPurchasesListener';
 import type {PromoPurchasesListener} from '../dto/PromoPurchasesListener';
 import User from '../dto/User';
 import PurchaseOptions from '../dto/PurchaseOptions';
@@ -29,8 +30,9 @@ export const sdkSource = "rn";
 
 export default class QonversionInternal implements QonversionApi {
 
-  private entitlementsUpdateListener: EntitlementsUpdateListener | null = null;
+  private deferredPurchasesListener: DeferredPurchasesListener | null = null;
   private promoPurchasesDelegate: PromoPurchasesListener | null = null;
+  private deferredPurchaseEventSubscribed = false;
 
   constructor(qonversionConfig: QonversionConfig) {
     RNQonversion.storeSDKInfo(sdkSource, sdkVersion);
@@ -46,6 +48,10 @@ export default class QonversionInternal implements QonversionApi {
     if (qonversionConfig.entitlementsUpdateListener) {
       this.setEntitlementsUpdateListener(qonversionConfig.entitlementsUpdateListener);
     }
+
+    if (qonversionConfig.deferredPurchasesListener) {
+      this.setDeferredPurchasesListener(qonversionConfig.deferredPurchasesListener);
+    }
   }
 
   syncHistoricalData () {
@@ -382,9 +388,19 @@ export default class QonversionInternal implements QonversionApi {
     return;
   }
 
-  private entitlementsUpdatedEventHandler = (payload: Object) => {
-    const entitlements = Mapper.convertEntitlements(payload as Record<string, QEntitlement>);
-    this.entitlementsUpdateListener?.onEntitlementsUpdated(entitlements);
+  private subscribeToDeferredPurchaseEvent() {
+    if (!this.deferredPurchaseEventSubscribed) {
+      RNQonversion.onDeferredPurchaseCompleted(this.deferredPurchaseCompletedEventHandler);
+      this.deferredPurchaseEventSubscribed = true;
+    }
+  }
+
+  private deferredPurchaseCompletedEventHandler = (payload: Object) => {
+    const purchaseResult = Mapper.convertPurchaseResult(payload as Record<string, any>);
+
+    if (purchaseResult) {
+      this.deferredPurchasesListener?.onDeferredPurchaseCompleted(purchaseResult);
+    }
   }
 
   private promoPurchaseReceivedEventHandler = (productId: string) => {
@@ -397,11 +413,18 @@ export default class QonversionInternal implements QonversionApi {
   }
 
   setEntitlementsUpdateListener(listener: EntitlementsUpdateListener) {
-    if (this.entitlementsUpdateListener == null) {
-      RNQonversion.onEntitlementsUpdated(this.entitlementsUpdatedEventHandler);
-    }
-    
-    this.entitlementsUpdateListener = listener;
+    this.setDeferredPurchasesListener({
+      onDeferredPurchaseCompleted: (purchaseResult: PurchaseResult) => {
+        if (purchaseResult.entitlements) {
+          listener.onEntitlementsUpdated(purchaseResult.entitlements);
+        }
+      }
+    });
+  }
+
+  setDeferredPurchasesListener(listener: DeferredPurchasesListener) {
+    this.subscribeToDeferredPurchaseEvent();
+    this.deferredPurchasesListener = listener;
   }
 
   setPromoPurchasesDelegate(delegate: PromoPurchasesListener) {