> ## 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 데이터 태그를 사용하여 사용자 속성을 저장하고 고급 세그먼트화 및 개인화된 메시징을 위한 이벤트를 추적하세요.

데이터 태그는 OneSignal에서 사용자 지정 속성을 저장하고 사용자 동작을 추적할 수 있는 키-값 쌍입니다. 강력한 세그먼트화 및 개인화를 가능하게 합니다.

<Frame>
  <iframe width="560" height="315" src="https://www.youtube.com/embed/t82DSCUXShk?si=KH_u3zB2N5ci8GLT" 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>

태그 사용:

* `subscription_tier` 또는 `name`과 같은 사용자 특성 저장
* `purchases`, `clicks` 또는 `levels`와 같은 동작 추적
* 메시지 및 Journeys를 위한 사용자 세그먼트
* 메시지 콘텐츠 개인화

<Frame>
  <iframe width="560" height="315" src="https://www.youtube.com/embed/Z-rYqwEUU0M?si=Qjx2dMdFXwXSuZJR" 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>

***

## 데이터 태그 값 형식 규칙

모든 태그 값은 **문자열**이어야 합니다. 숫자, 타임스탬프 및 부울과 유사한 값을 여전히 저장할 수 있습니다. 문자열로 변환하기만 하면 됩니다!

| 값 유형    | 형식 예제                               | 참고                                                  |
| ------- | ----------------------------------- | --------------------------------------------------- |
| 문자열 레이블 | `"free"`, `"VIP"`                   | 사용자 유형, 권한, 상태에 사용                                  |
| 숫자      | `"42"`, `"3.14"`                    | 숫자 필터(`보다 큼`, `보다 작음`) 활성화                          |
| 타임스탬프   | `"1685400000"`                      | Unix 타임스탬프(초 단위). [시간 연산자](./time-operators)와 함께 사용 |
| 부울      | `"true"` / `"false"`, `"1"` / `"0"` | 페이로드 크기를 줄이려면 `"1"`/`"0"` 사용                        |

<Frame>
  <iframe width="560" height="315" src="https://www.youtube.com/embed/YTp-jLcajJ0?si=uSRn2cQ7Yur5MAp0" 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>

<Warning>
  **지원되지 않음:** 배열, 객체, 중첩 값 또는 JSON blob. 복잡한 데이터를 저장해야 하는 경우 [사용자 지정 이벤트](./custom-events)를 사용하세요.
</Warning>

### 제한된 키워드

다음 키워드는 메시지 개인화를 위해 내부적으로 사용되므로 제한되며 태그 키로 사용해서는 안 됩니다:
`message`, `notification`, `subscription`, `user`, `template`, `app`, `org`, `dynamic_content`, `data_feed`, `journey`, `custom_data`

자세한 내용은 [메시지 개인화](./message-personalization)를 참조하세요.

### Tags vs Custom Events

[Tags](/docs/en/add-user-data-tags) and [Custom Events](/docs/en/custom-events) are both ways to add data to your users. However, there are some key differences:

