> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/common/growth/review.md).

# 请求评价

`requestReview`是在迷你应用中可向用户请求撰写评论的 API。

Android 的 `In-App Review` API，iOS 的 `SKStoreReviewController`其工作方式与 Android 的 In-App Review API、iOS 的 SKStoreReviewController 类似，并帮助用户在充分感受到服务价值时自然留下评论。

**签名**

```typescript
function requestReview(): Promise<void>;
```

### 什么时候调用比较好？

`requestReview`建议在用户充分感受到应用价值的时刻调用。

例如，下面这些时刻就很合适。

* 核心任务成功完成后
* 达成目标或获得奖励后
* 重复使用后预计满意度较高的时刻

在这个时点调用，用户会在有正面体验的状态下留下评论，因此可以期待更好的评论质量。

### 工作方式

`requestReview`调用后，用户可能会按以下顺序看到评论流程。

1. 会先显示星级输入页面。
2. 当用户 **选择 4 分及以上**时，才会额外显示文字评论撰写页面。
3. 当用户 **选择 3 分及以下**时，则只收集星级，不会进入文字评论撰写。

### 使用指南

{% hint style="info" %}
**调用也不一定会显示**

`requestReview`即使调用了，也不一定总会显示评论输入页面。

根据 Appintos 内部政策，会考虑用户疲劳度来决定是否展示。因此，不能以评论页面一定会弹出的前提来设计 UX 流程。
{% endhint %}

* 请只在用户感到满意的时候调用。
* 不要在同一会话中反复调用。
* 即使没有显示评论请求，也请设计成用户流程仍能自然继续。
* 不要设计成依赖评论请求是否显示来跳转到下一页或发放奖励的流程。
* 由于调用后看起来可能什么都没有发生，请将其与功能上必需的流程分离。

**示例**

**在核心行为完成后请求评论**

{% tabs %}
{% tab title="js" %}

```js
import { requestReview } from '@apps-in-toss/web-framework';

async function handleTaskCompleted() {
  await saveMissionResult();

  try {
    await requestReview();
  } catch (error) {
    console.error('评论请求失败：', error);
  }
}
```

{% endtab %}

{% tab title="React" %}

```tsx
import { requestReview } from '@apps-in-toss/web-framework';

function CompleteButton() {
  const handleComplete = async () => {
    await completeGoal();

    try {
      await requestReview();
    } catch (error) {
      console.error('评论请求失败：', error);
    }
  };

  return <button onClick={handleComplete}>完成</button>;
}
```

{% endtab %}

{% tab title="React Native" %}

```tsx
import { Button, Alert } from 'react-native';
import { requestReview } from '@apps-in-toss/framework';

function CompleteButton() {
  const handleComplete = async () => {
    await completeGoal();

    try {
      await requestReview();
    } catch (error) {
      Alert.alert('评论请求失败', String(error));
    }
  };

  return <Button title="完成" onPress={handleComplete} />;
}
```

{% endtab %}
{% endtabs %}

### 查看评论

在控制台的“评分与评论”菜单中 `requestReview`可以查看通过其收集的评论，以及通过导航栏的“留下使用感想”撰写的评论。

### 常见问题

<details>

<summary>如果对已经留下评论的用户调用，会怎样？</summary>

已经留下星级或评论的用户不会显示评论 UI，会直接跳过。

</details>

<details>

<summary>通过导航栏的留下使用感想写评论的用户也是一样吗？</summary>

是的，通过导航栏的“留下使用感想”留下评论的用户同样不会显示 UI。

</details>

<details>

<summary>Promise 什么时候 resolve？</summary>

在评论请求完成时 resolve。实际上 `Promise`不必等待 Promise。

</details>

<details>

<summary>即使因疲劳度政策被拦截，也会 resolve 吗？</summary>

是的。即使评论 UI 未展示，也会正常 resolve。

</details>

<details>

<summary>能区分评论完成和 dismiss 吗？</summary>

不能。我们有意不提供该能力，以免根据是否撰写评论来区分功能或行为。

</details>

<details>

<summary>可以查询特定用户的评论状态吗？</summary>

不能。目前不提供通过 SDK 或控制台 API 查询特定用户是否已撰写评论的功能。

</details>

<details>

<summary>有提供类似 getReviewStatus() 的 API 计划吗？</summary>

没有。由于与不返回评论撰写结果是同样的原因，目前没有提供计划。

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/common/growth/review.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.