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

# CSV를 사용한 동적 콘텐츠

> OneSignal에서 CSV 업로드와 Liquid 구문을 사용하여 대규모로 푸시, 이메일 및 SMS 메시지를 개인화합니다.

OneSignal은 대규모로 [메시지 콘텐츠를 개인화](./message-personalization)하는 여러 방법을 제공합니다. 이 가이드는 푸시, 이메일 및 SMS용 OneSignal 대시보드에 있는 CSV 업로드 기능을 갖춘 동적 콘텐츠 사용에 중점을 둡니다.

**주요 이점:**

* **CSV를 사용하여 대규모로 개인화** – 하나의 메시지, 모두를 위한 맞춤형 경험
* **다국어 지원** – 사용자별로 자동 언어 전환
* **동적 개인화** – 사용자 속성(언어, 지역, 캠페인 ID)에 따라 콘텐츠 조정
* **팀 협업** – 비기술 사용자가 CSV 파일에서 콘텐츠 편집
* **HTML 삽입(이메일)** – CSV 셀에 HTML 마크업을 포함하여 풍부한 이메일 콘텐츠를 동적으로 구성
* **크로스 채널 호환성** – 채널 전반에서 CSV 로직 재사용

**일반적인 사용 사례:**

* 다국어 온보딩 또는 마케팅
* 지역별 프로모션
* 위치별 이벤트 공지
* 캠페인 기반 개인화

***

## CSV를 사용한 동적 콘텐츠 설정 단계

**빠른 참조:**

1. 콘텐츠 변형이 포함된 CSV 파일을 만듭니다.
2. Liquid 구문의 `dynamic_content` 속성을 사용하여 CSV 데이터를 메시지에 매핑합니다.
3. OneSignal 대시보드에서 새 메시지 또는 [템플릿](./templates)을 만듭니다.
4. **동적 콘텐츠** 또는 **개인화** 버튼을 선택합니다.
5. CSV 파일을 업로드하고 메시지를 전송합니다.

### CSV 요구 사항 및 설정

* **파일 크기:** 200 KB 미만
* **열 헤더:**
  * 태그 키를 위해 첫 번째 열 헤더를 예약하거나 섹션을 참조하기 위해 비워 둡니다
  * 영숫자 문자 및 밑줄만
  * 공백 대신 밑줄(`_`) 사용
* **인코딩:** UTF-8

빈 CSV로 시작하거나 제공된 템플릿을 사용합니다. 메시지 및 템플릿 편집기에서 **동적 콘텐츠** 또는 **개인화** 버튼을 선택하면 템플릿이 제공됩니다.

<Frame caption="메시지 편집기에 있는 동적 콘텐츠 버튼.">
  <img src="https://mintcdn.com/onesignal/jBdBk5XvQR5eKOks/images/docs/772f91e24ebca83a05d4e96819a41ec58d5ca0acd3a715e971c4a43ba7654494-Screenshot_2025-02-10_at_5.23.32_PM.png?fit=max&auto=format&n=jBdBk5XvQR5eKOks&q=85&s=c51a6fcb07f7aab797cbfe74423530cb" alt="OneSignal 메시지 편집기의 동적 콘텐츠 버튼" width="1960" height="380" data-path="images/docs/772f91e24ebca83a05d4e96819a41ec58d5ca0acd3a715e971c4a43ba7654494-Screenshot_2025-02-10_at_5.23.32_PM.png" />
</Frame>

사용 가능한 템플릿:

* **다국어** – 언어별로 콘텐츠 현지화
* **콘텐츠 개인화** – 데이터 태그별로 콘텐츠 사용자 지정

<Frame caption="OneSignal 대시보드의 CSV 템플릿 옵션.">
  <img src="https://mintcdn.com/onesignal/YOTSrtBSoqdrJ37A/images/docs/47f48b79aa100bd5d2c59a418216bafba75daaa92d0bf939dcd3ccceca39cd7c-Screenshot_2025-02-10_at_5.26.15_PM.png?fit=max&auto=format&n=YOTSrtBSoqdrJ37A&q=85&s=87947eb40093580c8589cf7eb4183564" alt="다국어 및 콘텐츠 개인화 템플릿을 보여주는 CSV 템플릿 옵션" width="1986" height="870" data-path="images/docs/47f48b79aa100bd5d2c59a418216bafba75daaa92d0bf939dcd3ccceca39cd7c-Screenshot_2025-02-10_at_5.26.15_PM.png" />
</Frame>

#### CSV 예제

이 가이드는 다음 CSV 데이터 예제를 사용합니다.

