> ## 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의 기기 중심 모델에서 보다 개인화된 다채널 참여를 위한 새로운 사용자 중심 API 및 SDK로 마이그레이션하는 방법을 알아보세요.

OneSignal은 기기 중심(Player ID) 모델에서 통합 사용자 개념을 중심으로 구축된 사용자 중심 모델로 마이그레이션했습니다. 이 가이드는 새로운 모델, 이전 접근 방식과의 차이점 및 앱을 안전하고 성공적으로 마이그레이션하는 방법을 설명합니다.

<Note>
  이 가이드는 모바일 SDK 버전 2, 3 또는 4 또는 웹 SDK v15에서 오랫동안 OneSignal을 사용해 온 고객을 위한 것입니다.

  신규 고객이거나 이미 모바일 SDK 버전 5 또는 웹 SDK v16으로 마이그레이션한 경우 이 가이드를 건너뛰고 다음으로 이동할 수 있습니다:

  * [사용자](./users)
  * [구독](./subscriptions)
  * [모바일 SDK 참조](./mobile-sdk-reference)
  * [웹 SDK 참조](./web-sdk-reference)
</Note>

<Frame caption="사용자 모델을 사용한 다채널 메시징">
  <img src="https://mintcdn.com/onesignal/RWtLFPeffHrC81wI/images/docs/aafd98a-small-header-user-model.png?fit=max&auto=format&n=RWtLFPeffHrC81wI&q=85&s=6d6b720a52fb316510a09653bae94385" alt="사용자 모델 다채널 일러스트" width="1280" height="720" data-path="images/docs/aafd98a-small-header-user-model.png" />
</Frame>

## 사용자 모델이란 무엇인가요?

사용자 모델을 사용하면 개별 기기를 타겟팅하는 대신 구독한 모든 메시징 채널(모바일 푸시, 웹 푸시, 이메일, SMS 및 인앱)에서 실제 사용자를 타겟팅할 수 있습니다.

각 사용자:

* 하나 이상의 ID 별칭을 가집니다(예: external\_id, 사용자 지정 별칭)
* 각 채널 또는 기기에 대해 하나씩 여러 구독을 가질 수 있습니다
* 태그, 언어 및 활동 기록과 같은 메타데이터를 포함합니다

이 모델은 오디언스 타겟팅을 단순화하고 개인화된 다채널 메시징을 지원하며 저니, 사용자 수준 분석 및 실시간 ID 해결과 같은 고급 기능을 잠금 해제합니다.

<Frame caption="Player 모델 vs. 사용자 모델">
  <img src="https://mintcdn.com/onesignal/tNi1OgLc_p9hiq7_/images/docs/201ccdd-User_Model_Office_Visuals.png?fit=max&auto=format&n=tNi1OgLc_p9hiq7_&q=85&s=d7910b524fb166050871f47ea344141f" alt="Player 모델과 사용자 모델의 차이를 보여주는 다이어그램" width="4064" height="5214" data-path="images/docs/201ccdd-User_Model_Office_Visuals.png" />
</Frame>

***

## 핵심 개념

<Tabs>
  <Tab title="사용자">
    **사용자**는 실제 사람을 나타냅니다. 시스템 생성 또는 사용자 지정 별칭을 사용하여 사용자를 식별할 수 있습니다.

    * `onesignal_id`: OneSignal에서 자동 생성됨
    * `external_id`: SDK `login()` 또는 API를 통해 설정됨(예약된 별칭)
    * 사용자 지정 별칭: 예: `user_id`, `email`, `facebook` 등

    자세히 알아보기: [사용자](./users)
  </Tab>

  <Tab title="구독">
    **구독**은 사용자가 구독한 채널을 나타냅니다. 여기에는 기기 정보, 토큰, 세션 기록 및 옵트인 상태와 같은 메타데이터가 포함됩니다.

    * 모바일 및 인앱
    * 웹 푸시
    * 이메일
    * SMS

    자세히 알아보기: [구독](./subscriptions)
  </Tab>

  <Tab title="별칭">
    별칭은 외부 식별자(예: 앱의 사용자 ID, Mixpanel ID)를 OneSignal 사용자에 매핑합니다. 여러 별칭을 할당하여 플랫폼 전체에서 분산된 ID를 통합할 수 있습니다.

    * 특수 별칭:
      * `onesignal_id`: 자동 관리, 읽기 전용
      * `external_id`: 쓰기 가능, 레거시 호환

    자세히 알아보기: [별칭 및 외부 ID](./users)
  </Tab>
