Observer Mode

Using RevenueCat without changing existing purchase code

Observer Mode enables you to migrate your existing subscribers to RevenueCat while retaining your existing code for fetching products, making purchases, and checking subscription status. This allows you to access to the advanced charting, webhooks, and integrations that RevenueCat provides as quickly as possible and with minimal engineering effort.

Observer Mode may be set up as part of your migration strategy to RevenueCat, or as a permanent solution. Use the table below to compare what features become available with Observer Mode vs. a full RevenueCat SDK integration.

Feature

Observer Mode

Full Integration

Charts

✅ *

Webhooks & Integrations

Data Exports

Customer Lists

✅ *

Experiments

Fetching Products

Making Purchases

Checking Subscription Status

❌ **

*information based around the "last seen time" and "country" may not be complete in Observer Mode

**subscription status will be correct for your customers in Observer Mode, but we strongly recommend a full integration if planning to use RevenueCat as your subscription source-of-truth

Implementation

Observer Mode can be implemented server-side via REST APIs or client-side through the RevenueCat SDK. You should only implement Observer Mode one way or the other.

Option 1: Server-side

Pros

Cons

✅ No client-side code changes

❌ The "last seen" attribute will be missing from customers since they are never "seen" by the client

✅ Captures purchases from any app version

❌ The "country" attribute will be missing from customers and transactions since it is computed from the customer's device IP address

If you're already sending receipts to your server, you can enable Observer Mode by forwarding the receipts along to RevenueCat then processing them as you normally do.

With this option, you should already have a process in place for validating receipts on your server. When you receive a receipt, you can forward it to RevenueCat via the POST /receipts endpoint then have your server continue doing whatever it is already.

Don't worry about validating the receipt before forwarding to RevenueCat - we always validate receipts with the stores before saving them.

Requirements

The requirements for server-side Observer Mode are the same as those for the POST /receipts endpoint. This includes:

  • app_user_id
  • fetch_token
  • price
  • currency
  • product_id

While price, currency, and product_id are not required parameters for the API, they're highly recommended for Observer Mode to get value out of the integration - without providing this info RevenueCat will not have any price information.

If you're not already sending price and currency to your server there are two options:

  1. Update your client-side code to start sending price and currency to your server. However, at this point a client-side Observer Mode setup may be simpler.
  2. Hardcode a mapping of product IDs to their corresponding USD currency on your server. While this system isn't perfect as it won't account for country specific pricing and currency conversion rates, it may be a suitable approximation.

🚧

Complete Apple base64 receipt file required

Observer Mode requires the raw base64 encoded Apple receipt as the fetch_token. Partial receipts or the receipt information from the Apple server-to-server notifications is insufficient.

Option 2: Client-side

Pros

Cons

✅ No server-side code changes

❌ Only captures purchases from latest app version

If you're not saving receipts already on your server, or have limited backend resources available, a client-side Observer Mode implementation is often the best path. Implementation is no more than a couple lines

Requirements

Android
Google Play Billing Library: 2.0+ (Android only)

iOS
No special requirements

Amazon
❌ Not supported with client-side Observer Mode

1. Configure the SDK

Purchases.configure(
            withAPIKey: "my_api_key",
            appUserID: "my_app_user_id",
            observerMode: true)
[RCPurchases 
    configureWithAPIKey:@"my_api_key" 
    appUserID:@"my_app_user_id"
    observerMode: YES];
Purchases.configure(this, "my_api_key", "my_app_user_id", true)
Purchases.configure(this, "my_api_key", "my_app_user_id", true);
await Purchases.setup("my_api_key", observerMode: true);
See "Enable Observer Mode in Unity configuration" below

Enable Observer Mode in Unity configuration (Unity Only)

🚧

Important note regarding InAppBillingService (Android Unity only)

If using RevenueCat alongside Unity IAP or other plugin that includes the Android InAppBillingService class, follow these instructions

2. Sync purchases with RevenueCat (Android only)

On Android (including cross-platform SDKs running on Android), any time a purchase or restore occurs in your app you should call the syncPurchases method to record it in RevenueCat. Failure to do so will result in no purchases being recorded.

// Called any time a purchase or restore 
// is successful in your existing code
Purchases.sharedInstance.syncPurchases()
// Called any time a purchase or restore 
// is successful in your existing code
Purchases.getSharedInstance().syncPurchases();
// Called any time a purchase or restore 
// is successful in your existing code
Purchases.syncPurchases();

❗️

Important (Android only)

On Android, RevenueCat will not consume or acknowledge any purchase in Observer Mode so be sure your app is handling that. Failure to do so will result in your purchases being refunded after 3 days.

Configuring Integrations

Certain integrations, such as most of the Attribution Integrations, require some device data to work properly. Observer Mode does not automatically collect any device data.

If you plan on using an integration that requires device data with Observer Mode, you'll need to integrate the RevenueCat SDK to collect the data or set the appropriate attributes via the REST API. Note that attributes can be passed as an object in the POST /receipts endpoint as well if you're doing a server-side Observer Mode implementation.

Next Steps


Did this page help you?