Kebechet.Maui.RevenueCat.InAppBilling 10.1.0

Maui.RevenueCat.InAppBilling

A .NET MAUI wrapper library for RevenueCat in-app purchases. Provides a unified C# API that abstracts away the need for you to use platform-specific code from Android and iOS native bindings.

Features

• Unified API for iOS, Android and Mac Catalyst in-app purchases
• Subscription and one-time purchase support
• User authentication (anonymous and identified users)
• Subscription status and entitlement checking
• Trial/intro discount eligibility
• Subscriber attributes management
• Test Store test_… keys work in Release builds on iOS - the shipped xcframework is built from source with BYPASS_SIMULATED_STORE_RELEASE_CHECK, so it does not force-close the app
• Stub implementation for Windows (for development convenience)

Installation

dotnet add package Kebechet.Maui.RevenueCat.InAppBilling

Quick Start

1. Register the service

In your MauiProgram.cs:

builder.Services.AddRevenueCatBilling();

2. Inject and initialize

In App.xaml.cs, inject IRevenueCatBilling and initialize in OnStart():

public partial class App : Application
{
    private readonly IRevenueCatBilling _revenueCat;

    public App(IRevenueCatBilling revenueCat)
    {
        InitializeComponent();
        _revenueCat = revenueCat;
    }

    protected override void OnStart()
    {
        var revenueCatApiKey = string.Empty;

#if __ANDROID__
        revenueCatApiKey = "<your-android-api-key>";
#elif __IOS__
        revenueCatApiKey = "<your-ios-api-key>";
#endif

        _revenueCat.Initialize(revenueCatApiKey);
        base.OnStart();
    }
}

Important: Initialize must be called in OnStart(), not in the constructor.

Tip: If you already know your user's ID at startup, use Initialize(revenueCatApiKey, appUserId) instead - RevenueCat then never creates an anonymous user ($RCAnonymousID:...), so your custom ID won't show up as an alias of an anonymous customer.

Test Store API keys

RevenueCat's Test Store lets you exercise the full purchase flow without configuring App Store Connect / Play Console products. Test Store keys start with test_.

This wrapper ships an iOS xcframework built from source with the BYPASS_SIMULATED_STORE_RELEASE_CHECK Swift compilation flag, so a test_… key works on iOS Release builds too — it does not force-close the app. No code changes are required on your side; just pass the test_… key to Initialize(...).

