> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 예제 앱: 인앱 메시지

> 예제 앱 Clean Beans가 인앱 메시지 트리거와 커스텀 HTML로 도움말 오버레이, 권한 사전 안내, 업데이트 및 리뷰 요청을 구현하는 방법입니다.

이 페이지는 실제 앱 하나를 처음부터 끝까지 따라가는 [예제 앱: OneSignal 전체 통합](https://documentation.onesignal.com/docs/ko/example-full-integration-overview.md)의 일부입니다. 앱은 공유 주택을 위한 청소 당번표 앱인 **Clean Beans**이며, Expo(React Native)와 Supabase 백엔드로 만들어졌습니다.

인앱 메시지는 사용자가 앱을 사용하는 동안 표시됩니다. 콘텐츠, 대상, 일정은 OneSignal 대시보드에 있으므로 릴리스 없이 바꿀 수 있습니다. Clean Beans는 다섯 가지 용도로 사용합니다.

| 메시지 | 표시 시점 | 타겟팅 방법 |
| - | - | - |
| 도움말 오버레이 | 사용자가 화면의 도움말 버튼을 탭할 때 | 앱이 설정하는 트리거 |
| 안내 | 사용자에게 화면 안내가 필요할 때 | 같은 트리거 |
| 푸시 권한 사전 안내 | 시스템 권한 대화상자 전에 | 대시보드의 대상과 일정 |
| 앱 업데이트 안내 | 사용자가 오래된 버전을 사용할 때 | 세그먼트 |
| 리뷰 요청 | 사용자가 연속 기록 목표에 도달했을 때 | 앱이 설정하는 트리거 |

## 트리거: 시점은 앱이 결정 \\

트리거는 앱이 설정하는 키와 값입니다. 이와 일치하도록 구성된 인앱 메시지가 표시됩니다. Clean Beans의 모든 화면에는 헤더에 도움말 버튼이 있으며, 이 버튼은 화면 이름을 값으로 하는 트리거 하나를 설정합니다.

```typescript src/components/HelpButton.tsx theme={null}
export function HelpButton({ triggerValue }: HelpButtonProps) {
  const handlePress = () => {
    OneSignal.InAppMessages.addTrigger('help_topic', triggerValue);
  };

  return (
    <TouchableOpacity onPress={handlePress} style={styles.button} hitSlop={8}>
      <Ionicons name="help-circle-outline" size={26} color={Colors.white} />
    </TouchableOpacity>
  );
}
```

```typescript app/(tabs)/_layout.tsx theme={null}
<Tabs.Screen
  name="index"
  options={{
    title: 'Dashboard',
    headerRight: () => <HeaderRight helpTopic="dashboard" />,
    tabBarIcon: ({ focused }) => <TabIcon name={focused ? 'home' : 'home-outline'} focused={focused} />,
  }}
/>
```

트리거 키 하나가 13개 화면을 담당합니다. 새 화면에 도움말을 추가하려면 새 값을 가진 버튼을 추가하고 대시보드에서 메시지를 만들면 됩니다.

![대시보드 위에 표시된 도움말 오버레이 인앱 메시지](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-help.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=521ce92f66d1df24e99790600813523a)

대시보드의 도움말 버튼을 탭하면 도움말 오버레이가 표시됩니다.

**대시보드 설정.** **Messages > In-App**에서 트리거가 `help_topic` **is** `dashboard`인 메시지를 만들고, 화면마다 반복하세요. 여러 단계로 된 안내는 같은 트리거에 캐러셀 레이아웃을 사용합니다.

![넘길 수 있는 카드로 구성된 안내 인앱 메시지](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-iam-walkthrough.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=c335375ee2bb79060e97aa945dea644e)

카드 캐러셀로 만든 여러 단계의 안내.

## 커스텀 HTML 메시지 \\

도움말 오버레이는 HTML로 작성되어 앱의 디자인과 정확히 일치합니다. HTML 인앱 메시지는 `OneSignalIamApi` 객체를 통해 SDK와 통신합니다. 클릭할 수 있는 모든 요소에는 두 가지 규칙이 적용됩니다.

* 클릭이 올바르게 추적되도록 고유한 `data-onesignal-unique-label`을 지정합니다.
* `OneSignalIamApi` 메서드를 호출하는 리스너를 연결합니다. 일반 링크는 추적되지 않습니다.

```html docs/iam-html/help-dashboard.html theme={null}
<button id="got-it" class="cta-btn" data-onesignal-unique-label="dashboard-got-it">Got it</button>

<script>
  document.addEventListener("DOMContentLoaded", function () {
    document.getElementById("got-it").addEventListener("click", function (e) {
      OneSignalIamApi.close(e);
    });
  });
</script>
```

## 푸시 권한 사전 안내 \\

시스템 권한 대화상자는 한 번만 표시할 수 있습니다. 먼저 인앱 메시지를 표시하면 사용자가 무엇을 받게 되는지 설명할 수 있고, **Enable notifications**를 탭한 사람만 시스템 대화상자를 보게 됩니다.

![알림을 켜면 좋은 점을 설명하는 인앱 메시지](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-iam-push-prompt.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=18791e9af52a803d41048eba393109f6)

사전 안내는 시스템 대화상자가 나타나기 전에 이점을 설명합니다.

```html docs/iam-html/push-permission-prompt.html theme={null}
<script>
  document.addEventListener("DOMContentLoaded", function () {
    document.getElementById("enable-btn").addEventListener("click", function (e) {
      OneSignalIamApi.triggerPushPrompt(e);
    });
    document.getElementById("skip-btn").addEventListener("click", function (e) {
      OneSignalIamApi.close(e);
    });
  });
</script>
```

> [!NOTE]
>
> 사전 안내를 사용한다면 앱 시작 시의 `requestPermission()` 호출을 제거하세요. 그렇지 않으면 시스템 대화상자가 먼저 나타나 사전 안내가 물어볼 것이 남지 않습니다.

## 앱 업데이트 안내 \\

새 버전이 출시되면 이전 버전 사용자에게 업데이트를 권하는 안내가 표시됩니다. 이 메시지에는 앱 코드가 전혀 필요하지 않습니다. 대상은 오래된 앱 버전을 사용하는 사용자 세그먼트입니다.

![사용자에게 앱 업데이트를 요청하는 인앱 메시지](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-iam-app-version.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=f096ce85f566823331171e14312e534d)

오래된 버전 사용자에게만 표시되는 업데이트 안내.

메시지 하나가 두 플랫폼을 모두 지원합니다. 스크립트가 기기에 맞는 스토어를 고르고, `openUrl`이 클릭을 추적한 뒤 스토어를 열고 메시지를 닫습니다.

```html docs/iam-html/app-update-prompt.html theme={null}
<script>
  var IOS_URL = "https://apps.apple.com/app/id" + IOS_APP_STORE_ID;
  var ANDROID_URL = "https://play.google.com/store/apps/details?id=" + ANDROID_PACKAGE;

  // One message serves both platforms: pick the store from the device.
  var isAndroid = /android/i.test(navigator.userAgent);
  var storeUrl = isAndroid ? ANDROID_URL : IOS_URL;

  document.addEventListener("DOMContentLoaded", function () {
    document.getElementById("update-btn").addEventListener("click", function (e) {
      // openUrl tracks the click, opens the store and closes the message
      OneSignalIamApi.openUrl(e, storeUrl);
    });
    document.getElementById("later-btn").addEventListener("click", function (e) {
      OneSignalIamApi.close(e);
    });
  });
</script>
```

인사말은 태그를 사용하며, 태그가 없는 사용자를 위한 대체 값이 있습니다.

```html docs/iam-html/app-update-prompt.html theme={null}
<p>Hey {{ user_name | default: "there" }}, you're on an older version</p>
```

**대시보드 설정.** **App version** 필터가 현재 버전보다 작은 세그먼트를 만들고 이를 메시지 대상으로 사용하세요. 릴리스할 때마다 필터를 업데이트하세요.

> [!NOTE]
>
> 태그 대체는 HTML 인앱 메시지의 텍스트와 속성에서는 동작하지만 `script` 태그 안에서는 동작하지 않습니다.

## 리뷰 요청: 클릭을 앱으로 돌려주기 \\

앱 스토어 평점을 요청하기 좋은 시점은 무언가가 잘 된 직후입니다. Clean Beans는 청소 세션으로 연속 기록이 7일의 배수에 도달했을 때 요청합니다.

네이티브 평가 시트는 앱 자체만 열 수 있으므로, 이것은 탭이 앱의 코드를 실행해야 하는 유일한 인앱 메시지입니다.

**1. 앱이 연속 기록 목표 지점에서 트리거를 설정합니다**

청소를 방해하지 않도록 세션 화면이 닫힐 때까지 기다리며, 마지막으로 요청한 목표 지점을 기억합니다.

```typescript src/lib/reviewPrompt.ts theme={null}
export async function maybeAskForReview(streak: number): Promise<void> {
  try {
    if (streak <= 0 || streak % STREAK_MILESTONE_DAYS !== 0) return;

    // A second session on the same day leaves the streak unchanged —
    // don't ask twice for the same milestone.
    const lastPrompted = await AsyncStorage.getItem(LAST_PROMPTED_STREAK_KEY);
    if (lastPrompted === String(streak)) return;
    await AsyncStorage.setItem(LAST_PROMPTED_STREAK_KEY, String(streak));

    OneSignal.InAppMessages.addTrigger(REVIEW_TRIGGER_KEY, REVIEW_TRIGGER_VALUE);
    console.log('[reviewPrompt] Trigger set at streak', streak);
  } catch (e) {
    console.warn('[reviewPrompt] maybeAskForReview error:', e);
  }
}
```

**2. 메시지가 클릭 이름을 앱에 보냅니다**

`addClickName`은 앱의 클릭 리스너에 이름을 전달합니다. 메시지를 닫지는 않으므로 스크립트가 이후에 메시지를 닫습니다.

```html docs/iam-html/review-prompt.html theme={null}
<script>
  document.addEventListener("DOMContentLoaded", function () {
    var autoCloseBtn = document.getElementById("auto-close-btn");

    document.getElementById("rate-btn").addEventListener("click", function (e) {
      // Passes the click name "review" to the app's In-App Message click
      // listener, which opens the native rating sheet. addClickName does not
      // close the message, so close it straight afterwards.
      OneSignalIamApi.addClickName(e, "review");
      setTimeout(function () { autoCloseBtn.click(); }, 300);
    });
    autoCloseBtn.addEventListener("click", function (e) {
      OneSignalIamApi.close(e);
    });
    document.getElementById("later-btn").addEventListener("click", function (e) {
      OneSignalIamApi.close(e);
    });
  });
</script>
```

**3. 앱이 네이티브 평가 시트를 엽니다**

클릭 리스너가 이름을 확인하고 시스템에 시트를 표시하도록 요청합니다.

```typescript src/lib/reviewPrompt.ts theme={null}
export function handleReviewClick(event: InAppMessageClickEvent): void {
  if (event.result.actionId !== REVIEW_ACTION_ID) return;

  // Give the In-App Message a moment to close before presenting the sheet
  setTimeout(async () => {
    try {
      // false on TestFlight builds and on the web
      if (await StoreReview.isAvailableAsync()) {
        await StoreReview.requestReview();
      } else {
        console.log('[reviewPrompt] Store review not available on this build');
      }
    } catch (e) {
      console.warn('[reviewPrompt] requestReview error:', e);
    } finally {
      // Clear the trigger so the message is not re-evaluated this app session
      OneSignal.InAppMessages.removeTrigger(REVIEW_TRIGGER_KEY);
    }
  }, 800);
}
```

```typescript app/_layout.tsx theme={null}
OneSignal.InAppMessages.addEventListener('click', handleReviewClick);
```

![리뷰 요청 인앱 메시지](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-review-prompt.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=90dde058450240f49d42e76402ed28ce)

리뷰 요청 인앱 메시지.

**대시보드 설정.** 트리거가 `ask_for_review` **is** `show`인 HTML 인앱 메시지를 만드세요. 최대 17주에 한 번 표시되도록 일정을 설정하세요.

> [!WARNING]
>
> Apple은 평가 시트를 사용자당 1년에 최대 세 번만 표시하며, Google에도 자체 제한이 있으므로 버튼을 탭해도 아무것도 표시되지 않을 수 있습니다. TestFlight 빌드에서는 시트가 나타나지 않습니다. 이 흐름은 App Store 빌드로 테스트하세요.

> [card] [인앱 트리거](https://documentation.onesignal.com/docs/ko/iam-triggers.md)
>
> 트리거 유형과 조합 방식.

> [card] [HTML 인앱 메시지](https://documentation.onesignal.com/docs/ko/design-your-in-app-message-with-html.md)
>
> 직접 작성한 HTML로 메시지 디자인하기.

> [card] [인앱 JavaScript API](https://documentation.onesignal.com/docs/ko/in-app-message-api.md)
>
> 모든 `OneSignalIamApi` 메서드.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.