<Tabs>
  <Tab title="다국어 템플릿 예제">
    * 열 헤더를 [지원되는 언어 코드](./multi-language-messaging#supported-languages)에 매핑합니다.
    * 각 언어 코드에 대해 각 행에 번역을 추가합니다.
    * 여러 섹션(예: 이메일)이 있는 경우 첫 번째 열을 섹션 이름으로 지정합니다.

    이 예에는 다음이 포함됩니다:

    * 3개의 언어: 영어, 스페인어, 프랑스어.
    * 2개의 섹션: "section\_1" 및 "section\_2".

    <Frame caption="사용자 언어 속성을 콘텐츠와 일치시키는 다국어 CSV (VLOOKUP과 유사).">
      <img src="https://mintcdn.com/onesignal/0qspEXXeJ8zJbkJ-/images/docs/8716e43deead16759c2500d85900d2d1be8b6a9c51e0477160569b05534a58fb-Screenshot_2025-02-10_at_8.37.25_PM.png?fit=max&auto=format&n=0qspEXXeJ8zJbkJ-&q=85&s=4a20651cf2949bad117b8a9fda432536" alt="언어 코드를 열 헤더로, 번역 콘텐츠를 행으로 가진 다국어 CSV" width="1438" height="220" data-path="images/docs/8716e43deead16759c2500d85900d2d1be8b6a9c51e0477160569b05534a58fb-Screenshot_2025-02-10_at_8.37.25_PM.png" />
    </Frame>
  </Tab>

  <Tab title="콘텐츠 개인화 템플릿 예제">
    * 첫 번째 열 헤더를 태그 키에 매핑하고 기본 행을 참조하려는 값에 매핑합니다. 사용자에게 태그를 추가하는 방법에 대한 자세한 내용은 [태그](./add-user-data-tags)를 참조하세요.
    * 나머지 열 헤더를 개인화하려는 섹션 또는 구성 요소에 매핑합니다.

    이 예에서:

    * 태그 키는 `campaign_id`이며 가능한 값은 `A`와 `B`입니다.
    * 3개의 구성 요소가 있습니다: "title", "message", "url".

    <Frame caption="campaign_id 데이터 태그를 사용한 개인화 CSV.">
      <img src="https://mintcdn.com/onesignal/3zq1PvSaqvUE2bIx/images/docs/2d49628c7c891801e50b7f397442f5887e7b776897d24788be16887ed191f631-Screenshot_2025-04-10_at_9.47.35_AM.png?fit=max&auto=format&n=3zq1PvSaqvUE2bIx&q=85&s=23ec0fe2224cc3103e7a7c62168dd050" alt="campaign_id 태그와 title, message, url 열을 사용한 콘텐츠 개인화 CSV" width="1406" height="160" data-path="images/docs/2d49628c7c891801e50b7f397442f5887e7b776897d24788be16887ed191f631-Screenshot_2025-04-10_at_9.47.35_AM.png" />
    </Frame>

    <Warning>
      **중요:** CSV 헤더에서 공백과 영숫자가 아닌 문자를 제거하거나
      Liquid에서 해시 표기법을 사용하세요.
    </Warning>

    <Frame caption="Liquid 구문을 사용하여 태그를 참조하는 상세한 CSV 예제.">
      <img src="https://mintcdn.com/onesignal/tc0EvmtSSX56SX0c/images/docs/9352ff1-event_translation.csv.png?fit=max&auto=format&n=tc0EvmtSSX56SX0c&q=85&s=e71b92286f500fc201b95bafa2b38a85" alt="태그 기반 개인화를 위한 Liquid 구문 참조를 보여주는 상세한 CSV 예제" width="3189" height="2646" data-path="images/docs/9352ff1-event_translation.csv.png" />
    </Frame>
  </Tab>
</Tabs>

### CSV 데이터를 메시지 콘텐츠에 매핑

[Liquid 구문](./using-liquid-syntax)을 사용하여 `dynamic_content` 속성을 사용하여 메시지에서 CSV 데이터를 참조합니다:

```liquid theme={null}
<!-- 옵션 1: 구성 요소로 먼저 접근 -->
{{dynamic_content.file_name.message_component[user_property]}}

<!-- 옵션 2: 사용자 속성으로 먼저 접근 -->
{{dynamic_content.file_name[user_property].message_component}}
```

**매개변수:**

* `dynamic_content` – CSV 데이터를 참조하는 데 사용되는 속성 이름
* `file_name` – CSV 파일 이름(`.csv` 확장자 제외)
* `message_component` – 개인화하려는 특정 메시지 구성 요소. CSV 열 헤더 또는 첫 번째 행의 정적 텍스트입니다.
* `user_property` – 참조하려는 [사용자 속성](./message-personalization#properties).

**대체 콘텐츠:**

CSV 조회 또는 동적 콘텐츠가 실패할 경우 메시지가 렌더링되도록 항상 하드코딩된 문자열 `default` 대체를 사용하세요.

```liquid 대체를 위한 Liquid 구문 theme={null}
{{ dynamic_content.my_template.header[user.language] | default: "최신 업데이트에 오신 것을 환영합니다" }}
```

이것은 CSV 조회 또는 동적 콘텐츠가 실패하면 메시지가 대체 텍스트 `"최신 업데이트에 오신 것을 환영합니다"`를 렌더링한다는 것을 의미합니다.

이것은 다음을 보장합니다:

* 사용 가능한 경우 동적 콘텐츠가 사용됩니다
* 동적 콘텐츠가 실패하면 하드코딩된 메시지가 나타납니다
* 사용자가 빈 콘텐츠를 받지 않습니다

<Tabs>
  <Tab title="다국어 메시지 예제">
    ```csv translations.csv theme={null}
    ,en,es,fr
    section_1,Hello,Hola,Bonjour
    section_2,Thanks for shopping with us...,Gracias por comprar con nosotros...,Merci pour votre achat avec nous...
    ```

    * `file_name`은 `translations.csv`입니다.
    * `message_component`는 첫 번째 열의 행 `section_1`과 `section_2`에 있습니다.
    * `user_property`는 언어 코드와 일치하는 열 헤더입니다. `user.language` [속성](./message-personalization#properties)을 사용하여 사용자에서 이를 참조할 수 있습니다.

    ```liquid 다국어 메시지를 위한 기본 Liquid 구문 theme={null}
    {{dynamic_content.translations.section_1[user.language]}}
    {{dynamic_content.translations.section_2[user.language]}}
    ```

    ```liquid (권장) 기본 대체가 있는 다국어 메시지를 위한 Liquid 구문 theme={null}
    {% assign supported_langs = "en,es,fr,de" | split: "," %}
    {% assign lang = user.language | default: "en" %}

    {% unless supported_langs contains lang %}
      {% assign lang = "en" %}
    {% endunless %}

    {{ dynamic_content.translations.section_1[lang] | default: "Hello" }}
    {{ dynamic_content.translations.section_2[lang] | default: "Thanks for shopping with us..." }}
    ```

    <Frame caption="다국어 이메일 콘텐츠를 위한 Liquid 구문 추가.">
      <img src="https://mintcdn.com/onesignal/4HyuQPBpu-4xjmQC/images/docs/d0df135475c202308b5b5e40f3893f1beff6d7d387a99e9264c5c5936283d699-Screenshot_2025-02-10_at_10.08.20_PM.png?fit=max&auto=format&n=4HyuQPBpu-4xjmQC&q=85&s=bb3aaec56a1bcca6e1400b096a5550b7" alt="다국어 동적 콘텐츠를 위한 Liquid 구문이 있는 OneSignal 이메일 편집기" width="1062" height="446" data-path="images/docs/d0df135475c202308b5b5e40f3893f1beff6d7d387a99e9264c5c5936283d699-Screenshot_2025-02-10_at_10.08.20_PM.png" />
    </Frame>
  </Tab>

  <Tab title="콘텐츠 개인화 메시지 예제">
    ```csv content_personalization_template.csv theme={null}
    campaign_id,title,message,url
    campaign_123,Flash deal for you,Tap to claim,https://example.com/flash
    campaign_456,Weekend picks are here,See what's trending,https://example.com/weekend
    default,Our latest offers,See what's new,https://example.com
    ```

    * `file_name`은 `content_personalization_template.csv`입니다.
    * `user_property`는 태그 키: `campaign_id`에 매핑됩니다.
    * `message_component`는 개인화하려는 메시지 섹션에 매핑된 열 헤더입니다(title, message 또는 url).

    ```liquid 콘텐츠 개인화 메시지를 위한 Liquid 구문 theme={null}
    {{ dynamic_content.content_personalization_template[campaign_id].title }}
    {{ dynamic_content.content_personalization_template[campaign_id].message }}
    {{ dynamic_content.content_personalization_template[campaign_id].url }}
    ```

    ```liquid (권장) 기본 대체가 있는 콘텐츠 개인화 메시지를 위한 Liquid 구문 theme={null}
    {% assign cid = campaign_id | default: "default" %}

    {% unless dynamic_content.content_personalization_template[cid] %}
      {% assign cid = "default" %}
    {% endunless %}

    {{ dynamic_content.content_personalization_template[cid].title | default: "최신 제안" }}
    {{ dynamic_content.content_personalization_template[cid].message | default: "새로운 것을 보세요" }}
    {{ dynamic_content.content_personalization_template[cid].url | default: "https://example.com" }}
    ```

    <Frame caption="캠페인 기반 푸시 개인화를 위한 Liquid 구문 추가.">
      <img src="https://mintcdn.com/onesignal/tNi1OgLc_p9hiq7_/images/docs/1c80cff787617df73a16bd4858446a07db6af84f4d79404c4a2ad34e3e509876-Screenshot_2025-02-10_at_9.53.13_PM.png?fit=max&auto=format&n=tNi1OgLc_p9hiq7_&q=85&s=37a96d318756adc6b0f2a35aecc20c92" alt="동적 콘텐츠 개인화 Liquid 예제" width="1774" height="1018" data-path="images/docs/1c80cff787617df73a16bd4858446a07db6af84f4d79404c4a2ad34e3e509876-Screenshot_2025-02-10_at_9.53.13_PM.png" />
    </Frame>
  </Tab>
</Tabs>

<Check>
  `default` 대체가 있는 Liquid을 사용하여 제목 줄, 프리헤더, 버튼
  레이블 및 URL을 업데이트하세요.
</Check>

### CSV 셀에서 HTML 사용(이메일만 해당)

CSV 셀에 HTML 마크업을 직접 포함하여 이메일에 풍부한 콘텐츠를 삽입할 수 있습니다. 이는 사용자 속성에 따라 배너, CTA 또는 스타일 블록과 같은 이메일의 전체 섹션을 교체하는 데 유용합니다.

```csv promo_banners.csv theme={null}
campaign_id,banner_html
spring_sale,<div style="background:#4CAF50;padding:16px;text-align:center;"><a href="https://example.com/spring" style="color:#fff;font-size:18px;">Shop the Spring Sale</a></div>
default,<div style="background:#333;padding:16px;text-align:center;"><a href="https://example.com" style="color:#fff;font-size:18px;">See What's New</a></div>
```

이메일 템플릿에서 HTML 셀을 참조합니다:

```liquid theme={null}
{{ dynamic_content.promo_banners[campaign_id].banner_html | default: "<p>Check out our latest offers</p>" }}
```

HTML은 이메일 본문에 직접 렌더링되므로 이메일 클라이언트가 지원하는 모든 인라인 스타일과 마크업을 사용할 수 있습니다.

<Warning>
  CSV 셀의 HTML은 이메일에서만 지원됩니다. 푸시 및 SMS 채널은 콘텐츠를 일반 텍스트로 렌더링하며 HTML 마크업을 해석하지 않습니다.
</Warning>

***

## 참조

### 템플릿 업데이트

대시보드를 통해 CSV를 다시 업로드하거나 [템플릿 업데이트 API](/reference/update-template) `dynamic_content` 속성을 사용하세요.

### 키의 특수 문자

**해시 표기법**(영숫자가 아닌 키의 경우):

```liquid theme={null}
{{ dynamic_content.file_name["!the_row!"]["&the_column&"] }}
```

**점 표기법**(표준 키의 경우):

```liquid theme={null}
{{ dynamic_content.file_name.the_row.the_column }}
```

***

## 자주 묻는 질문

### CSV를 사용한 동적 콘텐츠를 테스트하는 방법은?

이메일을 사용하여 메시지의 여러 변형을 테스트합니다.

* 이메일에서 `+` 주소 지정을 사용하여 여러 변형을 테스트합니다: `username+test@example.com`.
* 위의 다국어 및 콘텐츠 개인화 예제에 따라 태그를 설정하세요.
* 여러 사용자 및 데이터 태그 업로드에 대한 자세한 내용은 [가져오기](./import)를 참조하세요.

### CSV를 사용한 동적 콘텐츠와 다른 개인화 옵션을 언제 사용하나요?

대시보드에서 메시지를 보내고 CSV 파일에 사용자 데이터가 있는 경우 **CSV를 사용한 동적 콘텐츠**를 사용하세요. 메시지에 동적 콘텐츠를 추가하는 다른 방법은 [메시지 개인화](./message-personalization) 또는 [다국어 메시징](./multi-language-messaging)을 참조하세요.

***

## 관련 페이지

<Columns cols={2}>
  <Card title="메시지 개인화" icon="wand-magic-sparkles" href="./message-personalization">
    OneSignal에서 사용 가능한 모든 개인화 옵션 개요.
  </Card>

  <Card title="Liquid 구문 사용" icon="code" href="./using-liquid-syntax">
    OneSignal 메시지를 위한 완전한 Liquid 구문 참조.
  </Card>

  <Card title="가져오기" icon="file-import" href="./import">
    OneSignal에 사용자 데이터와 세그먼트를 업로드합니다.
  </Card>

  <Card title="템플릿" icon="clone" href="./templates">
    재사용 가능한 메시지 템플릿을 만듭니다.
  </Card>
</Columns>