DOCSEARCHbyAlgolia
Submit Docs

RevenueCat purchases-ios

repository·main·Indexed 25 days ago

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

SDK and server for implementing subscriptions and in-app purchases on iOS. Includes the RevenueCatAdMob adapter for tracking Google AdMob ad events (Loaded, Displayed, Opened, Revenue, and Failed to Load) across formats like Banner, Interstitial, App Open, Rewarded, and Native ads. The adapter utilizes experimental Swift SPI for iOS 15.0+ and provides loadAndTrack methods to map AdMob callbacks to the RevenueCat Dashboard.

Tokens
16K
Snippets
39
Records
103
Agent score
81%

What's inside purchases-ios

  1. Overview of RevenueCat SDK

    main

    RevenueCat is an in-app purchase server and SDK wrapper for StoreKit and Google Play Billing. It provides cross-platform support (iOS, tvOS, macOS, and watchOS) to simplify implementing in-app purchases and subscriptions.

    Key features include:

    • Server-side receipt validation.
    • Subscription status tracking across platforms (iOS, Android, Web).
    • Remote product configuration via the RevenueCat dashboard.
    • Real-time event notifications via webhooks.
    • Automatic calculation of business metrics like MRR, churn, and conversion.
    • Integrations with various analytics and attribution tools.

  4. Use Custom Entitlements Computation mode

    main

    Custom Entitlements Computation mode is a special behavior mode for the RevenueCat SDK intended for apps that perform their own entitlement computation separately from RevenueCat.

    Key behaviors in this mode:

    • RevenueCat will not generate anonymous user IDs.
    • The customerInfo cache will not refresh automatically when a purchase occurs; apps must rely on webhooks to signal their backends to refresh entitlements.
    • Most SDK methods are disallowed except for configuration, switching users, getting offerings, and making purchases.
    • The SDK should only be configured once the initial appUserID is known.

    Important Setup Requirements:

    • Contact RevenueCat support before enabling this mode.
    • In the RevenueCat Dashboard, it is highly recommended to set Transfer Behavior to Keep with original App User ID.

  5. Update Framework and Import References

    main

    The framework name has changed from Purchases to RevenueCat. You must update your import statements and dependency managers.

    Swift Imports

    Replace import Purchases with import RevenueCat.

    Objective-C Imports

    Replace @import Purchases; with @import RevenueCat;.

    Dependency Manager Updates

    Swift Package Manager

    In Xcode, go to Build Phases -> Link Binary with Libraries. Remove the reference to Purchases and add RevenueCat.

    CocoaPods

    Update your Podfile:

    # Before
pod 'Purchases'

# After
pod 'RevenueCat'

    Carthage

    • Using XCFrameworks (Recommended): In Build Phases, update both Link Binary with Libraries and Embed Frameworks to reference RevenueCat instead of Purchases.
    • Using Platform-specific frameworks: Update Link Binary with Libraries to use RevenueCat.framework. Additionally, update your input.xcfilelist and output.xcfilelist in the Carthage Run Script phase, replacing Purchases.framework with RevenueCat.framework.

  6. Regenerate RC Container v1 fixtures

    main

    If you have made intentional changes to fixtures, wire-compatibility, or are introducing a new major version of the RC Container format, you can regenerate the .bin files located in Tests/UnitTests/Networking/Responses/Fixtures/RCContainer.

    To regenerate them:

    1. Run only the test UnitTests/RCContainerBackwardsCompatibilityTests/testGenerateFixtures.
    2. Set the environment variable GENERATE_RC_CONTAINER_FIXTURES=1 for the test runner.

    If using xcodebuildmcp, use the same focused XCTest identifier and pass GENERATE_RC_CONTAINER_FIXTURES=1 in testRunnerEnv. You can also use TEST_RUNNER_GENERATE_RC_CONTAINER_FIXTURES=1 which is the environment name exposed by xcodebuildmcp.

    After regeneration, run the focused RC Container tests and review the binary diffs before committing.

  7. Run the Magic Weather Sample App

    main

    The Magic Weather sample app demonstrates how to use the RevenueCat Purchases SDK. To run the sample, follow these steps:

    1. Clone the repository:
      git clone https://github.com/RevenueCat/purchases-ios.git
    2. Open the project: Navigate to the Examples directory and open MagicWeather.xcodeproj in Xcode.
    3. Configure Bundle ID: In the project's General tab, update the Bundle Identifier to match your App Store Connect and RevenueCat bundle ID.
    4. Configure Signing: In the Signing & Capabilities tab, select your development team.
    5. Configure Constants: Open Constants.swift and update the following:
      • apiKey: Replace with your RevenueCat project API key.
      • entitlementID: Replace with your RevenueCat entitlement ID.
      • Comment out any error directives.
    6. Run: Build and run the app on a physical device.

  8. Migrate from RevenueCat v4 to v5

    main

    Upgrading to version 5.0 introduces several breaking changes and architectural shifts, most notably the default enablement of StoreKit 2 and the replacement of 'Observer Mode' with PurchasesAreCompletedBy.

    Key Migration Steps:

    1. Configure In-App Purchase Key: You must configure your In-App Purchase Key in the RevenueCat dashboard. Purchases will fail without this.
    2. Update StoreKit 2 Configuration: The deprecated .with(usesStoreKit2IfAvailable: true) option has been removed. The SDK now uses StoreKit 2 by default.
    3. Replace Observer Mode: The observerMode: true configuration is deprecated. It is replaced by purchasesAreCompletedBy and storeKitVersion.
    4. Update Deployment Targets: Ensure your app meets the new minimum requirements:
      • iOS 13.0
      • tvOS 13.0
      • watchOS 6.2
      • macOS 10.15
    5. Switch to .xcframeworks: Pre-built .frameworks are no longer included; use .xcframeworks instead.

  12. Use the Experimental Swift API for RevenueCat AdMob

    main

    The RevenueCat AdMob adapter currently uses an experimental surface. To use the Swift API, you must explicitly import the experimental SPI and ensure your target is iOS 15.0 or higher.

    Requirements:

    • iOS 15.0+ (@available(iOS 15.0, *))
    • Use @_spi(Experimental) import RevenueCatAdMob

    Warning: The API shape is subject to change. It is recommended to pin to a known-good version during initial rollout and review release notes when upgrading.

    @available(iOS 15.0, *) 
@_spi(Experimental) import RevenueCatAdMob

// Use the experimental APIs here