> 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/common/growth/review.md).

# 리뷰 요청

`requestReview`는 미니앱에서 사용자에게 리뷰 작성을 요청할 수 있는 API예요.

Android의 `In-App Review` API, iOS의 `SKStoreReviewController`와 비슷한 방향으로 동작하며, 사용자가 서비스의 가치를 충분히 체감한 시점에 자연스럽게 리뷰를 남길 수 있도록 도와줘요.

**시그니처**

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

### 언제 호출하면 좋나요?

`requestReview`는 사용자가 앱의 가치를 충분히 느낀 시점에 호출하는 것을 권장해요.

예를 들면 아래와 같은 순간이 적절해요.

* 핵심 태스크를 성공적으로 완료한 직후
* 목표를 달성하거나 보상을 획득한 직후
* 반복 사용 후 만족도가 높을 것으로 예상되는 순간

이 시점에 호출하면 사용자가 긍정적인 경험을 한 상태에서 리뷰를 남기게 되어, 더 좋은 리뷰 품질을 기대할 수 있어요.

### 동작 방식

`requestReview`를 호출하면 사용자에게 아래 순서로 리뷰 플로우가 노출될 수 있어요.

1. 별점 입력 화면이 먼저 노출돼요.
2. 사용자가 **4점 이상**을 선택한 경우에만 텍스트 리뷰 작성 화면이 추가로 노출돼요.
3. 사용자가 **3점 이하**를 선택한 경우에는 텍스트 리뷰 작성 없이 별점만 수집돼요.

### 사용 가이드

{% hint style="info" %}
**호출해도 항상 노출되지는 않아요**

`requestReview`를 호출하더라도 리뷰 입력 화면이 항상 표시되지는 않아요.

앱인토스 내부 정책에 따라 사용자의 피로도를 고려해 노출 여부가 결정돼요. 따라서 리뷰 화면이 반드시 뜬다는 전제로 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/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.