Install

pnpm add @cap-kit/rank
# or
npm install @cap-kit/rank
# or
yarn add @cap-kit/rank
# then run:
npx cap sync

Configuration

Configuration options for the Rank plugin.

| Prop | Type | Description | Default | Since | | ------------------------ | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----- | | verboseLogging | boolean | Enables verbose native logging. When enabled, additional debug information is printed to the native console (Logcat on Android, Xcode on iOS). | false | 8.0.0 | | appleAppId | string | The Apple App ID used for App Store redirection on iOS. Example: '123456789' * @since 8.0.0 | | | | androidPackageName | string | The Android Package Name used for Play Store redirection. Example: 'com.example.app' * @since 8.0.0 | | | | fireAndForget | boolean | If true, the requestReview method will resolve immediately without waiting for the native OS review flow to complete. * @default false | | 8.0.0 |

Examples

In capacitor.config.json:

{
  "plugins": {
    "Rank": {
      "verboseLogging": true,
      "appleAppId": "123456789",
      "androidPackageName": "com.example.app",
      "fireAndForget": false
    }
  }
}

In capacitor.config.ts:

/// <reference types="@cap-kit/rank" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    Rank: {
      verboseLogging: true,
      appleAppId: '123456789',
      androidPackageName: 'com.example.app',
      fireAndForget: false,
    },
  },
};

export default config;

Native Requirements

Android

• Requires Google Play Services for In-App Reviews.
• To support Android 11+ (API 30+) and allow navigation to the Play Store, you must include the following in your AndroidManifest.xml:

<queries>
    <intent>
        <action android:name="android.intent.action.VIEW" />
        <data android:scheme="market" />
    </intent>
    <intent>
        <action android:name="android.intent.action.VIEW" />
        <data android:scheme="https" android:host="play.google.com" />
    </intent>
</queries>

iOS

• Requires Xcode 26 and iOS 15+.
• To allow the plugin to open the App Store review page, ensure your Info.plist includes the appropriate URL schemes if you perform programmatic checks.

Permissions

Android

This plugin requires the following permission, which is automatically merged into your application's AndroidManifest.xml:

• android.permission.INTERNET: Required to communicate with Google Play Services for the review flow and store navigation.

iOS

No specific usage descriptions (Privacy Manifest) are required for the standard SKStoreReviewController flow.

API

• isAvailable()
• checkReviewEnvironment()
• requestReview(...)
• presentProductPage(...)
• openStore(...)
• openStoreListing(...)
• search(...)
• openDevPage(...)
• openCollection(...)
• getPluginVersion()
• Interfaces

Public JavaScript API for the Rank Capacitor plugin.

This interface defines a stable, platform-agnostic API. All methods behave consistently across Android, iOS, and Web.

isAvailable()

isAvailable() => Promise<AvailabilityResult>

Checks if the native In-App Review UI can be displayed. On Android, it verifies Google Play Services availability. On iOS, it checks the OS version compatibility.

Returns: Promise<AvailabilityResult>

Since: 8.0.0

Example

const { value } = await Rank.isAvailable();
if (value) {
  // Show review prompt or related UI
} else {
  // Fallback behavior for unsupported platforms
}

checkReviewEnvironment()

checkReviewEnvironment() => Promise<ReviewEnvironmentResult>

Performs a diagnostic check to determine whether the Google Play In-App Review dialog can be displayed.

This does NOT trigger the review flow. Android-only. On other platforms, it resolves as unavailable.

Returns: Promise<ReviewEnvironmentResult>

Since: 8.0.0

requestReview(...)

requestReview(options?: ReviewOptions | undefined) => Promise<void>

Requests the display of the native review popup. On Web, this operation calls unimplemented().

| Param | Type | Description | | ------------- | ------------------------------------------------------- | ---------------------------------------- | | options | ReviewOptions | Optional review configuration overrides. |

Since: 8.0.0

Example

// Basic usage with default configuration
await Rank.requestReview();

// Usage with fire-and-forget behavior
await Rank.requestReview({ fireAndForget: true });

presentProductPage(...)

presentProductPage(options?: StoreOptions | undefined) => Promise<void>

Opens the App Store product page internally (iOS) or redirects to the Store (Android/Web).

| Param | Type | Description | | ------------- | ----------------------------------------------------- | --------------------- | | options | StoreOptions | Store identification. |

Since: 8.0.0

Example

// On iOS, this will open an internal App Store overlay.
await Rank.presentProductPage({
  appId: '123456789' // iOS App ID for URL generation
});

// On Android, this will redirect to the Play Store.
await Rank.presentProductPage({
  packageName: 'com.example.app' // Android Package Name for URL generation
});

openStore(...)

openStore(options?: StoreOptions | undefined) => Promise<void>

Opens the app's page in the App Store (iOS) or Play Store (Android). On Web, it performs a URL redirect if parameters are provided.

| Param | Type | Description | | ------------- | ----------------------------------------------------- | ---------------------------------------- | | options | StoreOptions | Optional store identification overrides. |

Since: 8.0.0

Example

// On Web, this will open the store page in a new tab if identifiers are provided.
await Rank.openStore({
  appId: '123456789', // iOS App ID for URL generation
  packageName: 'com.example.app' // Android Package Name for URL generation
});

