===============
LIBRARY RULES
===============
From library maintainers:
- Add `implementation("app.revenuedot.purchases:purchases:<version>")` from Maven Central, plus `app.revenuedot.purchases:purchases-ui` for paywalls. The artifact ids are the same as RevenueCat's.
- Kotlin packages stay `com.revenuecat.purchases.*`, so imports such as `import com.revenuecat.purchases.Purchases` do not change.
- RevenueDot Cloud (https://api.revenuedot.app) is the default API host. For a self-hosted server, set `Purchases.proxyURL = URL("https://revenuedot.example.com")` before `Purchases.configure`.
- Pass the app's public key from the RevenueDot dashboard (it starts with goog_) to `PurchasesConfiguration.Builder`.

### Set up development environment with fastlane

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/CONTRIBUTING.md

Run this command in the project root after installing and activating mise to set up the development environment. It links the pre-commit hook that runs detekt.

```bash
bundle exec fastlane setup_dev
```

--------------------------------

### AppOpenAdPreloaderExtensionsKt.startAndTrack

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/feature/admob-next-gen/api.txt

Starts preloading an app open ad and tracks its impression.

```APIDOC
## startAndTrack

### Description
Starts preloading an app open ad and tracks its impression.

### Method
startAndTrack

### Signature
public static boolean startAndTrack(AppOpenAdPreloader.Companion, String preloadId, PreloadConfiguration preloadConfiguration, String? placement, PreloadCallback? preloadCallback)

### Parameters
- **companion** (AppOpenAdPreloader.Companion) - Required - The companion object of AppOpenAdPreloader.
- **preloadId** (String) - Required - The preload ID.
- **preloadConfiguration** (PreloadConfiguration) - Required - The preload configuration.
- **placement** (String?) - Optional - The placement identifier for tracking.
- **preloadCallback** (PreloadCallback?) - Optional - Callback for preload events.

### Returns
boolean - True if the preload started successfully, false otherwise.
```

--------------------------------

### Preloading pattern: startAndTrack and pollAndTrackAd for interstitial

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/feature/admob-next-gen/docs/advanced-loading.md

Two-stage preloading example for interstitial ads. `startAndTrack` begins buffering, and `pollAndTrackAd` later adopts a buffered ad. Polling does not emit another loaded event. The placements passed to each method are independent.

```kotlin
val preloadConfiguration = PreloadConfiguration(
    request = AdRequest.Builder("AD_UNIT_ID").build(),
    bufferSize = 2,
)

InterstitialAdPreloader.startAndTrack(
    preloadId = "game-interstitial-buffer",
    preloadConfiguration = preloadConfiguration,
    placement = "game_interstitial_preload",
    preloadCallback = object : PreloadCallback {},
)

// Later, adopt a buffered ad. Polling does not emit another loaded event.
interstitialAd = InterstitialAdPreloader.pollAndTrackAd(
    preloadId = "game-interstitial-buffer",
    placement = "game_interstitial",
    adEventCallback = interstitialAdEventCallback,
)

interstitialAd?.show(this)
```

--------------------------------

### PaywallActivityLauncher

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/ui/revenuecatui/api.txt

Launcher class for starting a paywall activity with configurable options.

```APIDOC
## PaywallActivityLauncher

### Description
Launcher for starting a paywall activity with configurable options.

### Constructor
`PaywallActivityLauncher(ActivityResultCaller resultCaller, PaywallResultHandler resultHandler)`

### Methods
- `launch()`: Launches the paywall activity with default options.
- `launch(Offering? offering)`: Launches with a specific offering.
- `launch(Offering? offering, ParcelizableFontProvider? fontProvider)`: Launches with offering and font provider.

### Parameters
- `resultCaller` (ActivityResultCaller) - Required - The activity result caller.
- `resultHandler` (PaywallResultHandler) - Required - Handler for paywall results.
- `offering` (Offering?) - Optional - Offering to display.
- `fontProvider` (ParcelizableFontProvider?) - Optional - Font provider for the paywall.
```

--------------------------------

### Access installment plan details with SubscriptionOption.installmentsInfo

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/migrations/v8-MIGRATION.md

Use this snippet to retrieve installment plan details from the SDK. It calls awaitOfferings() and accesses the monthly product's default option's installmentsInfo property. This provides the number of installments the customer commits to and the number upon renewal.

```kotlin
val offerings = purchases.awaitOfferings()
// This provides the number of installments the customer commits to, and the number of installments they commit to upon a renewal.
val installmentsInfo = offerings.current?.monthly?.product?.defaultOption?.installmentsInfo
```

--------------------------------

### GET /purchases/cached-virtual-currencies

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/purchases/api-defauts.txt

Gets the cached virtual currencies.

```APIDOC
## [GET] /purchases/cached-virtual-currencies

### Description
Gets the cached virtual currencies.

### Method
GET

### Endpoint
/purchases/cached-virtual-currencies

### Response
#### Success Response (200)
- **virtualCurrencies** (VirtualCurrencies?) - The cached virtual currencies.

#### Response Example
```json
{
  "virtualCurrencies": "VirtualCurrencies"
}
```
```

--------------------------------

### PresentedOfferingContext.TargetingContext

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/purchases/api-entitlement.txt

Documentation for the TargetingContext class, including its constructor, properties, and methods.

```APIDOC
## PresentedOfferingContext.TargetingContext

### Description
Represents the targeting context within a presented offering.

### Constructors
- **TargetingContext(int revision, String ruleId)**

### Properties
- **revision** (int) - The revision number.
- **ruleId** (String) - The rule identifier.

### Methods
- **getRevision()** (int) - Returns the revision number.
- **getRuleId()** (String) - Returns the rule identifier.
```

--------------------------------

### GET /purchases/app-user-id

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/purchases/api-defauts.txt

Gets the app user ID.

```APIDOC
## [GET] /purchases/app-user-id

### Description
Gets the app user ID.

### Method
GET

### Endpoint
/purchases/app-user-id

### Response
#### Success Response (200)
- **appUserID** (String) - The app user ID.

#### Response Example
```json
{
  "appUserID": "string"
}
```
```

--------------------------------

### GET /purchases/amazon-lwa-consent-status

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/purchases/api-defauts.txt

Gets the Amazon LWA consent status.

```APIDOC
## [GET] /purchases/amazon-lwa-consent-status

### Description
Gets the Amazon LWA consent status.

### Method
GET

### Endpoint
/purchases/amazon-lwa-consent-status

### Parameters
#### Query Parameters
- **callback** (GetAmazonLWAConsentStatusCallback) - Required - The callback to receive the status.

### Request Example
```json
{
  "callback": "GetAmazonLWAConsentStatusCallback"
}
```

### Response
#### Success Response (200)
- **callback** (GetAmazonLWAConsentStatusCallback) - The callback with the status.
```

--------------------------------

### GET /purchases/allow-sharing-play-store-account

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/purchases/api-defauts.txt

Gets whether sharing the Play Store account is allowed.

```APIDOC
## [GET] /purchases/allow-sharing-play-store-account

### Description
Gets whether sharing the Play Store account is allowed.

### Method
GET

### Endpoint
/purchases/allow-sharing-play-store-account

### Response
#### Success Response (200)
- **allowSharingPlayStoreAccount** (Boolean) - Whether sharing is allowed.

#### Response Example
```json
{
  "allowSharingPlayStoreAccount": true
}
```
```

--------------------------------

### PresentedOfferingContext

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/purchases/api-entitlement.txt

Documentation for the PresentedOfferingContext class, including constructors, properties, and methods.

```APIDOC
## PresentedOfferingContext

### Description
Represents the context in which an offering was presented to the user.

### Constructors
- **PresentedOfferingContext(String offeringIdentifier)**
- **PresentedOfferingContext(String offeringIdentifier, String? placementIdentifier, TargetingContext? targetingContext)**

### Properties
- **offeringIdentifier** (String) - The identifier of the offering.
- **placementIdentifier** (String?) - The placement identifier, if any.
- **targetingContext** (TargetingContext?) - The targeting context, if any.

### Methods
- **getOfferingIdentifier()** (String) - Returns the offering identifier.
- **getPlacementIdentifier()** (String?) - Returns the placement identifier.
- **getTargetingContext()** (TargetingContext?) - Returns the targeting context.
```

--------------------------------

### GET /purchases/can-make-payments

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/purchases/api-defauts.txt

Checks if the user can make payments.

```APIDOC
## [GET] /purchases/can-make-payments

### Description
Checks if the user can make payments.

### Method
GET

### Endpoint
/purchases/can-make-payments

### Parameters
#### Query Parameters
- **context** (Context) - Required - The application context.
- **features** (List<BillingFeature>) - Optional - The billing features to check.

### Request Example
```json
{
  "context": "Context",
  "features": ["BillingFeature"]
}
```

### Response
#### Success Response (200)
- **callback** (Callback<Boolean>) - The callback with the result.

#### Response Example
```json
{
  "callback": "Callback<Boolean>"
}
```
```

--------------------------------

### POST /purchases/configure

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/purchases/api-defauts.txt

Configures the purchases instance.

```APIDOC
## [POST] /purchases/configure

### Description
Configures the purchases instance.

### Method
POST

### Endpoint
/purchases/configure

### Parameters
#### Request Body
- **configuration** (PurchasesConfiguration) - Required - The configuration to use.

### Request Example
```json
{
  "configuration": "PurchasesConfiguration"
}
```

### Response
#### Success Response (200)
- **purchases** (Purchases) - The configured purchases instance.

#### Response Example
```json
{
  "purchases": "Purchases"
}
```
```

--------------------------------

### Offering

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/purchases/api-entitlement.txt

Documentation for the Offering class, including constructors, properties, and methods.

```APIDOC
## Offering

### Description
Represents an offering configured in RevenueCat, containing a list of available packages and metadata.

### Constructor
`Offering(String identifier, String serverDescription, Map<String, ?> metadata, List<Package> availablePackages)`

`Offering(String identifier, String serverDescription, Map<String, ?> metadata, List<Package> availablePackages, PaywallData? paywall, Offering.PaywallComponents? paywallComponents, URL? webCheckoutURL)`

### Properties
- **identifier** (String) - The unique identifier of the offering.
- **serverDescription** (String) - Description of the offering from the RevenueCat dashboard.
- **metadata** (Map<String, Object>) - Additional metadata associated with the offering.
- **availablePackages** (List<Package>) - List of packages available in this offering.
- **annual** (Package?) - The annual package, if available.
- **lifetime** (Package?) - The lifetime package, if available.
- **monthly** (Package?) - The monthly package, if available.
- **sixMonth** (Package?) - The six-month package, if available.
- **threeMonth** (Package?) - The three-month package, if available.
- **twoMonth** (Package?) - The two-month package, if available.
- **weekly** (Package?) - The weekly package, if available.
- **webCheckoutURL** (URL?) - The web checkout URL, if available.
- **hasPaywall** (boolean) - Whether the offering has a paywall.

### Methods
- `Package get(String s)` - Returns the package with the given identifier.
- `Package? getAnnual()` - Returns the annual package, or null if not available.
- `List<Package> getAvailablePackages()` - Returns the list of available packages.
- `String getIdentifier()` - Returns the offering identifier.
- `Package? getLifetime()` - Returns the lifetime package, or null if not available.
- `Map<String, Object> getMetadata()` - Returns the metadata map.
- `String getMetadataString(String key, String default)` - Returns the metadata value as a string, or the default if not found.
- `Package? getMonthly()` - Returns the monthly package, or null if not available.
- `Package getPackage(String identifier)` - Returns the package with the given identifier, throwing `NoSuchElementException` if not found.
- `String getServerDescription()` - Returns the server description.
- `Package? getSixMonth()` - Returns the six-month package, or null if not available.
- `Package? getThreeMonth()` - Returns the three-month package, or null if not available.
- `Package? getTwoMonth()` - Returns the two-month package, or null if not available.
- `URL? getWebCheckoutURL()` - Returns the web checkout URL, or null if not available.
- `Package? getWeekly()` - Returns the weekly package, or null if not available.
- `boolean hasPaywall()` - Returns whether the offering has a paywall.

```

--------------------------------

### awaitStorefrontCountryCode

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/purchases/api-entitlement.txt

Coroutine extension to get the storefront country code.

```APIDOC
## awaitStorefrontCountryCode

### Description
Fetches the storefront country code asynchronously.

### Method
suspend fun

### Signature
```kotlin
suspend fun Purchases.awaitStorefrontCountryCode(): String
```

### Returns
- **String** - The storefront country code.
```

--------------------------------

### setTenjinAnalyticsInstallationID(String?)

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/purchases/api-defauts.txt

Sets the Tenjin analytics installation ID.

```APIDOC
## setTenjinAnalyticsInstallationID(String?)

### Description
Sets the Tenjin analytics installation ID for attribution.

### Method
setTenjinAnalyticsInstallationID

### Signature
public void setTenjinAnalyticsInstallationID(String? tenjinAnalyticsInstallationID)

### Parameters
- **tenjinAnalyticsInstallationID** (String?) - Optional - The Tenjin analytics installation ID.
```

--------------------------------

### configure

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/purchases/api-defauts.txt

Configures the RevenueCat SDK.

```APIDOC
## configure(PurchasesConfiguration configuration)

### Description
Configures the RevenueCat SDK with the provided configuration.

### Method
configure

### Parameters
- **configuration** (PurchasesConfiguration) - Required - The configuration object.
```

--------------------------------

### Load and track an app open ad with RevenueCat

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/feature/admob-next-gen/README.md

Loads an app open ad with RevenueCat tracking. Uses Purchases.sharedInstance.adTracker.loadAndTrackAppOpenAd with a placement and callbacks. The adEventCallback is set for tracking. Later, show() can optionally override the placement.

```kotlin
val adRequest = AdRequest.Builder("AD_UNIT_ID").build()

Purchases.sharedInstance.adTracker.loadAndTrackAppOpenAd(
    adRequest = adRequest,
    placement = "app_start",
    loadCallback = object : AdLoadCallback<AppOpenAd> {
        override fun onAdLoaded(ad: AppOpenAd) {
            appOpenAd = ad
        }

        override fun onAdFailedToLoad(adError: LoadAdError) {
            appOpenAd = null
        }
    },
    adEventCallback = appOpenAdEventCallback,
)

// Later, optionally override the load-time placement:
appOpenAd?.show(this, placement = "resume_from_background")
```

--------------------------------

### Access SubscriptionOptions from StoreProduct

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/migrations/v6-MIGRATION.md

Access the base plan, default offer, free trial, intro offer, and offers with a specific tag from a StoreProduct's subscriptionOptions. Use this when you need more control than the defaultOption property provides.

```kotlin
val basePlan = storeProduct.subscriptionOptions?.basePlan
val defaultOffer = storeProduct.subscriptionOptions?.defaultOffer
val freeOffer = storeProduct.subscriptionOptions?.freeTrial
val introOffer = storeProduct.subscriptionOptions?.introOffer
val offersForLapsedCustomers = storeProduct.subscriptionOptions?.withTag("lapsed-customers")
```

--------------------------------

### PaywallActivityLaunchOptions.Builder

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/ui/revenuecatui/api.txt

Builder class for configuring options to launch a paywall activity.

```APIDOC
## PaywallActivityLaunchOptions.Builder

### Description
Builder for configuring options to launch a paywall activity.

### Constructor
`PaywallActivityLaunchOptions.Builder()`

### Methods
- `build()`: Returns `PaywallActivityLaunchOptions`.
- `setCustomVariables(Map<String, ? extends CustomVariableValue> customVariables)`: Sets custom variables.
- `setEdgeToEdge(boolean edgeToEdge)`: Sets edge-to-edge mode.
- `setFontProvider(ParcelizableFontProvider? fontProvider)`: Sets font provider.
- `setListener(PaywallListener? listener)`: Sets paywall listener (experimental).
- `setOffering(Offering? offering)`: Sets offering.
- `setPurchaseLogic(PaywallPurchaseLogic? purchaseLogic)`: Sets purchase logic (experimental).
- `setShouldDisplayDismissButton(boolean shouldDisplayDismissButton)`: Sets whether to display dismiss button.

### Parameters
- `customVariables` (Map<String, ? extends CustomVariableValue>) - Optional - Custom variables for the paywall.
- `edgeToEdge` (boolean) - Optional - Whether to use edge-to-edge display.
- `fontProvider` (ParcelizableFontProvider?) - Optional - Font provider for the paywall.
- `listener` (PaywallListener?) - Optional - Listener for paywall events.
- `offering` (Offering?) - Optional - Offering to display.
- `purchaseLogic` (PaywallPurchaseLogic?) - Optional - Custom purchase logic.
- `shouldDisplayDismissButton` (boolean) - Optional - Whether to show dismiss button.

### Returns
- `PaywallActivityLaunchOptions` - The built options.
```

--------------------------------

### Show a rewarded interstitial ad with reward verification

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/feature/admob-next-gen/README.md

Shows a RewardedInterstitialAd using the verification-aware show overload with callbacks for verification start and completion. Assumes enableRewardVerification() was called on the loaded ad.

```kotlin
rewardedInterstitialAd?.show(
    activity = this,
    placement = "bonus_chest",
    rewardVerificationStarted = { /* Verification polling has started. */ },
    rewardVerificationCompleted = { result -> /* Handle the verification result. */ },
)
```

--------------------------------

### awaitOfferings

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/purchases/api-defauts.txt

Coroutine extension to fetch offerings.

```APIDOC
## awaitOfferings

### Description
Asynchronously fetches the current offerings.

### Method
suspend fun

### Signature
`awaitOfferings(): Offerings`

### Parameters
- None.

### Returns
- **Offerings** - The current offerings.

### Throws
- **PurchasesException** - If the operation fails.
```

--------------------------------

### Trigger CircleCI pipeline with action=bump

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/RELEASING.md

Triggers the CircleCI pipeline to start an automatic release by passing the action parameter 'bump'. Requires a CircleCI personal token and targets the main branch.

```bash
curl --location --request POST 'https://circleci.com/api/v2/project/github/RevenueCat/purchases-android/pipeline' \
            --header 'Content-Type: application/json' \
            -u "your_circleci_personal_token:" \
            -d '{
              "branch": "main",
              "parameters": {
                "action": "bump"
              }
            }'
```

--------------------------------

### setUpdatedCustomerInfoListener(UpdatedCustomerInfoListener?)

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/purchases/api-entitlement.txt

Sets the updated customer info listener.

```APIDOC
## setUpdatedCustomerInfoListener(UpdatedCustomerInfoListener?)

### Description
Sets the updated customer info listener.

### Method
setUpdatedCustomerInfoListener

### Parameters
- **listener** (com.revenuecat.purchases.interfaces.UpdatedCustomerInfoListener?) - Required - The listener to set.
```

--------------------------------

### Enable reward verification on a rewarded ad

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/feature/admob-next-gen/README.md

In the onAdLoaded callback, calls enableRewardVerification() on the loaded ad. Later, shows the ad using the verification-aware show overload with callbacks for verification start and completion.

```kotlin
override fun onAdLoaded(ad: RewardedAd) {
    rewardedAd = ad.apply {
        enableRewardVerification()
    }
}

// Later, to show:
rewardedAd?.show(
    activity = this,
    placement = "level_complete_reward",
    rewardVerificationStarted = {
        // Verification polling has started.
    },
    rewardVerificationCompleted = { result ->
        rewardedAd = null
        if (result.verifiedReward != null) {
            // Handle the verified reward.
        } else if (result.failed) {
            // Verification failed.
        }
    },
)
```

--------------------------------

### Suspending interstitial ad load with loadAndTrackInterstitialAd

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/feature/admob-next-gen/docs/advanced-loading.md

Suspending overload for interstitial ad loading. Returns Google's original result unchanged with event tracking installed on success. Use inside a coroutine scope.

```kotlin
lifecycleScope.launch {
    when (
        val result = Purchases.sharedInstance.adTracker.loadAndTrackInterstitialAd(
            adRequest = AdRequest.Builder("AD_UNIT_ID").build(),
            placement = "game_interstitial",
        )
    ) {
        is AdLoadResult.Success -> interstitialAd = result.ad
        is AdLoadResult.Failure -> interstitialAd = null
    }
}
```

--------------------------------

### awaitOfferings

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/purchases/api-entitlement.txt

Coroutine extension to fetch offerings, throwing on error.

```APIDOC
## awaitOfferings

### Description
Fetches offerings asynchronously and returns them, throwing a PurchasesException on failure.

### Method
suspend fun

### Signature
```kotlin
suspend fun Purchases.awaitOfferings(): Offerings
```

### Returns
- **Offerings** - The fetched offerings.

### Throws
- **PurchasesException** - If the operation fails.
```

--------------------------------

### awaitGetProducts

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/purchases/api-defauts.txt

Coroutine extension to fetch products.

```APIDOC
## awaitGetProducts

### Description
Asynchronously fetches products by their identifiers, optionally filtered by product type.

### Method
suspend fun

### Signature
`awaitGetProducts(productIds: List<String>, type: ProductType? = null): List<StoreProduct>`

### Parameters
- **productIds** (List<String>) - Required - List of product identifiers.
- **type** (ProductType?) - Optional - Product type filter.

### Returns
- **List<StoreProduct>** - The fetched products.

### Throws
- **PurchasesTransactionException** - If the operation fails.
```

--------------------------------

### Set tracking-safe ad event callback

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/feature/admob-next-gen/README.md

Use this setter to attach event callbacks to a loaded or polled ad. Assigning the ad's callback property directly would replace the tracking wrapper installed by the adapter.

```kotlin
ad.setTrackingAdEventCallback(adEventCallback)
```

--------------------------------

### Configure RevenueDot SDK with proxyURL and PurchasesConfiguration

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/README.md

Configure the RevenueDot SDK. Set Purchases.proxyURL only for self-hosted servers; RevenueDot Cloud is the default. The fork already trusts RevenueDot's signing key, so no signature or verification setting is needed. The app's public key (e.g., "goog_...") comes from the RevenueDot dashboard.

```kotlin
import com.revenuecat.purchases.Purchases
import com.revenuecat.purchases.PurchasesConfiguration
import java.net.URL

// Self-hosted server only: RevenueDot Cloud (https://api.revenuedot.app) is the default.
Purchases.proxyURL = URL("https://revenuedot.example.com")
Purchases.configure(PurchasesConfiguration.Builder(this, "goog_...").build())   // the app's public key from the RevenueDot dashboard
```

--------------------------------

### purchase(PurchaseParams, PurchaseCallback)

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/purchases/api-entitlement.txt

Initiates a purchase with the given parameters.

```APIDOC
## purchase(PurchaseParams, PurchaseCallback)

### Description
Initiates a purchase with the given parameters.

### Method
purchase

### Parameters
- **purchaseParams** (com.revenuecat.purchases.PurchaseParams) - Required - The purchase parameters.
- **callback** (com.revenuecat.purchases.interfaces.PurchaseCallback) - Required - Callback to receive the purchase result.

### Response
- **callback** - Provides the purchase result or an error.
```

--------------------------------

### Package

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/purchases/api-entitlement.txt

Documentation for the Package class, including constructors, properties, and methods.

```APIDOC
## Package

### Description
Represents a purchase package, which is a collection of a product and its metadata, such as the package type and the offering it was presented from.

### Constructors
- **Package(String identifier, PackageType packageType, StoreProduct product, PresentedOfferingContext presentedOfferingContext)**
- **Package(String identifier, PackageType packageType, StoreProduct product, PresentedOfferingContext presentedOfferingContext, URL? webCheckoutURL)**
- **@Deprecated Package(String identifier, PackageType packageType, StoreProduct product, String offering)**

### Properties
- **identifier** (String) - The identifier of the package.
- **packageType** (PackageType) - The type of the package.
- **product** (StoreProduct) - The product associated with the package.
- **presentedOfferingContext** (PresentedOfferingContext) - The context in which the offering was presented.
- **webCheckoutURL** (URL?) - The web checkout URL, if available.
- **@Deprecated offering** (String) - The offering identifier (deprecated).

### Methods
- **getIdentifier()** (String) - Returns the package identifier.
- **getPackageType()** (PackageType) - Returns the package type.
- **getProduct()** (StoreProduct) - Returns the product.
- **getPresentedOfferingContext()** (PresentedOfferingContext) - Returns the presented offering context.
- **getWebCheckoutURL()** (URL?) - Returns the web checkout URL.
- **@Deprecated getOffering()** (String) - Returns the offering identifier (deprecated).
```

--------------------------------

### PurchasesConfiguration

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/purchases/api-defauts.txt

Documentation for the PurchasesConfiguration class, including its constructor, properties, and getter methods.

```APIDOC
## PurchasesConfiguration

### Description
Configuration class for the Purchases SDK. It holds all the settings needed to initialize the SDK, such as API key, app user ID, and various feature flags.

### Constructor
`PurchasesConfiguration(com.revenuecat.purchases.PurchasesConfiguration.Builder builder)`

### Properties
- **apiKey** (String) - The API key for the RevenueCat project.
- **appUserID** (String?) - The app user ID. Optional.
- **automaticDeviceIdentifierCollectionEnabled** (boolean) - Whether automatic device identifier collection is enabled.
- **context** (android.content.Context) - The Android context.
- **dangerousSettings** (com.revenuecat.purchases.DangerousSettings) - Dangerous settings.
- **diagnosticsEnabled** (boolean) - Whether diagnostics are enabled.
- **galaxyBillingMode** (com.revenuecat.purchases.galaxy.GalaxyBillingMode) - The Galaxy billing mode.
- **observerMode** (boolean) - Deprecated. Whether observer mode is enabled.
- **pendingTransactionsForPrepaidPlansEnabled** (boolean) - Whether pending transactions for prepaid plans are enabled.
- **preferredUILocaleOverride** (String?) - The preferred UI locale override. Optional.
- **purchasesAreCompletedBy** (com.revenuecat.purchases.PurchasesAreCompletedBy) - Who completes purchases.
- **service** (java.util.concurrent.ExecutorService?) - The executor service. Optional.
- **showInAppMessagesAutomatically** (boolean) - Whether to show in-app messages automatically.
- **store** (com.revenuecat.purchases.Store) - The store.
- **verificationMode** (com.revenuecat.purchases.EntitlementVerificationMode) - The entitlement verification mode.

### Methods
- **getApiKey()** (String) - Returns the API key.
- **getAppUserID()** (String?) - Returns the app user ID.
- **getAutomaticDeviceIdentifierCollectionEnabled()** (boolean) - Returns whether automatic device identifier collection is enabled.
- **getContext()** (android.content.Context) - Returns the context.
- **getDangerousSettings()** (com.revenuecat.purchases.DangerousSettings) - Returns the dangerous settings.
- **getDiagnosticsEnabled()** (boolean) - Returns whether diagnostics are enabled.
- **getGalaxyBillingMode()** (com.revenuecat.purchases.galaxy.GalaxyBillingMode) - Returns the Galaxy billing mode.
- **getObserverMode()** (boolean) - Deprecated. Returns whether observer mode is enabled.
- **getPendingTransactionsForPrepaidPlansEnabled()** (boolean) - Returns whether pending transactions for prepaid plans are enabled.
- **getPreferredUILocaleOverride()** (String?) - Returns the preferred UI locale override.
- **getPurchasesAreCompletedBy()** (com.revenuecat.purchases.PurchasesAreCompletedBy) - Returns who completes purchases.
- **getService()** (java.util.concurrent.ExecutorService?) - Returns the executor service.
- **getShowInAppMessagesAutomatically()** (boolean) - Returns whether to show in-app messages automatically.
- **getStore()** (com.revenuecat.purchases.Store) - Returns the store.
- **getVerificationMode()** (com.revenuecat.purchases.EntitlementVerificationMode) - Returns the entitlement verification mode.
```

--------------------------------

### OriginalTemplatePaywallFooterView

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/ui/revenuecatui/api.txt

Documentation for the OriginalTemplatePaywallFooterView class, including constructors and methods.

```APIDOC
## OriginalTemplatePaywallFooterView

### Description
A view that displays the original template paywall footer. It can be embedded in an Android layout and configured with an offering, listener, font provider, and other options.

### Constructors
- `OriginalTemplatePaywallFooterView(Context context)`
- `OriginalTemplatePaywallFooterView(Context context, AttributeSet? attrs)`
- `OriginalTemplatePaywallFooterView(Context context, AttributeSet? attrs, int defStyleAttr)`
- `OriginalTemplatePaywallFooterView(Context context, Offering? offering)`
- `OriginalTemplatePaywallFooterView(Context context, Offering? offering, PaywallListener? listener)`
- `OriginalTemplatePaywallFooterView(Context context, Offering? offering, PaywallListener? listener, FontProvider? fontProvider)`
- `OriginalTemplatePaywallFooterView(Context context, Offering? offering, PaywallListener? listener, FontProvider? fontProvider, boolean condensed)`
- `OriginalTemplatePaywallFooterView(Context context, Offering? offering, PaywallListener? listener, FontProvider? fontProvider, boolean condensed, Function0<Unit>? dismissHandler)`

### Methods
- `setDismissHandler(Function0<Unit>? dismissHandler)` - Sets a handler invoked when the view is dismissed.
- `setFontProvider(FontProvider? fontProvider)` - Sets the font provider for the view.
- `setOfferingId(String? offeringId)` - Deprecated. Sets the offering ID.
- `setPaywallListener(PaywallListener? listener)` - Sets the paywall listener.

```

--------------------------------

### awaitGetProducts

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/purchases/api-entitlement.txt

Coroutine extension to fetch products, throwing on error.

```APIDOC
## awaitGetProducts

### Description
Fetches products asynchronously and returns them, throwing a PurchasesTransactionException on failure.

### Method
suspend fun

### Signature
```kotlin
suspend fun Purchases.awaitGetProducts(productIds: List<String>, type: ProductType? = null): List<StoreProduct>
```

### Parameters
- **productIds** (List<String>) - Required - The product identifiers to fetch.
- **type** (ProductType?) - Optional - The product type to filter by.

### Returns
- **List<StoreProduct>** - The fetched products.

### Throws
- **PurchasesTransactionException** - If the operation fails.
```

--------------------------------

### Build and Test Commands

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/AGENTS.md

Common Gradle commands for building, unit testing, and running instrumentation/integration tests. Backend integration tests require API keys in local.properties and self-skip if not set. Flavor format for module tests is {apis}{buildType}.

```bash
# Build all modules
./gradlew build

# Run unit tests
./gradlew test

# Run only backend integration tests
# (requires BACKEND_INTEGRATION_API_KEY and BACKEND_INTEGRATION_LOAD_SHEDDER_API_KEY in local.properties; tests self-skip if not set)
./gradlew :purchases:testDefaultsDebugUnitTest --tests "com.revenuecat.purchases.backend_integration_tests.*"

# Run unit tests for specific modules (flavor format: {apis}{buildType})
./gradlew :purchases:testDefaultsDebugUnitTest
./gradlew :purchases:testCustomEntitlementComputationDebugUnitTest
./gradlew :ui:revenuecatui:testDefaultsDebugUnitTest

# Run Android instrumentation tests
./gradlew connectedAndroidTest

# Run instrumentation tests for specific modules
./gradlew :purchases:connectedDefaultsDebugAndroidTest
./gradlew :ui:revenuecatui:connectedDefaultsDebugAndroidTest

# Run integration tests (requires device/emulator)
./gradlew :integration-tests:connectedDebugAndroidTest
```

--------------------------------

### Load and track app open ad with RevenueCat

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/feature/admob/README.md

Loads an app open ad with RevenueCat tracking. Pass the fullScreenContentCallback to the load method, not to the ad object later, to preserve impression and click tracking. The placement parameter is used for RevenueCat analytics.

```kotlin
Purchases.sharedInstance.adTracker.loadAndTrackAppOpenAd(
    context = context,
    adUnitId = "AD_UNIT_ID",
    adRequest = AdRequest.Builder().build(),
    placement = "app_launch",
    loadCallback = object : AppOpenAdLoadCallback() {
        override fun onAdLoaded(ad: AppOpenAd) {
            appOpenAd = ad
        }
        override fun onAdFailedToLoad(loadAdError: LoadAdError) {
            // Handle error.
        }
    },
    // ⚠️ Pass fullScreenContentCallback here — not on the ad object later.
    // The adapter wraps it with tracking; assigning ad.fullScreenContentCallback
    // afterward replaces the wrapper and breaks impression/click tracking.
    fullScreenContentCallback = object : FullScreenContentCallback() {
        override fun onAdDismissedFullScreenContent() { appOpenAd = null }
    },
)

// Later, to show (unchanged):
appOpenAd?.show(activity)
```

--------------------------------

### Add dependencies using RevenueCat BOM

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/feature/admob-next-gen/README.md

Uses the RevenueCat BOM to manage the adapter version, requiring only the platform dependency and the artifact names without versions.

```kotlin
val revenueCatVersion = "<version>"

dependencies {
    implementation(platform("com.revenuecat.purchases:purchases-bom:$revenueCatVersion"))
    implementation("com.revenuecat.purchases:purchases")
    implementation("com.revenuecat.purchases:purchases-admob-next-gen")
    implementation("com.google.android.libraries.ads.mobile.sdk:ads-mobile-sdk:1.4.0")
}
```

--------------------------------

### PaywallView

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/ui/revenuecatui/api.txt

Documentation for the PaywallView class, including constructors and methods for configuring and controlling the paywall view.

```APIDOC
## PaywallView

### Description
A composable view that displays a RevenueCat paywall. It can be configured with an offering, listener, font provider, dismiss button, purchase logic, and dismiss handler.

### Constructors

#### PaywallView(Context context)
- **context** (android.content.Context) - Required - The context.

#### PaywallView(Context context, AttributeSet? attrs)
- **context** (android.content.Context) - Required - The context.
- **attrs** (android.util.AttributeSet?) - Optional - The attribute set.

#### PaywallView(Context context, AttributeSet? attrs, int defStyleAttr)
- **context** (android.content.Context) - Required - The context.
- **attrs** (android.util.AttributeSet?) - Optional - The attribute set.
- **defStyleAttr** (int) - Required - The default style attribute.

#### PaywallView(Context context, Offering? offering)
- **context** (android.content.Context) - Required - The context.
- **offering** (com.revenuecat.purchases.Offering?) - Optional - The offering to display.

#### PaywallView(Context context, Offering? offering, PaywallListener? listener)
- **context** (android.content.Context) - Required - The context.
- **offering** (com.revenuecat.purchases.Offering?) - Optional - The offering to display.
- **listener** (com.revenuecat.purchases.ui.revenuecatui.PaywallListener?) - Optional - The listener for paywall events.

#### PaywallView(Context context, Offering? offering, PaywallListener? listener, FontProvider? fontProvider)
- **context** (android.content.Context) - Required - The context.
- **offering** (com.revenuecat.purchases.Offering?) - Optional - The offering to display.
- **listener** (com.revenuecat.purchases.ui.revenuecatui.PaywallListener?) - Optional - The listener for paywall events.
- **fontProvider** (com.revenuecat.purchases.ui.revenuecatui.fonts.FontProvider?) - Optional - The font provider.

#### PaywallView(Context context, Offering? offering, PaywallListener? listener, FontProvider? fontProvider, Boolean? shouldDisplayDismissButton)
- **context** (android.content.Context) - Required - The context.
- **offering** (com.revenuecat.purchases.Offering?) - Optional - The offering to display.
- **listener** (com.revenuecat.purchases.ui.revenuecatui.PaywallListener?) - Optional - The listener for paywall events.
- **fontProvider** (com.revenuecat.purchases.ui.revenuecatui.fonts.FontProvider?) - Optional - The font provider.
- **shouldDisplayDismissButton** (Boolean?) - Optional - Whether to display a dismiss button.

#### PaywallView(Context context, Offering? offering, PaywallListener? listener, FontProvider? fontProvider, Boolean? shouldDisplayDismissButton, PaywallPurchaseLogic? purchaseLogic)
- **context** (android.content.Context) - Required - The context.
- **offering** (com.revenuecat.purchases.Offering?) - Optional - The offering to display.
- **listener** (com.revenuecat.purchases.ui.revenuecatui.PaywallListener?) - Optional - The listener for paywall events.
- **fontProvider** (com.revenuecat.purchases.ui.revenuecatui.fonts.FontProvider?) - Optional - The font provider.
- **shouldDisplayDismissButton** (Boolean?) - Optional - Whether to display a dismiss button.
- **purchaseLogic** (com.revenuecat.purchases.ui.revenuecatui.PaywallPurchaseLogic?) - Optional - The purchase logic.

#### PaywallView(Context context, Offering? offering, PaywallListener? listener, FontProvider? fontProvider, Boolean? shouldDisplayDismissButton, PaywallPurchaseLogic? purchaseLogic, Function0<Unit>? dismissHandler)
- **context** (android.content.Context) - Required - The context.
- **offering** (com.revenuecat.purchases.Offering?) - Optional - The offering to display.
- **listener** (com.revenuecat.purchases.ui.revenuecatui.PaywallListener?) - Optional - The listener for paywall events.
- **fontProvider** (com.revenuecat.purchases.ui.revenuecatui.fonts.FontProvider?) - Optional - The font provider.
- **shouldDisplayDismissButton** (Boolean?) - Optional - Whether to display a dismiss button.
- **purchaseLogic** (com.revenuecat.purchases.ui.revenuecatui.PaywallPurchaseLogic?) - Optional - The purchase logic.
- **dismissHandler** (kotlin.jvm.functions.Function0<kotlin.Unit>?) - Optional - The dismiss handler.

#### PaywallView(Context context, Offering? offering, PaywallListener? listener, FontProvider? fontProvider, Boolean? shouldDisplayDismissButton, Function0<Unit>? dismissHandler)
- **context** (android.content.Context) - Required - The context.
- **offering** (com.revenuecat.purchases.Offering?) - Optional - The offering to display.
- **listener** (com.revenuecat.purchases.ui.revenuecatui.PaywallListener?) - Optional - The listener for paywall events.
- **fontProvider** (com.revenuecat.purchases.ui.revenuecatui.fonts.FontProvider?) - Optional - The font provider.
- **shouldDisplayDismissButton** (Boolean?) - Optional - Whether to display a dismiss button.
- **dismissHandler** (kotlin.jvm.functions.Function0<kotlin.Unit>?) - Optional - The dismiss handler.

### Methods

#### Content()
- **@KotlinOnly** - Composable function that defines the content of the view.

#### getLifecycle()
- **@InaccessibleFromKotlin** - Returns the Lifecycle owner.
- **Returns** (androidx.lifecycle.Lifecycle) - The lifecycle.

#### getSavedStateRegistry()
- **@InaccessibleFromKotlin** - Returns the SavedStateRegistry owner.
- **Returns** (androidx.savedstate.SavedStateRegistry) - The saved state registry.

#### getViewModelStore()
- **@InaccessibleFromKotlin** - Returns the ViewModelStore owner.
- **Returns** (androidx.lifecycle.ViewModelStore) - The view model store.

#### onBackPressed()
- Handles the back press event.

#### setCustomVariables(Map<String, ? extends CustomVariableValue> variables)
- **variables** (java.util.Map<java.lang.String,? extends com.revenuecat.purchases.ui.revenuecatui.CustomVariableValue>) - Required - The custom variables to set.

#### setDismissHandler(Function0<Unit>? dismissHandler)
- **dismissHandler** (kotlin.jvm.functions.Function0<kotlin.Unit>?) - Optional - The dismiss handler.

#### setDisplayDismissButton(boolean shouldDisplayDismissButton)
- **shouldDisplayDismissButton** (boolean) - Required - Whether to display the dismiss button.

#### setFontProvider(FontProvider? fontProvider)
- **fontProvider** (com.revenuecat.purchases.ui.revenuecatui.fonts.FontProvider?) - Optional - The font provider.

#### setOfferingId(String? offeringId)
- **offeringId** (String?) - Optional - The offering identifier.

#### setOfferingId(String? offeringId, PresentedOfferingContext? presentedOfferingContext)
- **offeringId** (String?) - Optional - The offering identifier.
- **presentedOfferingContext** (com.revenuecat.purchases.PresentedOfferingContext?) - Optional - The presented offering context.

#### setPaywallListener(PaywallListener? listener)
- **listener** (com.revenuecat.purchases.ui.revenuecatui.PaywallListener?) - Optional - The paywall listener.

#### setPurchaseLogic(PaywallPurchaseLogic? purchaseLogic)
- **purchaseLogic** (com.revenuecat.purchases.ui.revenuecatui.PaywallPurchaseLogic?) - Optional - The purchase logic.
```

--------------------------------

### Load and show app open ad (AdMob only)

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/feature/admob/README.md

Loads an app open ad using the AdMob API directly. Use this when you do not need RevenueCat tracking. The ad is loaded asynchronously and shown later with the show method.

```kotlin
AppOpenAd.load(
    context,
    "AD_UNIT_ID",
    AdRequest.Builder().build(),
    object : AppOpenAdLoadCallback() {
        override fun onAdLoaded(ad: AppOpenAd) {
            appOpenAd = ad
        }
        override fun onAdFailedToLoad(loadAdError: LoadAdError) {
            // Handle error.
        }
    },
)

// Later, to show:
appOpenAd?.show(activity)
```

--------------------------------

### PaywallActivityLaunchIfNeededOptions.Builder

Source: https://github.com/revenuedot/purchases-android/blob/revenuedot/main-patches/ui/revenuecatui/api.txt

Builder class for configuring options to launch a paywall activity if needed.

```APIDOC
## PaywallActivityLaunchIfNeededOptions.Builder

### Description
Builder for configuring options to launch a paywall activity if needed.

### Constructor
`PaywallActivityLaunchIfNeededOptions.Builder()`

### Methods
- `build()`: Returns `PaywallActivityLaunchIfNeededOptions`.
- `setCustomVariables(Map<String, ? extends CustomVariableValue> customVariables)`: Sets custom variables.
- `setEdgeToEdge(boolean edgeToEdge)`: Sets edge-to-edge mode.
- `setFontProvider(ParcelizableFontProvider? fontProvider)`: Sets font provider.
- `setListener(PaywallListener? listener)`: Sets paywall listener (experimental).
- `setOffering(Offering? offering)`: Sets offering.
- `setPaywallDisplayCallback(PaywallDisplayCallback? paywallDisplayCallback)`: Sets paywall display callback.
- `setPurchaseLogic(PaywallPurchaseLogic? purchaseLogic)`: Sets purchase logic (experimental).
- `setRequiredEntitlementIdentifier(String requiredEntitlementIdentifier)`: Sets required entitlement identifier.
- `setShouldDisplayBlock(Function1<? super CustomerInfo, Boolean> shouldDisplayBlock)`: Sets display block.
- `setShouldDisplayDismissButton(boolean shouldDisplayDismissButton)`: Sets whether to display dismiss button.

### Parameters
- `customVariables` (Map<String, ? extends CustomVariableValue>) - Optional - Custom variables for the paywall.
- `edgeToEdge` (boolean) - Optional - Whether to use edge-to-edge display.
- `fontProvider` (ParcelizableFontProvider?) - Optional - Font provider for the paywall.
- `listener` (PaywallListener?) - Optional - Listener for paywall events.
- `offering` (Offering?) - Optional - Offering to display.
- `paywallDisplayCallback` (PaywallDisplayCallback?) - Optional - Callback when paywall is displayed.
- `purchaseLogic` (PaywallPurchaseLogic?) - Optional - Custom purchase logic.
- `requiredEntitlementIdentifier` (String) - Optional - Required entitlement identifier.
- `shouldDisplayBlock` (Function1<? super CustomerInfo, Boolean>) - Optional - Block to determine if paywall should display.
- `shouldDisplayDismissButton` (boolean) - Optional - Whether to show dismiss button.

### Returns
- `PaywallActivityLaunchIfNeededOptions` - The built options.
```