| Feature        |                      Tags                     |                                          Custom Events                                         |
| -------------- | :-------------------------------------------: | :--------------------------------------------------------------------------------------------: |
| Data usage     |        Segmentation and personalization       | Trigger Journeys without a Segment, Wait Until steps, personalization directly within Journeys |
| Data retention |                    Lifetime                   |        30+ days ([lifetime storage is available](/docs/en/billing-faq#streaming-events))       |
| Data format    |          Key-value strings or numbers         |                                              JSON                                              |
| Data source    | OneSignal SDK, API, or integrations (limited) |                               OneSignal SDK, API, or integrations                              |
| Data access    |    Segmentation and message personalization   |        Journeys and Journey-message-template personalization, Segmentation (Coming soon)       |

The key distinction between Tags and Custom Events is in their depth and use cases. Tags are properties of a user, such as Name, Account Status, or Location. Events are thing that the user has done, such as Purchasing an Item, Completing a Level, or Inviting a Friend. Both tags and events can be used for segmentation and personalization.

In practice, you will likely use both:

* Tags for user properties that are static and don't change often
* Custom Events for real-time scenarios, complex segmentation, and more sophisticated journey workflows

***

## 권장 태그 전략

데이터 태그는 **메시지 또는 대상 세그먼트화에서 사용**하려는 정보를 나타내야 합니다. 전체 사용자 프로필이나 로그를 저장하기 위한 것이 아닙니다. 이를 위해서는 백엔드 데이터베이스를 사용하세요.

<Frame>
  <iframe width="560" height="315" src="https://www.youtube.com/embed/DeCnQYA21TY?si=YnAv50tpiiVdNEX7" 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>

### 이벤트 기반 동작 태그

태그로 사용자 작업을 추적합니다. Journeys, 후속 조치 또는 알림을 트리거하는 데 유용합니다.

| 키                 | 값 예제                       | 설명                                                             |
| ----------------- | -------------------------- | -------------------------------------------------------------- |
| `cart_update`     | `"1685400000"`             | 사용자가 장바구니에 무언가를 추가한 마지막 시간. [시간 연산자](./time-operators)와 함께 사용. |
| `last_order`      | `"1684100000"`             | 마지막으로 완료된 구매 타임스탬프                                             |
| `amount_spent`    | `"100"`                    | 총 지출—문자열화된 숫자, 통화 기호 없음                                        |
| `social_share`    | `"2"`                      | 소셜 공유 또는 추천 수                                                  |
| `tutorial_status` | `"step2"` 또는 `"completed"` | 튜토리얼 진행 상황—읽기 쉬운 또는 번호가 매겨진 문자열 값 사용                           |

### 게임 활동 태그

게임에서 사용자 성능을 기반으로 개인화하는 데 사용됩니다.

| 키            | 값 예제     | 설명            |
| ------------ | -------- | ------------- |
| `points`     | `"1250"` | 경험치 또는 게임 포인트 |
| `level`      | `"8"`    | 현재 게임 레벨      |
| `high_score` | `"3000"` | 달성한 최고 점수     |

### 계정 상태 태그

계정 등급 또는 상태 변경에 따라 사용자를 타겟팅하는 데 사용합니다.

| 키                 | 값 예제                    | 설명                  |
| ----------------- | ----------------------- | ------------------- |
| `user_type`       | `"free"`, `"premium"`   | 구독 또는 액세스 등급        |
| `has_downgraded`  | `"1"` 또는 `"1685400000"` | 다운그레이드의 부울 또는 타임스탬프 |
| `user_privileges` | `"admin"`, `"guest"`    | 역할 기반 세그먼트화         |

<Note>
  개별 사용자를 식별하려면 **External ID**를 사용하세요. 이 목적으로 태그를 사용하지 **마세요**. [External ID](./users#external-id) 및 [별칭](./aliases)을 참조하세요.
</Note>

### 개인화 태그

[변수 대체](./message-personalization)를 사용한 이름 기반 메시지 사용자 지정에 유용합니다.

| 키            | 값 예제              | 설명             |
| ------------ | ----------------- | -------------- |
| `first_name` | `"Jon"`           | 이름             |
| `last_name`  | `"Smith"`         | 성              |
| `user_name`  | `"PokeCatcher22"` | 표시 이름 또는 화면 이름 |

### 위치 및 인구 통계 태그

지역 또는 연령별로 사용자를 세그먼트화합니다.

| 키            | 값 예제            | 설명                                                                      |
| ------------ | --------------- | ----------------------------------------------------------------------- |
| `region`     | `"New York"`    | 대도시 지역, 선택적으로 [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) 사용 |
| `postcode`   | `"94105"`       | 우편 번호                                                                   |
| `location`   | `"Downtown LA"` | 사용자 지정 문자열 위치                                                           |
| `birthdate`  | `"915148800"`   | Unix 타임스탬프(초 단위) (생년월일)                                                 |
| `birth_year` | `"1998"`        | 4자리 출생 연도                                                               |
| `age_range`  | `"18-35"`       | 일반 대상 세그먼트화에 유용                                                         |

## 태그 추가, 업데이트 및 제거 방법

사용 사례 및 기술 설정에 따라 아래 방법 중 하나를 사용하여 태그를 관리할 수 있습니다.

<Frame>
  <iframe width="560" height="315" src="https://www.youtube.com/embed/e5B3nJyr_ao?si=PfVu4bHMkQJydc41" 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>

<br />

<Columns cols={2}>
  <Card title="SDK 메서드(권장)">
    사용자가 작업을 수행할 때 앱 또는 웹사이트에서 실시간으로 태그를 설정합니다.

    * → [Mobile SDK 참조](./mobile-sdk-reference#data-tags)
    * → [Web SDK 참조](./web-sdk-reference#data-tags)
  </Card>

  <Card title="REST API" href="/reference/update-user">
    REST API를 사용하여 서버 측에서 태그를 추가, 업데이트 또는 제거합니다.
  </Card>

  <Card title="Journeys" href="./journeys-overview">
    사용자가 Journey 단계를 이동할 때 태그를 자동으로 적용합니다.
  </Card>

  <Card title="CSV 가져오기" href="./import">
    `external_id` 또는 `subscription_id`가 있는 CSV를 업로드하여 사용자 태그를 대량 업데이트합니다.
  </Card>

  <Card title="웹 카테고리 프롬프트" href="./permission-requests">
    사용자에게 관심사를 자체 선택하도록 프롬프트하며, 이는 태그로 저장됩니다.
  </Card>

  <Card title="인앱 메시지" href="./in-app-messages-setup">
    인앱 메시지 클릭 작업을 기반으로 태그를 수집하거나 업데이트합니다.
  </Card>

  <Card title="수동 입력">
    OneSignal 대시보드에서 직접 태그를 편집합니다.

    * **대상 > 사용자 > 사용자 프로필 > 태그**로 이동
  </Card>

  <Card title="타사 통합" href="./integrations">
    일부 통합은 태그를 자동으로 동기화하는 것을 지원합니다.

    * Segment, HubSpot, Mixpanel 등
  </Card>
</Columns>

***

## FAQ

### 사용자당 몇 개의 태그를 설정할 수 있나요?

플랜에 따라 다릅니다. [플랜 제한](https://onesignal.com/pricing)을 참조하거나 할당량을 늘리려면 [영업팀에 문의](https://onesignal.com/contact)하세요.

### 플랜 제한을 초과하면 태그는 어떻게 되나요?

OneSignal 앱 내에서 사용할 수 있는 태그 수에는 제한이 없습니다. 제한은 한 번에 각 개별 사용자에게 설정할 수 있는 태그 수에 적용됩니다.

제한에 도달했거나 초과한 사용자에 대해 태그를 **추가하거나 업데이트할 수 없습니다**. 먼저 태그를 삭제한 다음 두 번째 요청을 보내 새 태그를 추가해야 합니다.

이미 설정된 태그는 유지됩니다.

예:

플랜 제한 = 사용자당 20개 태그.

* 사용자에게 19개의 태그가 있음:
  * ✅ 새 태그 1개 추가 = 성공
  * ❌ 새 태그 2개 이상 추가 = 실패
* 사용자에게 20개의 태그가 있음:
  * ❌ 새 태그 추가 = 실패
  * ✅ 기존 태그 1개 이상 업데이트 = 성공

### 태그 사용량은 어디에서 확인할 수 있나요?

* 대시보드: **대상 > 사용자 > 태그 열**
* 전체 보기를 위해 [사용자 내보내기](./exporting-data)

### 태그 사용량을 줄이려면 어떻게 해야 하나요?

* SDK 또는 API를 사용하여 태그 제거
* [CSV 가져오기](./import)를 사용하여 대량 삭제
* 더 적고 재사용 가능한 태그 사용(예: `status:active`)

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

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

  다음을 포함해 주세요:

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

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

***