openStoreListing(...)

openStoreListing(options?: { appId?: string | undefined; } | undefined) => Promise<void>

Opens the App Store listing page for a specific app. If no appId is provided, it uses the one from the plugin configuration.

| Param | Type | | ------------- | -------------------------------- | | options | { appId?: string; } |

Since: 8.0.0

Example

// Opens the store listing page.
// Uses the provided appId or falls back to the one in capacitor.config.ts
await Rank.openStoreListing({
  appId: '123456789'
});

search(...)

search(options: { terms: string; }) => Promise<void>

Performs a search in the app store for the given terms.

| Param | Type | | ------------- | ------------------------------- | | options | { terms: string; } |

Since: 8.0.0

Example

// Searches the store for specific terms.
// Android: market://search | iOS: itms-apps search
await Rank.search({
  terms: 'Capacitor Plugins'
});

openDevPage(...)

openDevPage(options: { devId: string; }) => Promise<void>

Opens the developer's page in the app store.

| Param | Type | | ------------- | ------------------------------- | | options | { devId: string; } |

Since: 8.0.0

Example

// Navigates to a developer or brand page.
await Rank.openDevPage({
  devId: '543216789'
});

openCollection(...)

openCollection(options: { name: string; }) => Promise<void>

Opens a specific app collection (Android Only).

| Param | Type | | ------------- | ------------------------------ | | options | { name: string; } |

Since: 8.0.0

Example

// Opens a curated collection (Android only).
await Rank.openCollection({
  name: 'editors_choice'
});

getPluginVersion()

getPluginVersion() => Promise<PluginVersionResult>

Returns the native plugin version.

The returned version corresponds to the native implementation bundled with the application.

Returns: Promise<PluginVersionResult>

Since: 8.0.0

Example

const { version } = await Rank.getPluginVersion();

Interfaces

AvailabilityResult

Result object returned by the isAvailable() method.

| Prop | Type | Description | | ----------- | -------------------- | ----------------------------------------------------------- | | value | boolean | Indicates whether the native In-App Review UI is available. |

ReviewEnvironmentResult

Diagnostic result for Android In-App Review availability.

This result describes whether the Google Play Review flow can actually be displayed in the current environment.

| Prop | Type | Description | | ---------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------ | | canRequestReview | boolean | True if the environment supports showing the review dialog. | | reason | 'PLAY_STORE_NOT_AVAILABLE' | 'NOT_INSTALLED_FROM_PLAY_STORE' | Optional diagnostic reason when the review dialog cannot be shown. |

ReviewOptions

Options for the requestReview method.

| Prop | Type | Description | | ------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------- | | fireAndForget | boolean | Override the global configuration to determine if the promise should resolve immediately or wait for the native flow. |

StoreOptions

Options for the openStore method.

| Prop | Type | Description | | ----------------- | ------------------- | ---------------------------------------------- | | appId | string | Runtime override for the Apple App ID on iOS. | | packageName | string | Runtime override for the Android Package Name. |

PluginVersionResult

Result object returned by the getPluginVersion() method.

| Prop | Type | Description | | ------------- | ------------------- | --------------------------------- | | version | string | The native plugin version string. |

Limitations

General

• openCollection: This feature is specific to the Google Play Store and is unavailable on iOS/Web.
• openDevPage: On iOS, this method performs a store search for the developer name as a fallback, as direct developer page IDs are not consistently supported via deep links.

iOS

• The in-app review prompt is not guaranteed to appear. Apple internally controls when and how often the review dialog is shown.
• Calling requestReview() may result in no visible UI, even if the API is available.
• On iOS, requestReview() is effectively always fire-and-forget because StoreKit does not provide a completion callback; the fireAndForget option does not change this behavior on iOS.

Android

• Google Play In-App Review requires Google Play Services to be available on the device.
• The review flow may silently fail if Play Services are missing, outdated, or restricted.
• As with iOS, the system ultimately decides whether the review dialog is displayed.

Best practices

• Call requestReview() only after a positive user interaction (e.g. completed task, successful checkout, achieved milestone).
• Avoid calling the review prompt on app startup or without user context.
• Always check availability first:

const { value } = await Rank.isAvailable();
if (value) {
  await Rank.requestReview();
}

• Use fireAndForget: true only when you do not need to track completion and want to avoid blocking UI flows.

Error handling

All Rank plugin methods return Promises and may reject in case of failure. Consumers should always handle errors using try / catch.

Example

import { Rank, RankErrorCode } from '@cap-kit/rank';

try {
  await Rank.requestReview();
} catch (err: any) {
  switch (err.code) {
    case RankErrorCode.UNAVAILABLE:
      // Feature not supported on this device or platform
      break;

    case RankErrorCode.INIT_FAILED:
      // Native initialization or runtime failure
      break;

    default:
      // Unknown or unexpected error
      console.error(err.message);
  }
}

Error codes

The following error codes may be returned by the plugin:

• UNAVAILABLE — The feature is not supported on the current device or platform
• PERMISSION_DENIED — A required permission was denied (platform-dependent)
• INIT_FAILED — Native initialization or runtime failure
• UNKNOWN_TYPE — Invalid or unsupported input

Contributing

Contributions are welcome! Please read the contributing guide before submitting a pull request.

License

MIT