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

# 인앱 메시지 이벤트 스트림

> 이벤트 스트림을 활용하여 인앱 메시지 메트릭을 캡처하는 방법

이 문서는 [인앱 메시지](./in-app-messages-setup) 이벤트의 기능 및 사용법을 설명합니다. 블록 수준 클릭 및 페이지별 표시를 포함하여 사용자가 이러한 메시지를 클릭하거나 볼 때마다 필수 참여 통계를 추적할 수 있습니다.

## 인앱 메시지 이벤트

인앱 메시지 이벤트에는 세 가지 종류의 [`event.kind`](./event-streams-data#event-kind)가 있습니다:

* 인앱 노출 - `message.iam.impression`
* 인앱 클릭 - `message.iam.clicked`
* 인앱 페이지 표시 - `message.iam.page_displayed`

이러한 이벤트는 사용자가 기기에서 인앱 메시지를 열고 상호 작용할 때 발생합니다.

### 인앱 노출

이 이벤트는 메시지가 로드를 완료하고 화면에 표시되는 즉시 발생합니다.

[캐러셀](./design-your-in-app-message#carousels)을 사용할 때 `event.data.page_name` 및 `event.data.page_id`를 사용하여 표시된 특정 페이지의 이름과 UUID를 가져올 수 있습니다.

### 인앱 클릭

이 이벤트는 클릭 작업이 있는 모든 요소 또는 블록("타겟"이라고도 함)에 적용됩니다. `event.data.target_name` 및 `event.data.target_id`를 사용하여 클릭된 특정 타겟의 이름과 UUID를 가져올 수 있으며, `event.data.page_name` 및 `event.data.page_id`를 사용하여 타겟이 속한 페이지도 가져올 수 있습니다.

자세한 내용은 [인앱 클릭 작업](./iam-click-actions)을 참조하세요.

### 인앱 페이지 표시

이는 [캐러셀](./design-your-in-app-message#carousels)에만 적용되는 이벤트입니다. `event.data.page_name` 및 `event.data.page_id`를 사용하여 표시된 특정 페이지 또는 카드의 이름과 UUID를 가져올 수 있습니다. 첫 번째 카드의 노출은 문서가 로드를 완료하는 즉시 발생합니다. 후속 페이지 노출은 스와이프 시 발생합니다.

## 인앱 메시지 이벤트 데이터

각 `event.kind`는 인앱 메시지를 만드는 방법에 따라 추가 이벤트 데이터를 가질 수 있습니다.

<ParamField path="event.data.page_name" type="string">
  `event.kind`가 `clicked` 또는 `page_displayed`일 때 표시되는 페이지 또는 카드의 이름입니다. `impression` 이벤트에는 사용할 수 없습니다.

  `page_name`은 어떤 페이지가 표시되었고 해당 페이지에서 무엇이 클릭되었는지 알아내는 데 도움이 됩니다.

  페이지 이름은 기본적으로 "Card 1", "Card 2" 등이지만 Block Editor 내에서 이름을 변경할 수 있습니다.

  <Frame>
    <img src="https://mintcdn.com/onesignal/Z6xkXGfmy814If53/images/docs/e0862074b7ea2c064808035d2028410dae6aecc4bdf9ae4c4c83eeee1ac8d643-Screenshot_2025-01-17_at_1.30.34_PM.png?fit=max&auto=format&n=Z6xkXGfmy814If53&q=85&s=44d2b05d410b28b9e6fec94fd979ec5b" width="1040" height="826" data-path="images/docs/e0862074b7ea2c064808035d2028410dae6aecc4bdf9ae4c4c83eeee1ac8d643-Screenshot_2025-01-17_at_1.30.34_PM.png" />
  </Frame>
</ParamField>

<ParamField path="event.data.page_id" type="string UUID v4">
  페이지의 고유 식별자입니다. [캐러셀](./design-your-in-app-message#carousels)을 사용하고 이전 카드가 삭제되거나 새 카드로 교체되는 경우에 유용합니다.
</ParamField>

<ParamField path="event.data.target_name" type="string">
  버튼 또는 이미지 블록 요소의 이름입니다. [클릭 작업](./iam-click-actions)을 설정해야 합니다.
</ParamField>

<ParamField path="event.data.target_id" type="string UUID v4">
  버튼 또는 이미지 블록 요소의 고유 식별자입니다. [클릭 작업](./iam-click-actions)을 설정해야 합니다. [캐러셀](./design-your-in-app-message#carousels)을 사용하고 이전 카드가 삭제되거나 새 카드로 교체되는 경우에 유용합니다.
</ParamField>

## 인앱 메시지 이벤트 스트림 생성

### 이벤트 스트림 설정

이벤트 스트림 설정 및 개인화에 대한 안내는 [이벤트 스트림 설정](./event-streams#setup) 지침을 검토하세요. 다음은 이벤트 스트림 구성(3단계)을 위한 IAM 관련 단계를 제공합니다.

## 추적하려는 타겟이 올바르게 설정되었는지 확인

이벤트 스트림 요청 본문에서 사용자 지정 이름을 활용하려면 Block 또는 HTML 에디터에서 새 사용자 지정 이름을 수동으로 지정해야 합니다. 사용자 지정 이름이 릴리스되기 전에 존재했던 인앱 메시지는 각 페이지 또는 블록에 대한 사용자 지정 이름으로 인앱이 업데이트될 때까지 이벤트 스트림에서 `page_name` 및 `target_name` 값을 노출할 수 없습니다.

인앱이 업데이트된 후 그 순간부터 트리거되는 이벤트 스트림 요청은 해당 값에 액세스할 수 있습니다. 언제든지 `page_name` 및 `target_name` 값은 해당 순간의 인앱 사용자 지정 이름 상태를 반영하며, 인앱이 다시 업데이트되면 변경될 수 있습니다.

<Tabs>
  <Tab title="블록 에디터">
    세 가지 이벤트 모두 이 에디터와 함께 사용할 수 있습니다. 블록 에디터를 사용할 때 타겟에 [인앱 클릭 작업](./iam-click-actions)이 포함되어 있는지 확인하세요. 타겟에는 이미지, 버튼, 닫기 버튼 및 배경 블록이 포함됩니다. 텍스트 블록은 현재 클릭 작업을 지원하지 않으며 포함되지 않습니다.

    대시보드 환경에서 혼란을 피하기 위해 타겟 사용자 지정 이름은 고유해야 합니다.
  </Tab>

  <Tab title="HTML 에디터">
    이 에디터에서는 인앱 노출 및 클릭 이벤트만 사용할 수 있습니다. HTML 에디터를 사용할 때 버튼과 이미지뿐만 아니라 모든 요소 유형에서 클릭을 추적할 수 있습니다. 2가지 요구 사항이 있습니다:

    1. 요소에 타겟을 추적하려면 `data-onesignal-unique-label="<insert_value>"` 속성이 있어야 합니다.
    2. 요소에 임베드된 [인앱 JS 라이브러리](./in-app-message-api)(일명 `OneSignalIamAPI`)의 메서드를 호출하는 이벤트 리스너가 적용되어 있어야 합니다.

    참고: 혼란을 피하기 위해 타겟 이름이 고유한지 확인하세요. 사용자 지정 내부 보고와 같이 중요한 고유성의 경우 OneSignal에서 고유성을 보장하는 `target_id`를 사용하세요. 여러 요소에 동일한 레이블로 `data-onesignal-unique-label` 속성을 사용하면 분석이 병합됩니다. 이러한 레이블을 변경하면 이전 데이터는 원래 레이블 아래에 유지되고 새 데이터는 새 레이블에 할당됩니다. 정확한 추적을 위해 `target_id`를 우선시하세요.

    예를 들어:

    <CodeGroup>
      ```html html theme={null}
      // For elements that do something like tag a user or prompt a push do something like this:

      <body>
        <button data-onesignal-unique-label="my-tag-user-button">Tag User</button>
      </body>
      <script>
        document
          .querySelector("button[data-onesignal-unique-label="my-tag-user-button")
          .addEventListener("click", function(e) {
            OneSignalIamApi.tagUser(e, { fiz: "baz" });
           });
      </script>

      // or for elements that don't require any specific functionality of the OneSignalIamApi other than click tracking, just call trackClick

      <body>
        <button data-onesignal-unique-label="my-button">Click Here</button>
      </body>
      <script>
        document
          .querySelector("button[data-onesignal-unique-label="my-button")
          .addEventListener("click", function(e) {
            OneSignalIamApi.trackClick(e);
           });
      </script>
      ```
    </CodeGroup>

    **샘플 입력:**

    <CodeGroup>
      ```json json theme={null}
      {
        "page_name":"{{ event.data.page_name }}",
        "page_id":"{{ event.data.page_id }}",
        "target_id":"{{ event.data.target_id }}",
        "target_name":"{{ event.data.target_name }}",
        "iam_id":"{{ message.id }}",
        "iam_name":"{{ message.name }}",
        "event_kind": "{{ event.kind }}"
      }
      ```
    </CodeGroup>

    **샘플 출력:**

    <CodeGroup>
      ```json json theme={null}
      {
        "page_name" : "html_page",
        "page_id": "d8b28eda-add3-59f8-a12d-07c70642363b" ,
        "target_id": "6bab1bd9-4de6-557b-b5ed-ecb85baed f89",
        "target_name": "my-location-prompt-button",
        "iam_id": "bb6329b6-f81a-44aa-a571-30ef6746de0c",
        "iam_name": "html iam naming",
        "event_kind": "message. iam.clicked"
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>

### 고유 ID 활용

모범 사례: 분석 목적으로 이벤트 스트림을 사용할 때 `message.id`, `page_id` 및 `target_id`를 사용하여 고유성을 검증하세요. 사용자 지정 이름을 사용할 수 있지만 사람이 읽을 수 있는 형식으로 하나의 IAM 내 요소를 구별하는 데 도움이 되도록 의도되었습니다. 여러 인앱 메시지가 있는 경우 `message.id`를 사용하여 구별하세요.

### 블록 에디터에서 명확한 이름 사용

데이터 분석을 단순화하기 위해 모든 인앱 메시지 제목, 카드 및 블록에 의미 있고 고유한 이름을 사용하세요. 캐러셀에서 카드 이름을 바꾸려면 업데이트하려는 탭을 선택하고 카드 탭 옆에 있는 "Options" 드롭다운을 선택합니다. 카드 이름을 바꾸는 옵션이 표시됩니다.

블록 이름을 바꾸려면 각 블록의 오른쪽 상단에 있는 세 점 옵션 메뉴를 선택하여 이름 바꾸기 모달을 엽니다. 모든 사용자 지정 이름은 해당하는 경우 대시보드 보고서 및 이벤트 스트림에 반영됩니다. 사용자 지정 이름은 설정 및 저장되지 않으면 이벤트 스트림에 표시되지 않습니다. 활성 IAM이 있고 최근에 새 IAM 이벤트 스트림을 설정한 경우 더 깔끔한 분석을 위해 이러한 IAM에 의미 있는 사용자 지정 이름이 있는지 확인해야 합니다.

***