</Tabs>

***

## 마이그레이션의 이점

* **통합 ID**: 모든 기기 및 채널에서 한 명의 사용자
* **고급 메시징**: 저니, 인앱 로그인 추적 및 수명 주기 캠페인과 같은 강력한 기능
* **깔끔한 세분화**: 태그, 구독 상태, 채널 참여 등으로 사용자를 그룹화
* **단순화된 API**: 더 적은 엔드포인트, 더 일관된 데이터 모델

***

## 마이그레이션 단계

<Warning>
  사용자 모델은 이전 버전과 호환되지 않습니다. 마이그레이션은 Player 모델에서 사용자 모델로의 **단방향**입니다.

  마이그레이션하기 전에:

  * 스테이징 환경에서 철저히 테스트
  * 모든 SDK 및 백엔드 서비스를 업데이트한 후에만 마이그레이션
</Warning>

<Steps>
  <Step title="external_id로 사용자 통합">
    ID 별칭을 사용하여 기존 플레이어 레코드를 통합 사용자로 연결합니다.

    **옵션**:

    * SDK `login(externalId)`
    * API: [사용자 생성](/reference/create-user), [사용자 업데이트](/reference/update-user)
    * CSV: [가져오기](./import)

    OneSignal은 동일한 외부 ID로 구독을 자동으로 병합합니다.
  </Step>

  <Step title="OneSignal SDK 업데이트">
    모든 OneSignal 모바일 SDK v5+ 및 웹 SDK v16+는 사용자 모델을 지원합니다.

    위험을 최소화하기 위해 단계적 배포 전략을 사용하여 SDK 업데이트를 롤아웃합니다:

    * [Apple 단계적 롤아웃](https://developer.apple.com/help/app-store-connect/update-your-app/release-a-version-update-in-phases)
    * [Google Play 단계적 롤아웃](https://support.google.com/googleplay/android-developer/answer/6346149)

    아래 [SDK 지원 표](#sdk-support)를 참조하세요.
  </Step>

  <Step title="새로운 사용자 API를 사용하도록 백엔드 업데이트">
    더 이상 사용되지 않는 Player 모델 API 호출을 새로운 사용자 모델 동등물로 교체합니다.

    이전 엔드포인트를 새 엔드포인트로 매핑하려면 [API 참조](/reference/rest-api-overview) 및 아래 표를 사용하세요.
  </Step>
</Steps>

## SDK 지원 및 마이그레이션 가이드

<Tabs>
  <Tab title="모바일 SDK">
    | 플랫폼          | SDK                                                                 | 마이그레이션 가이드                                                                                               |
    | ------------ | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
    | Android      | [v5+](https://github.com/OneSignal/OneSignal-Android-SDK/releases)  | [가이드](https://github.com/OneSignal/OneSignal-Android-SDK/blob/user-model/main/MIGRATION_GUIDE.md)        |
    | iOS          | [v5+](https://github.com/OneSignal/OneSignal-iOS-SDK/releases)      | [가이드](https://github.com/OneSignal/OneSignal-iOS-SDK/blob/major_release_5.0.0/MIGRATION_GUIDE.md)        |
    | Unity        | [v5+](https://github.com/OneSignal/OneSignal-Unity-SDK/releases)    | [가이드](https://github.com/OneSignal/OneSignal-Unity-SDK/blob/user-model/main/MIGRATION_GUIDE_v3_to_v5.md) |
    | Flutter      | [v5+](https://github.com/OneSignal/OneSignal-Flutter-SDK/releases)  | [가이드](https://github.com/OneSignal/OneSignal-Flutter-SDK/blob/user_model/main/MIGRATION_GUIDE.md)        |
    | React Native | [v5+](https://github.com/OneSignal/react-native-onesignal/releases) | [가이드](https://github.com/OneSignal/react-native-onesignal/blob/major_release_5.0.0/MIGRATION_GUIDE.md)   |
    | .NET MAUI    | [v5+](https://github.com/OneSignal/OneSignal-DotNet-SDK/releases)   | [가이드](https://github.com/OneSignal/OneSignal-DotNet-SDK/blob/user-model/main/MIGRATION_GUIDE.md)         |

    <Note>
      이전 플레이어 모델 메서드와 새 사용자 모델 메서드의 매핑은 [모바일 SDK 매핑](./device-user-model-mobile-sdk-mapping)을 참조하세요.
    </Note>
  </Tab>

  <Tab title="웹 SDK">
    | 플랫폼       | SDK                                                                 | 마이그레이션 가이드                                                                               |
    | --------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
    | Web       | [v16+](https://github.com/OneSignal/OneSignal-Website-SDK/releases) | [가이드](https://github.com/OneSignal/OneSignal-Website-SDK/blob/160000/MIGRATION_GUIDE.md) |
    | React     | [v3+](https://www.npmjs.com/package/react-onesignal)                | [가이드](https://github.com/OneSignal/react-onesignal/blob/main/MigrationGuide.md)          |
    | Vue 2 & 3 | [v2+/v3+](https://www.npmjs.com/package/@onesignal/onesignal-vue3)  | [가이드](https://github.com/OneSignal/onesignal-vue/blob/HEAD/MigrationGuide.md)            |
    | Angular   | [v2+](https://www.npmjs.com/package/onesignal-ngx)                  | [가이드](https://github.com/OneSignal/onesignal-ngx/blob/HEAD/MigrationGuide.md)            |

    <Note>
      이전 플레이어 모델 메서드와 새 사용자 모델 메서드의 매핑은 [웹 SDK 매핑](./device-user-model-web-sdk-mapping)을 참조하세요.
    </Note>
  </Tab>

  <Tab title="백엔드 SDK">
    | 언어     | SDK                                                                                  |
    | ------ | ------------------------------------------------------------------------------------ |
    | Node   | [@onesignal/node-onesignal](https://www.npmjs.com/package/@onesignal/node-onesignal) |
    | Python | [onesignal-python-api](https://pypi.org/project/onesignal-python-api/)               |
    | Go     | [onesignal-go-api](https://pkg.go.dev/github.com/OneSignal/onesignal-go-api/v2)      |
    | .NET   | [OneSignalApi](https://www.nuget.org/packages/OneSignalApi)                          |
    | Rust   | [onesignal-rust-api](https://crates.io/crates/onesignal-rust-api)                    |
    | Ruby   | [onesignal](https://rubygems.org/gems/onesignal)                                     |
    | PHP    | [onesignal-php-api](https://packagist.org/packages/onesignal/onesignal-php-api)      |
  </Tab>
</Tabs>

***

## API 참조

<Tabs>
  <Tab title="Player 모델(더 이상 사용되지 않음)">
    | 이전 API                                   | 대체                                                                              |
    | ---------------------------------------- | ------------------------------------------------------------------------------- |
    | [기기 추가](/reference/add-a-device)         | [사용자 생성](/reference/create-user) 또는 [구독 생성](/reference/create-subscription)     |
    | [기기 편집](/reference/edit-device)          | [사용자 업데이트](/reference/update-user) 또는 [구독 업데이트](/reference/update-subscription) |
    | [플레이어 삭제](/reference/delete-user-record) | [사용자 삭제](/reference/delete-user) 또는 [구독 삭제](/reference/delete-subscription)     |
  </Tab>

  <Tab title="사용자 모델(신규)">
    | 작업    | API                                |
    | ----- | ---------------------------------- |
    | 생성    | [사용자 생성](/reference/create-user)   |
    | 보기    | [사용자 보기](/reference/view-user)     |
    | 업데이트  | [사용자 업데이트](/reference/update-user) |
    | 삭제    | [사용자 삭제](/reference/delete-user)   |
    | 별칭 추가 | [별칭 생성](/reference/create-alias)   |
    | 별칭 제거 | [별칭 삭제](/reference/delete-alias)   |

    ### 구독 API

    | 작업   | API                                       |
    | ---- | ----------------------------------------- |
    | 생성   | [구독 생성](/reference/create-subscription)   |
    | 업데이트 | [구독 업데이트](/reference/update-subscription) |
    | 삭제   | [구독 삭제](/reference/delete-subscription)   |
    | 전송   | [구독 전송](/reference/transfer-subscription) |
  </Tab>
</Tabs>

***

## 다음 단계

* 📘 [사용자](./users) 및 [구독](./subscriptions) 문서를 참조하세요
* 🛠️ SDK를 업데이트하고 프로덕션으로 이동하기 전에 스테이징에서 테스트하세요
* 💬 도움이 필요하신가요? `support@onesignal.com`으로 문의하세요

<Check>
  이제 새로운 사용자 모델로 구동되는 개인화된 다채널 메시징 경험을 구축할 준비가 되었습니다!
</Check>

***