On Android no such rebuild is needed: the RevenueCat SDK ships as a normal AAR (Kotlin bytecode), so its test-key check runs against the consuming app's build at runtime rather than being compiled into the library — a prebuilt AAR doesn't carry the always-on guard the prebuilt iOS framework did. Test Store support does require RevenueCat Android SDK 9.9.0+; this binding ships upstream SDK 11.1.0 (binding package 11.1.0), so test_… keys work out of the box in Debug builds (see issue #95, resolved by the 10.1.2 SDK bump). In a Release build of your app, RevenueCat refuses the key with a ConfigurationError ("Test Store API key used in release build"). The same "don't ship a test_ key to production" guidance applies on both platforms.

See src/Maui.RevenueCat.iOS/README.md for the build-time details and issue #116 for context.

Debug logs

RevenueCat's debug logs are off by default. Enable them explicitly, for example only in your Debug builds:

#if DEBUG
builder.Services.AddRevenueCatBilling(forceEnableDebugLogs: true);
#else
builder.Services.AddRevenueCatBilling();
#endif

Where to read them:

• Android: logcat, filter by Purchases.
• iOS: the device's system log, not the Visual Studio output window. Open it in Xcode → Window → Devices and Simulators → Open Console, or in Console.app on the Mac, and filter by Purchases.

When offerings come back empty with a configuration error, the logs show which product identifiers RevenueCat requested from the store. See Why are offerings empty? and issue #127.

API Reference

Initialization & State

Offerings & Products

Purchases

User Management

Customer Info Caching

The RevenueCat SDK caches customer info on the device and treats it as stale after 5 minutes while the app is in the foreground (RevenueCat docs), but only after 25 hours while it is in the background (an iOS sandbox build keeps 5 minutes). fetchPolicy decides whether GetCustomerInfo answers from that cache:

A failed call sets Error to CustomerInfoError when FromCacheOnly finds nothing cached. A fetch that fails because the device is offline sets NetworkError on Android and OfflineConnectionError on iOS.

// e.g. after the user bought on the web, so the device cache cannot know about it yet
var customerInfoResult = await _revenueCat.GetCustomerInfo(CustomerInfoFetchPolicy.FetchCurrent);

PurchaseProduct(), RestoreTransactions() and Logout() already return fresh customer info, and so does Login() when it switches to a different app user ID. Login() with the ID that is already logged in reads with CachedOrFetched instead, so it can return stale data - follow it with GetCustomerInfo(CustomerInfoFetchPolicy.FetchCurrent) when that matters. GetActiveSubscriptions(), GetAllPurchasedIdentifiers(), GetPurchaseDateForProductIdentifier() and GetManagementSubscriptionUrl() always read with CachedOrFetched.

Subscriber Attributes

Example: Complete Purchase Flow

public class PurchaseService
{
    private readonly IRevenueCatBilling _revenueCat;

    public PurchaseService(IRevenueCatBilling revenueCat)
    {
        _revenueCat = revenueCat;
    }

    public async Task<bool> PurchaseSubscription()
    {
        var offeringsResult = await _revenueCat.GetOfferings();
        var offerings = offeringsResult.Value;
        if (offeringsResult.IsError || offerings is null || !offerings.Any())
            return false;

        var defaultOffering = offerings.FirstOrDefault(o => o.IsCurrent);
        var monthlyPackage = defaultOffering?.AvailablePackages
            .FirstOrDefault(p => p.Identifier == "monthly");

        if (monthlyPackage == null)
            return false;

        var result = await _revenueCat.PurchaseProduct(monthlyPackage);

        if (result.IsSuccess)
        {
            // Purchase successful
            return true;
        }

        if (result.Error == PurchaseErrorStatus.PurchaseCancelledError)
        {
            // User cancelled - not an error
            return false;
        }

        // Handle other errors
        Console.WriteLine($"Purchase failed: {result.Error}");
        return false;
    }

    public async Task<bool> HasActiveSubscription(string entitlementId)
    {
        var customerInfoResult = await _revenueCat.GetCustomerInfo();
        return customerInfoResult.Value?.ActiveSubscriptions
            .Any(e => e == entitlementId) ?? false;
    }
}

Platform Support

Stub implementations return a successful result (IsSuccess == true, no Error) whose Value is an empty collection, an empty CustomerInfoDto, string.Empty for the storefront country code, or null for GetManagementSubscriptionUrl() and GetPurchaseDateForProductIdentifier(). This allows you to build and test on Windows without platform conditionals.

Error Handling

The library follows a non-throwing approach for runtime errors:

• Exceptions are thrown only for developer mistakes (e.g., calling methods before Initialize())
• Runtime errors (network issues, store problems, etc.) come back as a failed result

Every asynchronous member returns a named result DTO built on DataResult<TValue, PurchaseErrorStatus> from the Kebechet.Types.Result package, so they are all branched on the same way:

var restoreResult = await _revenueCat.RestoreTransactions();

if (restoreResult.IsSuccess)
{
    var activeSubscriptions = restoreResult.Value?.ActiveSubscriptions;
}
else
{
    Console.WriteLine($"Restore failed: {restoreResult.Error} {restoreResult.ErrorException?.Message}");
}

The result DTOs are thin named subclasses, so signatures stay readable and each type documents its own payload:

ErrorException.Message is platform-specific and may include the RevenueCat backend code and message (e.g. 7255 alias limit reached), but that is not guaranteed - branch on Error, log ErrorException.

Only PurchaseProduct() has a user-facing cancel. On every other member, PurchaseCancelledError means the CancellationToken you passed fired - not that the user cancelled anything.

Common Error Codes

See PurchaseErrorStatus for the complete list.

Credits

• Native bindings for Android and iOS inspired by thisisthekap's Xamarin bindings
• Abstraction layer based on RevenueCatXamarin by BillFulton

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for what the repository accepts and how to build and test a change.

License

This project is licensed under the MIT License.