> 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`与 SKStoreReviewController 类似地工作，帮助用户在充分感受到服务价值的时机，自然地留下评论。

**签名**

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

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

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

比如在以下这些时刻比较合适。

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

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

### 工作方式

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

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

### 使用指南

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

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

根据 Apps in Toss 的内部政策，会考虑用户疲劳度来决定是否展示。因此，不能把一定会弹出评论界面作为前提来设计 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`可以不等待。

</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.