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

# 개인화

> OneSignal에서 적절한 개인화 방법을 선택하세요. 속성, Custom Events, API custom_data, Data Feeds, CSV 업로드를 비교하여 Liquid 구문으로 동적 메시지를 전송하는 방법을 알아보세요.

<Frame>
  <iframe width="560" height="315" src="https://www.youtube.com/embed/71gtwxKWlN8?si=mlgmP6eE3652r_cX" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />
</Frame>

개인화를 사용하면 사용자 이름, 장바구니 항목, 계정 잔액, 예약 세부 정보, 일회용 비밀번호 등 동적 데이터를 포함한 메시지를 전송할 수 있습니다.

이 가이드는 다음을 기준으로 적절한 개인화 방법을 선택하는 데 도움을 줍니다:

* 데이터가 어디에 있는지
* 데이터가 지속되어야 하는지
* 메시지가 어떻게 트리거되는지

***

## 개인화 작동 방식

OneSignal의 개인화는 두 부분으로 구성됩니다:

1. **Liquid 구문** – 메시지에서 값이 렌더링되는 방식을 정의합니다
2. **데이터 소스** – 값의 출처를 결정합니다

전송 시점에 OneSignal은 선택된 데이터 소스를 사용하여 Liquid 변수를 해석합니다.

<Info>
  Liquid는 서식 지정과 로직(변수, 루프, 조건문)을 제어합니다. 데이터 소스는 사용 가능한 값을 결정합니다.
</Info>

**예시:**

```liquid Liquid theme={null}
Hi {{ user.tags.first_name }},

Your verification code is {{ message.custom_data.otp }}.
```

* `user.tags.first_name`은 저장된 속성입니다
* `message.custom_data.otp`는 API `custom_data` 필드를 통해 전달됩니다

***

## 메시지 유형별 지원 필드

