入门

1. 安装软件包

   npm

   npm i @capgo/capacitor-in-app-review

   pnpm

   pnpm add @capgo/capacitor-in-app-review

   yarn

   yarn add @capgo/capacitor-in-app-review

   bun

   bun add @capgo/capacitor-in-app-review

2. 与原生项目同步

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

用法

导入插件并在您的应用程序中的适当时刻请求审核：

import { CapgoInAppReview } from '@capgo/capacitor-in-app-review';

// Request a review at a natural point in your app's user flow
const requestReview = async () => {
  try {
    await CapgoInAppReview.requestReview();
    console.log('Review requested successfully');
  } catch (error) {
    console.error('Failed to request review:', error);
  }
};

API 参考

requestReview()

触发本机应用内审阅对话框。

await CapgoInAppReview.requestReview();

重要说明：

• 每次调用此方法时可能不会显示审阅对话框
• Apple 和 Google 都有限制提示出现频率的准则
• 不保证用户会看到审核提示
• 即使未显示对话框，该方法也能成功解析
• 不要调用它来响应用户操作，例如点击按钮

getPluginVersion()

返回本机插件版本。

const { version } = await CapgoInAppReview.getPluginVersion();
console.log('Plugin version:', version);

最佳实践

何时请求评论

在用户最有可能获得积极体验的时刻请求评论：

// Good examples:
// - After completing a level in a game
// - After successfully completing a task
// - After the user has used the app multiple times
// - After a positive interaction

// Example: Track usage and request review after positive milestone
let taskCompletedCount = 0;

const onTaskComplete = async () => {
  taskCompletedCount++;

  // Request review after user completes 5 tasks
  if (taskCompletedCount === 5) {
    await CapgoInAppReview.requestReview();
  }
};

何时不请求评论

// Bad examples - DO NOT do these:
// - On app launch
// - In response to a "Rate Us" button tap
// - After an error or negative experience
// - Too frequently (respect platform quotas)

跟踪审核请求

由于平台控制是否显示对话框，因此请跟踪您的请求：

import { CapgoInAppReview } from '@capgo/capacitor-in-app-review';
import { Preferences } from '@capacitor/preferences';

const requestReviewIfAppropriate = async () => {
  const lastRequest = await Preferences.get({ key: 'lastReviewRequest' });
  const daysSinceLastRequest = lastRequest.value
    ? (Date.now() - parseInt(lastRequest.value)) / (1000 * 60 * 60 * 24)
    : Infinity;

  // Only request if it's been at least 30 days
  if (daysSinceLastRequest >= 30) {
    await CapgoInAppReview.requestReview();
    await Preferences.set({
      key: 'lastReviewRequest',
      value: Date.now().toString()
    });
  }
};

平台说明

iOS

• 使用 SKStoreReviewController
• 系统自动限制在365天内显示3次
• 根据 App Store 政策，该对话框可能不会出现
• 测试：在开发中，该对话框将始终出现，但不会提交评论

Android

• 使用 Play 应用内评论 API
• Google Play 对用户显示对话框的频率强制实施配额
• 该对话框不会在调试版本中显示
• 为了进行测试，您需要：
  • 从 Play Store 安装应用程序（内部测试轨道有效）
  • 设备上有 Google 帐户

完整示例

import { CapgoInAppReview } from '@capgo/capacitor-in-app-review';
import { Preferences } from '@capacitor/preferences';

export class ReviewService {
  private static REVIEW_REQUEST_KEY = 'lastReviewRequest';
  private static MIN_DAYS_BETWEEN_REQUESTS = 30;
  private static MIN_APP_LAUNCHES = 5;

  async checkAndRequestReview(): Promise<boolean> {
    const shouldRequest = await this.shouldRequestReview();

    if (shouldRequest) {
      try {
        await CapgoInAppReview.requestReview();
        await this.recordReviewRequest();
        return true;
      } catch (error) {
        console.error('Review request failed:', error);
        return false;
      }
    }

    return false;
  }

  private async shouldRequestReview(): Promise<boolean> {
    // Check app launch count
    const launchCount = await this.getAppLaunchCount();
    if (launchCount < ReviewService.MIN_APP_LAUNCHES) {
      return false;
    }

    // Check days since last request
    const lastRequest = await Preferences.get({ key: ReviewService.REVIEW_REQUEST_KEY });
    if (lastRequest.value) {
      const daysSince = (Date.now() - parseInt(lastRequest.value)) / (1000 * 60 * 60 * 24);
      if (daysSince < ReviewService.MIN_DAYS_BETWEEN_REQUESTS) {
        return false;
      }
    }

    return true;
  }

  private async getAppLaunchCount(): Promise<number> {
    const count = await Preferences.get({ key: 'appLaunchCount' });
    return count.value ? parseInt(count.value) : 0;
  }

  private async recordReviewRequest(): Promise<void> {
    await Preferences.set({
      key: ReviewService.REVIEW_REQUEST_KEY,
      value: Date.now().toString()
    });
  }

  async incrementLaunchCount(): Promise<void> {
    const current = await this.getAppLaunchCount();
    await Preferences.set({
      key: 'appLaunchCount',
      value: (current + 1).toString()
    });
  }
}