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

# 속성을 사용한 개인화

> 미리 정의된 속성과 사용자 정의 데이터 Tags를 사용하여 OneSignal 메시지를 개인화하세요. Liquid 구문을 통해 이메일, 푸시, SMS, 웹훅 전반에서 사용자, 구독, Journey, 메시지, 템플릿, 앱 수준의 데이터를 활용할 수 있습니다.

속성(예: 사용자 Tags 및 External ID와 같은 식별자)을 사용하여 [Liquid 구문](./using-liquid-syntax)으로 메시지와 전송 페이로드를 개인화하세요.

OneSignal은 사용자, 구독, Journey, 메시지, 템플릿, 앱 또는 조직에 이미 저장된 데이터를 사용하여 **전송 시점에** Liquid 플레이스홀더를 렌더링합니다. 이 데이터를 사용하여 메시지, [Journey 웹훅](./journeys-webhook), [Event Streams](./event-streams)를 개인화할 수 있습니다.

***

## 속성 개인화를 사용하는 시기

OneSignal에 이미 존재하는 데이터(가장 일반적으로 사용자 Tags, External ID, 이메일이나 전화번호와 같은 구독 필드)를 사용하여 전송 시점에 콘텐츠를 렌더링하려면 속성 개인화를 사용하세요.

다음과 같은 경우에 적합합니다:

* 데이터가 이미 OneSignal에 저장되어 있는 경우
* 메시지 전송 시 Liquid 플레이스홀더가 자동으로 대체되기를 원하는 경우
* 전송 시점에 새로운 데이터를 가져오거나 계산할 필요가 없는 경우

<Note>
  전송 시점에 값을 가져오거나 계산해야 하는 경우(예: 실시간 가격이나 재고), [Data Feeds](./data-feeds) 또는 [`custom_data`를 사용하는 API](./personalization-api-custom-data)를 사용하세요.

  사용자가 Journey에 진입하거나 진행하게 만든 이벤트에서 값이 제공되는 경우, [Custom Event 개인화](./personalization-custom-event)를 사용하세요.
</Note>

### 채널 지원

각 채널은 특정 속성 유형과 필드를 지원합니다.

