DOCSEARCHbyAlgolia
Submit Docs

RevenueCat Capacitor SDK

repository·main·Indexed 42 days ago

https://github.com/revenuecat/purchases-capacitor

A cross-platform in-app purchase and subscription management system for Capacitor applications. The @revenuecat/purchases-capacitor plugin (v13.6.0) provides a wrapper around StoreKit and Google Play Billing to implement purchases, track subscription status, and manage entitlements. Includes an optional UI plugin, @revenuecat/purchases-capacitor-ui, for presenting paywalls and the customer center on iOS 15.0+ and Android 7.0+.

Tokens
40.9K
Snippets
114
Records
169
Agent score
53%

What's inside RevenueCat

  1. Overview of @revenuecat/purchases-capacitor

    main

    @revenuecat/purchases-capacitor is the client for the RevenueCat subscription and purchase tracking system. It acts as an open-source wrapper around StoreKit (iOS), Google Play Billing (Android), and the RevenueCat backend, specifically designed to make implementing in-app purchases within Capacitor applications straightforward.

    Key features include:

    • Server-side receipt validation: Ensures purchases are legitimate.
    • Subscription status tracking: Provides a unified way to know if a user is subscribed across iOS, Android, or web.
    • Webhooks: Enables server-to-server communication for events like renewals, cancellations, and purchases.
    • Analytics: Automatically calculates business metrics like MRR, conversion, and churn.
    • Integrations: Easily send purchase data to various third-party analytics and attribution tools.

  5. PurchasesOffering concept

    main
    An PurchasesOffering is a collection of PurchasesPackage objects available for a user to purchase. Offerings are used to group packages together, allowing you to change what products are displayed to users from the RevenueCat dashboard without updating your app code.

  6. Use SubscriptionOptions for Google Play offers

    main

    In V6, PurchasesStoreProduct supports multiple free trials and introductory offers via the Google Play BillingClient 5+ model.

    Automatic Selection

    When you call purchasePackage() or purchaseStoreProduct(), the SDK automatically selects a SubscriptionOption using this logic:

    1. Filters out offers with the rc-ignore-offer tag.
    2. Selects the SubscriptionOption with the longest free trial or cheapest first phase.
    3. Falls back to the base plan.

    Manual Selection

    To gain granular control over which offer a user receives, use the purchaseSubscriptionOption method with a specific SubscriptionOption from the product's subscriptionOptions array.

    Accessing Options

    You can inspect available options on a PurchasesStoreProduct instance:

    • defaultOption: The automatically selected option (longest free trial or cheapest intro).
    • subscriptionOptions: An array of all available SubscriptionOptions.
    • basePlan: Filter subscriptionOptions where option.isBasePlan is true.
    • freeOffer: Filter subscriptionOptions where option.freePhase is truthy.
    • trialOffer: Filter subscriptionOptions where option.introPhase is truthy.
    const basePlan = storeProduct.subscriptionOptions?.filter((option) => { option.isBasePlan });
const defaultOption = storeProduct.defaultOption
const freeOffer = storeProduct.subscriptionOptions?.filter((option) => { !!option.freePhase });
const trialOffer = storeProduct.subscriptionOptions?.filter((option) => { !!option.introPhase });

  7. Use the `e2e_test_flow` launch argument to jump to specific screens

    main

    To bypass the standard UI and jump directly to a specific test screen, pass the e2e_test_flow argument via Maestro's launchApp.arguments. If the argument is missing or unrecognized, the app defaults to the "Test Cases" list.

    Example Maestro YAML configuration:

    - launchApp:
    arguments:
        e2e_test_flow: purchase_through_paywall

  11. Perform a Hotfix Release for an Older Version

    main

    If you need to release a patch for a version that is not the current main branch (e.g., releasing 3.9.1 when the current version is 4.0.0), follow this workflow:

    1. Prepare Fix: Open a PR with the fix and merge it into main.
    2. Create Release Base: Navigate to the tag of the version you are patching (e.g., 3.9.0) and create a new branch named release/3.9.0. Push this branch to the remote.
    3. Bump Version: Run bundle exec fastlane bump. This creates a new PR (e.g., release/3.9.1). Crucially, ensure the PR's base branch is set to your release base branch (release/3.9.0) instead of main.
    4. Cherry-pick Fix: While on the new release branch (release/3.9.1), cherry-pick the fix from main: git cherry-pick <sha_of_the_squashed_commit_in_main> Resolve any conflicts, then push the commit to the remote.
    5. Tagging: Once the PR is approved, CircleCI should tag the release. If the wait-for-pr-approval job does not exist for this older version, manually tag the last commit in the release branch with the new version number (e.g., 3.9.1) and push.
    6. Cleanup: After the release is complete, merge the PR and delete both the release/3.9.0 and release/3.9.1 branches.
    7. Reset NPM Tag: Because the hotfix overrides the latest tag on npm, you must manually reset it to the actual latest version: npm dist-tag add @revenuecat/purchases-capacitor@x.x.x latest (where x.x.x is the current stable version).
    8. Update Changelog: Manually edit CHANGELOG.md in main to include the hotfix version.
    # 1. Create base branch from old version
git checkout -b release/3.9.0 3.9.0
git push origin release/3.9.0

# 2. Bump version (ensure base is release/3.9.0)
bundle exec fastlane bump

# 3. Cherry-pick fix from main
git checkout release/3.9.1
git cherry-pick <sha_of_fix>
git push origin release/3.9.1

# 4. Reset npm latest tag after release
npm dist-tag add @revenuecat/purchases-capacitor@4.0.0 latest

  12. Install @revenuecat/purchases-capacitor

    main

    To use the RevenueCat SDK in your Capacitor project, install the package via npm and then synchronize your Capacitor project to apply the native changes.

    Follow these steps:

    1. Install the npm package.
    2. Run the Capacitor sync command.
    npm install @revenuecat/purchases-capacitor
npx cap sync