onPurchaseRequest()

Registers a listener invoked when Encore’s offer flow completes and a purchase is needed. The listener receives the product ID and placement ID and should trigger the purchase via your billing library.

You must call completePurchaseRequest() in every code path of your handler — both success and failure. Failing to do so will block the SDK from presenting future offers until the app restarts.

Signature

onPurchaseRequest(handler: (event: PurchaseRequestEvent) => void): () => void

Parameters

Name	Type	Description
`handler`	`(event: PurchaseRequestEvent) => void`	Callback receiving the purchase request event

PurchaseRequestEvent

Field	Type	Description
`productId`	string	The App Store / Play Store product ID to purchase
`placementId`	string?	Which placement triggered this request

Returns

An unsubscribe function. Call it to remove the listener.

When It Fires

Scenario	Fires?
User accepts an offer	Yes
User dismisses without purchasing	No — see onPassthrough()
No offer available for this user	No — see onPassthrough()

Usage

RevenueCat
react-native-iap
Custom

const unsubscribe = Encore.onPurchaseRequest(async ({ productId }) => {
  try {
    const { customerInfo } = await Purchases.purchaseProduct(productId);
    await Encore.completePurchaseRequest(true);
  } catch (error) {
    await Encore.completePurchaseRequest(false);
  }
});

const unsubscribe = Encore.onPurchaseRequest(async ({ productId }) => {
  try {
    await RNIap.requestSubscription({ sku: productId });
    await Encore.completePurchaseRequest(true);
  } catch (error) {
    await Encore.completePurchaseRequest(false);
  }
});

const unsubscribe = Encore.onPurchaseRequest(async ({ productId, placementId }) => {
  try {
    // Your billing library here
    await yourBillingService.purchase(productId);
    await Encore.completePurchaseRequest(true);
  } catch (error) {
    await Encore.completePurchaseRequest(false);
  }
});

Every code path must call completePurchaseRequest(). If your handler throws without calling it, the SDK will remain locked until the app restarts. Always use try/catch.

With onPassthrough

useEffect(() => {
  const unsub1 = Encore.onPurchaseRequest(async ({ productId }) => {
    try {
      await billingService.purchase(productId);
      await Encore.completePurchaseRequest(true);
    } catch (error) {
      await Encore.completePurchaseRequest(false);
    }
  });

  const unsub2 = Encore.onPassthrough(({ placementId }) => {
    proceedWithCancellation();
  });

  return () => {
    unsub1();
    unsub2();
  };
}, []);

Clean up listeners when your component unmounts by calling the unsubscribe function in a useEffect cleanup.

Getting Started

iOS SDK

Android SDK

Flutter SDK

React Native SDK

Capacitor SDK

Kotlin Multiplatform SDK

Web SDK

Integration Patterns

Automated Messaging

Offer Catalog

Offers API

Signature

Parameters

PurchaseRequestEvent

Returns

When It Fires

Usage

With onPassthrough

​Signature

​Parameters

​PurchaseRequestEvent

​Returns

​When It Fires

​Usage

​With onPassthrough

Signature

Parameters

PurchaseRequestEvent

Returns

When It Fires

Usage

With onPassthrough