<Tabs>
  <Tab title="이메일">
    다음에서 [사용자 및 구독 속성](#user-&-subscription-properties)을 지원합니다:

    * 제목, 회신 주소, 프리헤더
    * 메시지 본문
    * HTML 속성(예: `<img src="{{ image_url }}" />`)
    * 버튼 액션(URL, mailto 등)
  </Tab>

  <Tab title="푸시">
    다음에서 [사용자 및 구독 속성](#user-&-subscription-properties)을 지원합니다:

    * 제목(`headings`), 부제목, 본문(`contents`)
    * 이미지 URL
    * 실행 URL: `https://example.com/{{last_category_viewed}}`

    <Warning>
      `data`(추가 데이터) 필드는 Liquid 구문을 지원하지 않습니다.
    </Warning>
  </Tab>

  <Tab title="SMS">
    다음에서 [사용자 및 구독 속성](#user-&-subscription-properties)을 지원합니다:

    * 메시지 본문(`contents`)
  </Tab>

  <Tab title="인앱 메시지">
    태그 대체만 지원됩니다. 속성, Custom Events 및 기타 데이터 소스는 현재 사용할 수 없습니다.

    * Tags는 사용자가 새 앱 세션을 시작하기 전에 설정되어야 합니다.
    * 테스트 전송 흐름을 사용할 때 태그 대체가 표시되지 않을 수 있습니다.

    **블록 에디터:** 텍스트, 버튼, 이미지 블록
    **HTML 에디터:** 텍스트 요소 및 속성(`src`, `href`, `action`, `data`)
  </Tab>

  <Tab title="라이브 액티비티">
    다음에서 [사용자 및 구독 속성](#user-&-subscription-properties)을 지원합니다:

    * `event_updates`
    * `contents`
    * `headings`
  </Tab>
</Tabs>

***

## 속성 개인화 작동 방식

OneSignal은 메시지를 받는 사용자와 구독에 해당하는 속성 값으로 Liquid 플레이스홀더를 대체합니다.

```liquid Liquid theme={null}
Hi {{ first_name | default: "friend" }}!
Congrats on reaching level {{ level | default: "1" }}!
```

사용자에게 `first_name: Jon` 및 `level: 5` Tags가 설정되어 있으면 다음과 같이 표시됩니다:

```liquid Text theme={null}
Hi Jon!
Congrats on reaching level 5!
```

## 사용자에게 설정된 Tags가 없으면 대신 기본값이 표시됩니다.

## 속성 Liquid 객체 참조

이 섹션에서 Liquid에서 사용할 수 있는 정확한 객체와 필드 이름을 확인하세요.

### 사용자 및 구독 속성

사용자 수준 데이터에는 `user`를 사용합니다. 이메일 주소나 전화번호와 같은 채널별 값이 필요한 경우 `subscription`을 사용합니다.

<ParamField body="user.tags">
  사용자의 [Tags](./add-user-data-tags)입니다. 여러 방법으로 Tags를 참조할 수 있습니다:

  * `key`를 직접 사용하거나 `tags` 뒤에 키를 배치합니다.
  * 설정된 Tags 예시: `first_name: Jon, level: 5`

  ```liquid Liquid theme={null}
  Your first name is {{ first_name }}.
  Your first name is {{ user.tags.first_name }}.
  Your level is {{ level }}.
  Your level is {{ user.tags.level }}.
  ```

  * for 루프 구문으로 Tags를 반복합니다. 이 예시는 쉼표로 구분된 key:value 쌍을 출력합니다.

  ```liquid Liquid theme={null}
  {% for tag in user.tags %}
  {{ tag[0] }}: {{ tag[1] }}
  {% unless forloop.last %},
  {% endunless %}{% endfor %}
  ```
</ParamField>

<ParamField body="user.external_id">
  사용자의 [External ID](./users#external-id)입니다.

  ```liquid Liquid theme={null}
  Your user ID is {{ user.external_id }}.
  Your user ID is {{ subscription.external_id }}.
  ```
</ParamField>

<ParamField body="user.onesignal_id">
  사용자의 [OneSignal ID](./users)입니다.

  ```liquid Liquid theme={null}
  Your OneSignal user ID is {{ user.onesignal_id }}.
  ```
</ParamField>

<ParamField body="subscription.email">
  메시지를 받는 이메일 구독의 이메일 주소입니다.

  ```liquid Liquid theme={null}
  Thanks for subscribing with email {{ subscription.email }}.
  ```
</ParamField>

<ParamField body="subscription.phone_number">
  메시지를 받는 SMS 구독의 전화번호입니다.

  ```liquid Liquid theme={null}
  Thanks for subscribing with phone number {{ subscription.phone_number }}.
  ```
</ParamField>

<ParamField body="user.language">
  사용자의 언어 코드입니다.

  ```liquid Liquid theme={null}
  Preferred language: {{ user.language }}
  Preferred language: {{ subscription.language }}
  ```
</ParamField>

<ParamField body="user.subscriptions">
  사용자의 [Subscriptions](./subscriptions)입니다.

  * for 루프 구문으로 Subscriptions를 반복합니다.
  * 이 예시는 각 구독의 토큰과 ID를 쉼표로 구분하여 출력합니다.

  ```json JSON theme={null}
  {
    "subscriptions": "{% for subscription in user.subscriptions %}{% if subscription.subscription_token %}{{ subscription.subscription_token }}: {{ subscription.id }}{% unless forloop.last %}, {% endunless %}{% endif %}{% endfor %}"
  }
  ```
</ParamField>

<ParamField body="subscription.unsubscribe_token">
  [토큰으로 이메일 구독 해제 API](/reference/unsubscribe-with-token)에 사용되는 토큰입니다.

  ```liquid theme={null}
  Unsubscribe: https://your-domain.com/unsubscribe?token={{ subscription.unsubscribe_token }}
  ```
</ParamField>

### Journey 속성

`journey` 객체를 사용하면 Journey 이름을 참조하거나 Journey의 [Custom Event 개인화](./personalization-custom-event)에 접근할 수 있습니다.

<ParamField body="journey.name">
  Journey의 이름입니다.

  ```json JSON theme={null}
  {
    "journey_name": "{{ journey.name }}"
  }
  ```
</ParamField>

### 메시지 속성

`message` 객체는 [Event Streams](./event-streams)에 유용한 메시지 ID, 이름, 템플릿 ID에 대한 접근과 백엔드에서 전송되는 메시지를 개인화하기 위한 [custom\_data](./personalization-api-custom-data)에 대한 접근을 제공합니다.

<ParamField body="message.id">
  OneSignal이 설정한 메시지 ID입니다.

  ```json theme={null}
  {
    "message_id": "{{ message.id }}"
  }
  ```
</ParamField>

<ParamField body="message.name">
  발신자가 설정한 메시지 이름입니다.

  ```json theme={null}
  {
    "message_name": "{{ message.name }}"
  }
  ```
</ParamField>

<ParamField body="message.template_id">
  OneSignal이 설정한 템플릿 ID입니다.

  ```json theme={null}
  {
    "template_id": "{{ message.template_id }}"
  }
  ```
</ParamField>

### 템플릿 속성

`template` 객체는 메시지를 보내는 데 사용된 [Template](./templates)의 템플릿 ID와 이름에 대한 접근을 제공합니다. 이는 [Event Streams](./event-streams)에 유용할 수 있습니다.

<ParamField body="template.id">
  OneSignal이 설정한 템플릿 ID입니다.

  ```json theme={null}
  {
    "template_id": "{{ template.id }}"
  }
  ```
</ParamField>

<ParamField body="template.name">
  발신자가 설정한 템플릿 이름입니다.

  ```json theme={null}
  {
    "template_name": "{{ template.name }}"
  }
  ```
</ParamField>

***

### 앱 및 조직 속성

`app` 및 `org` 객체는 메시지를 보낸 [앱과 조직](./apps-organizations)에 대한 세부 정보를 제공합니다. 이는 [Event Streams](./event-streams)에 유용할 수 있습니다.

<ParamField body="app.id">
  OneSignal이 설정한 앱 ID입니다.

  ```json theme={null}
  {
    "app_id": "{{ app.id }}"
  }
  ```
</ParamField>

<ParamField body="app.name">
  앱 소유자가 설정한 앱 이름입니다.

  ```json theme={null}
  {
    "app_name": "{{ app.name }}"
  }
  ```
</ParamField>

<ParamField body="org.id">
  OneSignal이 설정한 조직 ID입니다.

  ```json theme={null}
  {
    "org_id": "{{ org.id }}"
  }
  ```
</ParamField>

<ParamField body="org.name">
  조직 소유자가 설정한 조직 이름입니다.

  ```json theme={null}
  {
    "org_name": "{{ org.name }}"
  }
  ```
</ParamField>

***

## 예시: Tags를 사용한 장바구니 이탈

이 예시에서는 사용자 Tags를 사용하여 장바구니 이탈 메시지를 개인화하는 방법을 보여줍니다. [장바구니 이탈 튜토리얼](./abandoned-cart)을 기반으로 합니다.

**설정된 Tags 예시:**

```json JSON theme={null}
{
  "cart_updated": "unix_timestamp_seconds",
  "product_image": "https://i.imgur.com/ssPCfbC.png",
  "product_name": "24 Pack of Acorns",
  "product_quantity": "1",
  "product_price": "$12.99",
  "cart_items_count": "4",
  "cart_url": "https://yourdomain.com/cart"
}
```

### 이메일 템플릿

<Steps>
  <Step title="새 이메일 템플릿 생성">
    **Messages > Templates > New Email Template**로 이동하여 드래그 앤 드롭 에디터를 엽니다.
  </Step>

  <Step title="레이아웃 구조 추가">
    5개의 행을 생성합니다:

    * 행 1, 2, 4: **Paragraph** 블록이 있는 1열
    * 행 3: **HTML | Paragraph | Paragraph | Paragraph**가 있는 4열
    * 행 5: **Button** 블록이 있는 1열

    <Frame caption="장바구니 이탈용 기본 이메일 템플릿">
      <img src="https://mintcdn.com/onesignal/v-hm59YoewwF90UX/images/email/starter-template-abandoned-cart.png?fit=max&auto=format&n=v-hm59YoewwF90UX&q=85&s=551e9ec4618f64fdc0b6ab610a537c48" width="2968" height="2124" data-path="images/email/starter-template-abandoned-cart.png" />
    </Frame>
  </Step>

  <Step title="Paragraph 블록에 Liquid 추가">
    행 1에 다음을 추가합니다:

    ```liquid Liquid theme={null}
    We're holding onto {{cart_items_count}} items in your cart, but don't wait too long, other squirrels are getting ahead!
    ```

    행 2에 사용자가 보고 있는 내용에 대한 설명을 추가합니다:

    ```liquid Text theme={null}
    Currently in your cart:
    ```

    행 4에 추가 CTA를 넣습니다:

    ```liquid Text theme={null}
    Checkout now while supplies last!
    ```
  </Step>

  <Step title="가장 최근 항목 표시">
    행 3에서 4개의 열을 구성합니다:

    **열 1 (HTML 블록):**

    ```html HTML theme={null}
    <img src="{{product_image}}" alt="Image" style="max-width:100%;" />
    ```

    **열 2-4 (텍스트 블록):**

    * 열 2: `{{product_name}}`
    * 열 3: `{{product_quantity}}`
    * 열 4: `{{product_price}}`
  </Step>

  <Step title="버튼에 장바구니 URL 추가">
    행 5의 **Button** 블록에서 액션 URL을 다음으로 설정합니다:

    ```liquid theme={null}
    {{cart_url}}
    ```

    <Frame caption="스타일링 없는 장바구니 이탈 기본 이메일 템플릿 완성본">
      <img src="https://mintcdn.com/onesignal/v-hm59YoewwF90UX/images/email/finished-template-abandoned-cart-tags.png?fit=max&auto=format&n=v-hm59YoewwF90UX&q=85&s=a46cb86b4725c27c360b9f7cd96ab305" width="2968" height="2124" data-path="images/email/finished-template-abandoned-cart-tags.png" />
    </Frame>
  </Step>

  <Step title="템플릿 테스트 및 미리보기">
    **테스트 및 미리보기** 버튼을 사용하여 자신에게 테스트 이메일을 보냅니다.

    * 이메일 구독에 Tags가 설정되어 있는지 확인하세요.

    <Frame caption="Tags가 적용된 이메일 미리보기">
      <img src="https://mintcdn.com/onesignal/v-hm59YoewwF90UX/images/email/test-email-with-tags.png?fit=max&auto=format&n=v-hm59YoewwF90UX&q=85&s=307a846a3fec6676658ac4c653590110" width="2968" height="2124" data-path="images/email/test-email-with-tags.png" />
    </Frame>
  </Step>

  <Step title="템플릿 스타일링">
    <Check>성공! 이제 템플릿에 자체 스타일을 적용할 수 있습니다. [드래그 앤 드롭으로 이메일 디자인하기](./design-emails-with-drag-and-drop)를 참조하세요.</Check>
  </Step>
</Steps>

### 푸시 템플릿

푸시 알림은 공간이 제한되어 있으므로 하나의 항목을 표시하고 총 개수를 언급합니다.

**메시지 필드:**

[조건문](./using-liquid-syntax#if-elsif-else)을 사용하여 올바른 문법으로 항목과 개수를 표시합니다.

```liquid Liquid theme={null}
{% assign item_count = cart_items_count | plus: 0 %}
{% if item_count == 1 %}
You left {{product_name}} in your cart.
{% endif %}
{% if item_count == 2 %}
You left {{product_name}} and {{item_count | minus: 1}} more item in your cart.
{% endif %}
{% if item_count > 2 %}
You left {{product_name}} and {{item_count | minus: 1}} more items in your cart.
{% endif %}
```

**이미지 필드:**

```liquid Liquid theme={null}
{{product_image | default: "https://i.imgur.com/ssPCfbC.png"}}
```

**실행 URL 필드:**

```liquid theme={null}
{{cart_url | default: "https://yourdomain.com/cart"}}
```

<Frame caption="테스트 및 미리보기로 푸시 템플릿 개인화 미리보기">
  <img src="https://mintcdn.com/onesignal/Up-pAJT_jbhthm6E/images/push/preview-push-template-personalization-with-test-preview.png?fit=max&auto=format&n=Up-pAJT_jbhthm6E&q=85&s=97db90a05acdf4ed30f54a76b1d63b98" width="2880" height="2036" data-path="images/push/preview-push-template-personalization-with-test-preview.png" />
</Frame>

<Check>성공! 이제 더 많은 Templates를 생성하고 [장바구니 이탈 Journey](./abandoned-cart)에서 사용할 수 있습니다.</Check>

***

## 예시: 데이터 태그로 인앱 메시지 개인화하기

이 예시는 데이터 태그로 개인화된 보상 인앱 메시지를 보여줍니다. 인앱 메시지는 데이터 태그 값을 여러 블록 유형에 대체합니다.

구성된 메시지에서:

* **텍스트 블록** — 완료된 레벨과 해당 레벨의 보상을 표시
* **이미지 블록** — 해당 보상에 대한 이미지를 기본 이미지와 함께 표시
* **버튼 2 텍스트** — 보상 값을 표시하고, 기본값은 `100`
* **배경 이미지** — 데이터 태그 값에서 설정

<Frame caption="텍스트, 이미지 및 버튼 블록에 데이터 태그 대체가 구성된 인앱 메시지 편집기">
  <img src="https://mintcdn.com/onesignal/56ctKxZSV4m5VEkn/images/docs/b697ab5-config1.png?fit=max&auto=format&n=56ctKxZSV4m5VEkn&q=85&s=c40e541c296b138a7f04ac561b3b0c64" alt="" width="872" height="968" data-path="images/docs/b697ab5-config1.png" />
</Frame>

메시지는 세션 시작 시 사용자의 현재 데이터 태그 값을 사용하여 렌더링됩니다:

<Frame caption="데이터 태그에서 대체된 값으로 사용자에게 표시된 인앱 메시지">
  <img src="https://mintcdn.com/onesignal/tc0EvmtSSX56SX0c/images/docs/973f097-JustTheIAMTagSub.png?fit=max&auto=format&n=tc0EvmtSSX56SX0c&q=85&s=0626ef7b31dfbfece633e74b072fbff5" style={{ width:"100%" }} width="338" height="607" data-path="images/docs/973f097-JustTheIAMTagSub.png" />
</Frame>

<Note>
  지원되는 블록, 속성 및 타이밍 규칙에 대해서는 위의 [채널 지원](#채널-지원)에서 **인앱 메시지** 탭을 참조하세요. 거기서 다시 강조할 두 가지 사항:

  * **데이터 태그는 사용자가 새 앱 세션을 시작하기 전에 설정되어야 합니다.** 세션 중간에 업데이트된 데이터 태그는 해당 세션에 표시되는 인앱 메시지에서 렌더링되지 않습니다.
  * **데이터 태그 대체는 "테스트 메시지 보내기" 테스트 발송에서 렌더링되지 않습니다.** 대체가 작동하는지 확인하려면 실제 세션에서 메시지를 트리거하세요.
  * [속성 대체](./using-liquid-syntax#property-include)는 인앱 메시지에서 지원되지 않습니다.
</Note>

***

## 관련 페이지

<Columns cols={2}>
  <Card title="메시지 개인화" href="./message-personalization" icon="sparkles">
    Custom Events 대 기타 방법의 사용 시기를 포함한 OneSignal의 모든 개인화 옵션 개요입니다.
  </Card>

  <Card title="Tags" href="./add-user-data-tags" icon="tag">
    SDK, API 또는 CSV 가져오기를 통해 사용자에게 Tags를 설정하는 방법을 알아보세요.
  </Card>

  <Card title="Liquid 구문 사용" href="./using-liquid-syntax" icon="droplet">
    필터, 조건문, 루프, 문자열 조작이 포함된 완전한 Liquid 참조 문서입니다.
  </Card>

  <Card title="Templates" href="./templates" icon="file">
    Journeys에서 사용할 재사용 가능한 메시지 Templates를 생성하고 관리하세요.
  </Card>

  <Card title="장바구니 이탈 튜토리얼" href="./abandoned-cart" icon="cart-shopping">
    Tags와 속성을 사용하여 장바구니 이탈 Journey를 구축합니다.
  </Card>
</Columns>

<Info>
  도움이 필요하신가요?

  지원 팀과 채팅하거나 `support@onesignal.com`으로 이메일을 보내주세요.

  다음을 포함해 주세요:

  * 발생한 문제의 세부 정보 및 재현 단계(가능한 경우)
  * OneSignal 앱 ID
  * External ID 또는 Subscription ID(해당하는 경우)
  * OneSignal 대시보드에서 테스트한 메시지의 URL(해당하는 경우)
  * 관련 [로그 또는 오류 메시지](/docs/ko/capturing-a-debug-log)

  기꺼이 도와드리겠습니다!
</Info>

***