<Tabs>
  <Tab title="이메일">
    * 제목, 답장 대상 및 사전 헤더
    * 메시지 본문
    * HTML 블록의 이미지 대체. 예시: `<img src="{{image_url}}"/>`
    * URL, 메일 보내기 및 기타 필드와 같은 버튼 블록 작업.
  </Tab>

  <Tab title="푸시">
    * 제목 (`headings`), 부제, 본문 (`contents`)
    * 이미지 URL
    * 실행 URL. 예시: `https://example.com/{{last_category_viewed}}`
    * 추가 `data`는 Liquid 구문을 지원하지 않습니다.
  </Tab>

  <Tab title="SMS">
    * 메시지 본문 (`contents`)
  </Tab>

  <Tab title="인앱 메시지">
    <Warning>
      현재 태그 대체만 지원됩니다.

      태그는 사용자가 앱을 열어 새 세션을 시작하기 전에 설정되어야 합니다. 사용 가능한 태그는 [`getTags` 메서드](./mobile-sdk-reference#gettags)에 있습니다.
    </Warning>

    **블록 편집기:**

    * 태그 대체는 텍스트, 버튼, 이미지 블록에서 작동합니다.

    **HTML 편집기:**

    * 태그 대체는 다음에서 작동합니다:
      * 헤더 `<h*>` 및 `<p>` 태그. 예시: `<h2>Hello {{first_name}}!</h2>`
      * 요소 속성: `["src", "href", "action", "data"]`. 예시: `<img src="{{image_url}}"/>`

    <Note>
      자세한 내용 및 예제는 [인앱 메시지 JavaScript API](./in-app-message-api)를 참조하세요.
    </Note>
  </Tab>

  <Tab title="라이브 활동">
    * `event_updates`, `contents` 및 `headings` 속성 내에서.
  </Tab>
</Tabs>

***

## 데이터 소스

OneSignal은 개인화를 위해 5가지 데이터 소스를 지원합니다. 아래 표를 사용하여 사용 사례에 맞는 소스를 파악하고, 구현 지침은 상세 섹션을 참조하세요.

| 데이터 소스                                          | 내용                                    | 사용 시기                                    | 지속성  | Journeys에서 사용 가능 |
| ----------------------------------------------- | ------------------------------------- | ---------------------------------------- | ---- | ---------------- |
| [**속성**](#properties)                           | 태그, External ID, 구독 데이터, 앱 필드         | OneSignal에 저장된 재사용 가능한 값 (이름, 플랜, 기본 설정) | 예    | 예                |
| [**Custom Events**](#custom-events)             | Journey 진입 또는 Wait Until 시 캡처된 이벤트 속성 | Journeys 내 행동 기반 개인화                     | 이벤트별 | Journey만         |
| [**API `custom_data`**](#api-custom_data)       | Create Message API에서 전달된 키-값 쌍        | 일회성 또는 민감한 값 (OTP, 보안 링크, 장바구니 항목)       | 아니요  | 아니요              |
| [**Data Feeds**](#data-feeds)                   | 전송 시 이루어지는 실시간 API 호출                 | 자주 변경되는 값 (가격, 재고, 계정 잔액)                | 아니요  | 예                |
| [**Dynamic Content CSV**](#dynamic-content-csv) | 대시보드에서 업로드된 CSV                       | 수신자별 콘텐츠가 있는 대량 캠페인                      | 전송별  | 아니요              |

<Warning>
  **피해야 할 일반적인 실수**

  * OTP나 인증 코드와 같은 일회성 값에 속성(Tags)을 사용하는 것 — 대신 `custom_data`를 사용하세요
  * `custom_data`가 Journeys나 이후 메시지에서 사용 가능할 것으로 기대하는 것 — 현재 API 요청에만 존재합니다
  * Custom Event 속성이 이벤트 트리거 Journey 진입 또는 Wait Until 단계 외부에서 사용 가능하다고 가정하는 것
  * 거의 변경되지 않는 정적 데이터에 Data Feeds를 사용하는 것 — 대신 속성을 사용하세요
</Warning>

### 속성

속성에는 사용자 Tags, External ID, Subscription 데이터 및 앱 수준 필드가 포함됩니다.

속성의 특징:

* 지속적
* 재사용 가능
* 메시지, 템플릿, [Journey Webhooks](./journeys-webhook) 및 [Event Streams](./event-streams) 전반에서 사용 가능

**속성을 사용해야 하는 경우:**

* 값이 OneSignal에 존재하는 경우
* 값이 지속적인 경우
* 캠페인 전반에서 재사용하는 경우

<Card title="속성으로 개인화" icon="tag" href="./personalization-properties-and-tags">
  저장된 지속적 속성 데이터를 참조하는 방법을 알아보세요.
</Card>

***

### Custom Events

[Custom Events](./custom-events)는 이벤트 속성을 사용하여 [Journeys](./journeys-overview) 내에서 메시지를 개인화할 수 있습니다.

이벤트가 **Journey를 시작**하거나 **Wait Until 조건과 일치**하면, OneSignal은 해당 이벤트를 저장하여 Liquid를 사용하여 메시지 템플릿에서 속성을 참조할 수 있도록 합니다.

**Custom Events를 사용해야 하는 경우:**

* Journeys를 사용한 이벤트 트리거 메시지
* 메시지에 이벤트별 데이터가 반영되어야 하는 경우

<Warning> Journey 진입 또는 Wait Until 단계를 트리거하는 이벤트만 개인화를 위해 저장됩니다. 이러한 시점 외에 전송된 이벤트는 Journey 메시지에서 사용할 수 없습니다. </Warning>

<Card title="Custom Event 개인화" icon="bolt" href="./personalization-custom-event">
  Journeys에서 이벤트 속성을 사용하는 전체 가이드입니다.
</Card>

***

### API `custom_data`

[Create Message API](/reference/create-message)의 `custom_data` 필드를 사용하면 백엔드에서 메시지별 값을 전송할 수 있습니다.

이 데이터는:

* 현재 요청에만 존재합니다
* OneSignal에 저장되지 않습니다
* Journeys에서 사용할 수 없습니다

**`custom_data`를 사용해야 하는 경우:**

* 일회성 또는 민감한 값 전송(OTP, 보안 링크)
* 배열 전달(장바구니 항목, 주문 항목, 리더보드 점수)
* 트랜잭션 또는 API 트리거 메시지 전송

<Card title="API custom_data로 개인화" icon="code" href="./personalization-api-custom-data">
  일시적 개인화 데이터를 전달하는 방법을 알아보세요.
</Card>

***

### Data Feeds

[Data Feeds](./data-feeds)는 전송 시점에 API를 호출하고 응답을 메시지에 주입합니다.

**Data Feeds를 사용해야 하는 경우:**

* 전달 시점의 최신 값이 필요한 경우
* 데이터가 백엔드에 있는 경우
* 전송 간에 값이 변경될 수 있는 경우

<Card title="Data Feeds" icon="cloud-arrow-up" href="./data-feeds">
  전송 시점에 실시간 백엔드 데이터를 메시지에 가져옵니다.
</Card>

***

### Dynamic Content CSV

CSV 파일을 OneSignal 대시보드에 업로드하고 Liquid를 사용하여 해당 값을 참조합니다.

**CSV를 사용해야 하는 경우:**

* 각 수신자별로 대량 캠페인의 다른 섹션을 맞춤화하는 경우
* 각 수신자의 번역 또는 사용자 지정 데이터를 CSV 파일로 내보낼 수 있는 경우
* API를 사용하지 않으려는 경우

<Card title="Dynamic Content CSV" icon="file-csv" href="./dynamic-content">
  CSV 업로드를 사용하여 대시보드 캠페인을 개인화합니다.
</Card>

***

## 상세 가이드

단계별 구현 세부 정보 및 고급 예제는 아래 가이드를 사용하세요.

<Columns cols={2}>
  <Card title="Liquid 구문 사용" icon="droplet" href="./using-liquid-syntax">
    Liquid를 사용하여 메시지에 동적 데이터를 삽입하는 방법을 알아보세요. 변수, 조건문, 루프, 필터, 서식 지정 및 일반적인 개인화 패턴을 다룹니다.
  </Card>

  <Card title="Data Feeds" icon="cloud-arrow-up" href="./data-feeds">
    전송 시점에 자체 API에서 실시간 데이터를 가져옵니다. 메시지 콘텐츠가 잔액, 가용성 또는 가격과 같은 실시간 백엔드 값에 의존하는 경우 Data Feeds를 사용하세요.
  </Card>

  <Card title="Custom Events 개인화" icon="bolt" href="./personalization-custom-event">
    사용자가 Journey에 진입하거나 진행할 때 캡처된 이벤트 속성을 사용하여 Journey 메시지를 개인화합니다. 행동 기반 및 이벤트 기반 워크플로에 이상적입니다.
  </Card>

  <Card title="속성 및 Tags" icon="tag" href="./personalization-properties-and-tags">
    저장된 사용자, Subscription, 메시지 및 앱 속성을 사용하여 메시지, 템플릿, Journey Webhooks 및 Event Streams 전반에서 콘텐츠를 개인화합니다.
  </Card>

  <Card title="API custom_data" icon="code" href="./personalization-api-custom-data">
    Create Message API를 사용하여 백엔드에서 메시지별 및 일시적 데이터를 전달합니다. OTP, 장바구니, 배열 및 대량 트랜잭션 개인화에 가장 적합합니다.
  </Card>

  <Card title="Dynamic Content CSV" icon="file-csv" href="./dynamic-content">
    대시보드에서 CSV 파일을 업로드하여 대규모 캠페인을 개인화합니다. 각 행은 수신자에 매핑되며 Liquid를 사용하여 참조할 수 있습니다.
  </Card>
</Columns>

### 튜토리얼

이 가이드는 개인화를 실제로 구현하는 방법을 보여줍니다.

<Columns cols={2}>
  <Card title="인증, Magic Link 및 OTP" icon="key" href="./example-verification-magic-link-otp">
    일회용 비밀번호, Magic Link 또는 API 기반 개인화를 사용한 사용자 지정 URL로 보안 인증 메시지를 전송합니다.
  </Card>

  <Card title="장바구니 이탈 Journey" icon="cart-shopping" href="./abandoned-cart">
    장바구니 활동을 감지하고, 비활성을 기다리고, 개인화된 알림을 보내고, 구매 즉시 사용자를 종료하는 자동화된 Journey를 구축합니다.
  </Card>

  <Card title="예약 확인" icon="calendar" href="./booking-confirmations">
    실시간 예약 상태를 기반으로 Custom Events, Journeys 및 Data Feeds를 사용하여 예약 확인 및 복구 메시지를 전송합니다.
  </Card>

  <Card title="트랜잭션 메시지" icon="receipt" href="./transactional-messages">
    API 및 자동화를 사용하여 채널 전반에서 영수증, 알림, 확인 및 기타 트랜잭션 메시지를 전송하는 방법을 알아보세요.
  </Card>

  <Card title="인앱 개인화 예제" icon="mobile" href="./personalization-properties-and-tags">
    다양한 사용자 및 세그먼트를 위해 Tags 및 속성을 사용하여 인앱 메시지를 개인화하는 실용적인 예제를 확인하세요.
  </Card>
</Columns>