> ## 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로 마이그레이션하세요. SDK 통합, 사용자 가져오기, 단계적 롤아웃 및 테스트 가이드를 포함합니다.

이 가이드는 최소한의 중단으로 현재 메시징 플랫폼에서 OneSignal로 마이그레이션하는 방법을 설명합니다.

다음을 위해 설계되었습니다:

* OneSignal SDK를 구현하는 **개발자**
* 캠페인 및 분석을 관리하는 **마케터**

***

## 사전 요구 사항

시작하기 전에:

* [OneSignal](https://onesignal.com)에서 계정 설정
* [팀원 초대](./manage-team-members)

***

## 마이그레이션 단계

### 1. 현재 메시징 설정 감사

마이그레이션 전에 현재 구현을 확인하세요:

**개발자용:**

* 지원하는 플랫폼: iOS, Android, Web, 이메일, SMS 등
* 푸시 및 In-App 메시지 이벤트를 처리하는 코드:
  * 포그라운드 표시 및 클릭 처리
  * 푸시, 이메일 등의 Deep Link 사용
  * 푸시 토큰 및 페이로드 처리
* 이메일 주소, 전화번호, 푸시 토큰 등을 수집하는 방법
* 이메일 도메인 및 DNS 소유권
* SMS 발신자 및 옵트인 메커니즘

**마케터용:**

* 보내는 메시지 유형(거래, 마케팅 등)과 각 유형의 템플릿
* 사용자를 세분화하고 타겟팅하는 방법
* 추적하는 분석 또는 전환 지표

### 2. OneSignal 용어 매핑

대부분의 메시징 플랫폼은 서로 다른 이름 아래 유사한 개념을 공유합니다. OneSignal의 용어가 기존에 사용하던 것과 어떻게 매핑되는지 확인하세요:

| Your platform                           | OneSignal term                  | Details                                       |
| --------------------------------------- | ------------------------------- | --------------------------------------------- |
| User / contact / profile                | [User](./users)                 | External ID로 식별됩니다. 속성 및 Subscription을 포함합니다. |
| Push token, email address, phone number | [Subscription](./subscriptions) | 사용자가 메시지를 받을 수 있는 채널(모바일 푸시, 웹 푸시, 이메일, SMS). |
| Audience, cohort, list                  | [Segment](./segmentation)       | 공통 속성이나 행동을 기반으로 한 동적 사용자 그룹.                 |
| Custom attribute, user property         | [Tag](./add-user-data-tags)     | 타겟팅 및 개인화를 위해 사용자에 연결된 키-값 쌍.                 |
| Tracked action, analytics event         | [Custom Event](./custom-events) | 사용자가 수행하는 작업으로, 세분화 및 메시지 트리거에 사용됩니다.         |

### 3. OneSignal SDK 추가 (개발자)

모바일 앱 및/또는 웹 사이트에 OneSignal SDK를 설정하세요:

<Columns cols={2}>
  <Card title="Mobile SDK 설정" icon="mobile" href="./mobile-sdk-setup">
    In-App 메시지에 필수이며 iOS 및 Android의 푸시 알림에 권장됩니다.
  </Card>

  <Card title="Web SDK 설정" icon="globe" href="./web-sdk-setup">
    웹 푸시 알림에 필수입니다.
  </Card>
</Columns>

SDK를 통합한 후 다음 메서드를 사용하여 사용자를 식별하고 Subscription 데이터를 수집하세요:

* **`login`** — [External ID](./users#external-id)를 설정하여 장치 및 채널 간에 사용자를 식별합니다.
* **`addEmail`** — 앱 또는 사이트에서 수집한 주소로 이메일 Subscription을 생성합니다.
* **`addSms`** — 앱 또는 사이트에서 수집한 전화번호로 SMS Subscription을 생성합니다.

구현 세부 정보는 SDK 참조 문서를 확인하세요:

<Columns cols={2}>
  <Card title="Mobile SDK 참조" icon="mobile" href="./mobile-sdk-reference">
    `login`, `addEmail`, `addSms`, 푸시 토큰 접근 및 알림 리스너 메서드.
  </Card>

  <Card title="Web SDK 참조" icon="globe" href="./web-sdk-reference">
    `login`, `addEmail`, `addSms` 및 웹 푸시 이벤트 처리 메서드.
  </Card>
</Columns>

### 4. 레거시 구현 제거

마이그레이션 경로는 두 가지입니다:

* **클린 마이그레이션** — 이전 SDK를 완전히 제거하고 단일 앱 릴리스에서 OneSignal로 교체합니다. 이 방법이 권장됩니다.
* **단계적 마이그레이션** — 앱 버전에 따라 서로 다른 사용자 그룹에 각 제공업체에서 메시지를 보내면서 두 SDK를 일시적으로 유지합니다. 한 번의 릴리스에서 이전 SDK를 제거할 수 없는 경우에만 사용하세요.

어떤 경우든 푸시 토큰, 이메일 주소, 전화번호를 수집하는 레거시 메서드 및 API를 제거하세요. 특히 푸시 토큰 수집은 OneSignal SDK와 충돌을 일으킬 수 있습니다.

#### 푸시 토큰 충돌 및 형식

푸시 토큰을 생성하는 모든 레거시 코드를 제거하세요. SDK가 초기화될 때 자동으로 발생하는 OneSignal만 푸시 토큰을 생성하도록 허용하세요.

필요한 경우 SDK를 사용하여 토큰을 가져와 다른 제공업체 또는 백엔드로 보낼 수 있습니다. 이를 위한 메서드:

* [Frontend Mobile SDK](./mobile-sdk-reference#user-pushsubscription-token)를 사용하여 장치의 푸시 토큰 식별자 가져오기
* [View user](/reference/view-user) API를 사용하여 장치의 식별자 가져오기

<Note>
  푸시 토큰 형식은 플랫폼에 따라 다릅니다(iOS APNS vs. Android FCM). 자세한 내용은 [Push token formats](./osnotification-payload#push-token-formats)를 참조하세요.
</Note>

#### Firebase Messaging SDK 충돌

앱에 Firebase Messaging SDK(`firebase_messaging` 또는 커스텀 `FirebaseMessagingService`)가 포함되어 있으면 OneSignal이 처리하기 전에 FCM 메시지를 가로챌 수 있습니다. 이로 인해 OneSignal에서는 알림이 "전달됨"으로 표시되지만 실제 장치에는 나타나지 않습니다.

이 문제를 해결하려면:

* `AndroidManifest.xml`에서 레거시 Firebase 수신기를 제거하세요.
* `FirebaseMessaging.getToken()` 또는 `FirebaseMessaging.deleteToken()`을 호출하지 마세요.
* OneSignal이 푸시 토큰 수명 주기를 관리하는 유일한 SDK인지 확인하세요.

전체 문제 해결 단계는 [Firebase Messaging SDK conflict](./notifications-show-successful-but-are-not-being-shown#firebase-messaging-sdk-conflict)를 참조하세요.

#### 푸시 페이로드 처리

OneSignal과 다른 푸시 제공업체를 병렬로 사용하는 경우 다른 SDK가 OneSignal 알림을 처리하지 않도록 하여 중복을 방지해야 합니다.

OneSignal의 푸시 페이로드에는 다른 제공업체와 구별되는 `rawPayload`의 `"custom"` 키가 포함되어 있습니다. 두 SDK를 모두 실행하는 경우 레거시 SDK가 OneSignal 알림을 처리하지 않도록 이 키를 확인하는 알림 핸들러를 업데이트하세요. 자세한 내용은 [OSNotification payload](./osnotification-payload) 참조 문서를 확인하세요.

#### 단계적 마이그레이션 (모바일 앱만 해당)

일반적인 방법은 이전 앱 버전 사용자에게는 이전 제공업체에서, 새 버전 사용자에게는 OneSignal에서 메시지를 보내는 것입니다. 그러나 제한된 시간 동안 두 SDK를 모두 유지해야 하는 경우:

* OneSignal이 푸시 토큰을 독점적으로 관리하도록 하세요. 필요한 경우 이전 시스템과 토큰을 공유하세요(위의 [Push token conflicts](#push-token-conflicts--format) 참조).
* 레거시 SDK가 OneSignal 푸시를 무시하도록 페이로드 필터를 업데이트하세요(위의 [Push payload handling](#push-payload-handling) 참조).
* 이전 앱 버전 사용자에게는 이전 제공업체에서, 새 버전 사용자에게는 OneSignal에서 메시지를 보내세요.
* 명확한 마감일과 단계적 중단 계획을 설정하세요.

### 5. 웹 푸시 마이그레이션

동일한 HTTPS 사이트 [origin](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy)을 사용하는 경우 구독자는 다음 방문 시 자동으로 OneSignal에 추가됩니다. 프롬프트가 표시되지 않으며 즉시 푸시를 받을 수 있습니다. 브라우저 보안 제한으로 인해 웹 푸시 Subscription은 가져올 수 없습니다.

OneSignal이 인계받기 전에 이전 푸시 Service Worker를 등록 취소해야 합니다:

1. 웹사이트에서 레거시 SDK 코드 및 Service Worker 파일을 제거하세요.
2. 이전 Service Worker를 등록 취소하기 위해 다음 코드를 추가하세요. `sw.js`를 레거시 제공업체의 Service Worker 파일명으로 교체하세요.

```javascript theme={null}
if ('serviceWorker' in navigator) {
  navigator.serviceWorker.getRegistrations().then(function(registrations) {
    for (let registration of registrations) {
      if (registration.active.scriptURL.includes("sw.js")) {
        registration.unregister();
      }
    }
  });
}
```

#### OneSignal 앱 간 마이그레이션

한 OneSignal 앱(앱 A)에서 다른 앱(앱 B)으로 구독자를 이동하는 경우:

* 웹 푸시 Subscription은 앱 간에 직접 전송할 수 없습니다. 각 Subscription은 사이트의 도메인(origin)과 OneSignal 앱 ID 모두에 연결되어 있습니다.

* 마이그레이션하려면 사이트의 OneSignal 초기화 코드를 업데이트하여 앱 B의 appId를 사용하세요:

```javascript theme={null}
OneSignal.init({
  appId: "YOUR_APP_B_ID",
});
```

* 사용자가 사이트를 다시 방문하면 브라우저의 기존 푸시 권한을 통해 OneSignal이 자동으로 앱 B에 등록합니다.

* 새 권한 프롬프트가 표시되지 않지만 앱 B에서 Subscription이 생성되려면 사용자가 사이트를 최소한 한 번 방문해야 합니다.

* 구독자는 비활성화될 때까지 앱 A에 계속 표시됩니다.

<Info>
  **Best practice:** 충분한 사용자가 마이그레이션되었음을 확인한 후 앱 A에서 보내기를 중지하세요. 마이그레이션 진행 상황을 확인하려면 두 앱의 구독자 수를 모니터링하세요.
</Info>

### 6. 이메일 및 SMS 설정

OneSignal로 이메일 및/또는 SMS를 보내는 경우 [이메일 설정](./email-setup) 및 [SMS 설정](./sms-setup) 가이드를 따라야 합니다.

현재 이메일 발신 도메인을 OneSignal로 마이그레이션하려면 DNS 레코드를 업데이트하면 됩니다. 필요한 경우 OneSignal에서 여러 이메일 발신자를 설정할 수 있습니다.

SMS 발신자 마이그레이션에는 시간이 걸릴 수 있습니다. 도움이 필요한 경우 `support@onesignal.com`으로 문의하세요.

### 7. 기존 사용자 가져오기 (선택 사항)

지난 270일 동안 앱에서 활성 상태였던 구독 사용자를 가져오면 마이그레이션 중 중단을 최소화하는 데 도움이 됩니다.

알려진 테스트 사용자를 먼저 가져온 다음 앱 출시 전에 나머지 사용자를 가져오는 것이 좋습니다.

#### 플랫폼 고려 사항

* 이메일 주소는 활성 및 유효한 사용자의 것이어야 합니다. 이전에 이메일을 클릭하거나 열어본 적이 없는 이메일 주소는 가져오지 마세요.
* 전화번호는 특정 형식이어야 하며 사용자가 SMS 수신에 동의해야 합니다.
* iOS Subscription은 가져온 후 즉시 푸시 알림을 받기 시작할 수 있습니다. 알림 클릭 추적 및 확인된 전달과 같은 기능에는 장치에서 SDK가 활성화되어 있어야 합니다.
* Android/Huawei/Amazon Subscription은 자동 업데이트 또는 수동 업데이트를 통해 장치에서 SDK가 활성화되어 있어야 알림을 받을 수 있습니다.
* 웹 Subscription은 가져올 수 없습니다. [웹 푸시 마이그레이션](#5-web-push-migration)의 위 내용을 따르면 사용자가 사이트로 돌아올 때 웹 푸시 Subscription이 생성되고 푸시 토큰이 SDK를 통해 가져와집니다.

#### 가져오기 단계

1. [User](./users) 및 [Subscription](./subscriptions) 문서를 검토하세요.
2. 이전 시스템에서 테스트 사용자 데이터를 내보냅니다.
3. OneSignal의 [Create user](/reference/create-user) API에 맞게 데이터 형식을 지정합니다.
4. 테스트 사용자를 먼저 가져오고 확인되면 출시 전에 나머지 사용자에 대해 프로세스를 반복합니다.

각 사용자에게는 `external_id`(식별자)와 `type` 및 `token`(또는 `email`/`phone_number`)이 포함된 Subscription이 하나 이상 필요합니다. 필수 필드, 지원되는 Subscription 유형 및 예시 페이로드는 [Create user API 참조](/reference/create-user)를 확인하세요.

### 8. 마이그레이션 테스트

원활한 전환을 위해서는 철저한 테스트가 중요합니다.

1. OneSignal SDK에서 [Debug Logging](./capturing-a-debug-log)을 활성화합니다.
2. 모든 플랫폼(Android, iOS, Web 등)의 실제 장치에서 테스트합니다.
3. 포그라운드 및 백그라운드 알림 처리를 모두 확인합니다.

**개발자 및 마케터 팀을 위한 테스트 시나리오:**

* **OneSignal SDK를 추가하기 전에** OneSignal에서 가져온 사용자에게 테스트 알림을 보냅니다.
  * iOS에서는 푸시를 받아야 하지만 확인된 전달 또는 클릭 분석은 받지 못합니다.
  * 다른 푸시 SDK가 있고 아직 [페이로드 처리](#push-payload-handling) 요구 사항을 구현하지 않은 경우 Android에서 푸시를 받을 수 있습니다. 알림에 데이터가 누락되어 클릭 시 예상대로 작동하지 않을 수 있습니다.

* **OneSignal SDK를 추가한 후** OneSignal에서 가져온 사용자에게 테스트 알림을 보냅니다.
  * 확인된 전달 및 클릭 분석과 함께 Android 및 iOS 모두에서 푸시를 받아야 합니다.

* 앱이 다른 상태일 때 알림 동작을 테스트합니다.

* Deep Link 및 사용자 지정 작업이 올바르게 작동하는지 확인합니다.

**여러 제공업체를 사용하는 경우:**

* 현재 제공업체와 OneSignal 모두에서 보냅니다.
* 중복 알림을 확인하세요.
* 각 제공업체의 알림이 올바르게 표시되는지 확인하세요.
* 사용자 로그인/로그아웃 시나리오를 테스트하세요.

***

## 사전 릴리스 체크리스트

**마케터용:**

* 앱 업데이트를 유도하는 메시징 계획을 구축하세요.
* 이전 시스템의 푸시 및 In-App 메시지를 사용하여 사용자에게 업데이트를 부드럽게 상기시키는 것을 고려하세요.

**개발자용:**

* 푸시 및 In-App 메시지 분석이 예상대로 작동하는지 확인합니다.
  * Android 및 iOS 전반에서 클릭 이벤트 및 확인된 전달이 추적됩니다.
* 두 제공업체에서 보낸 메시지에 대해 클릭 이벤트 및 포그라운드 수신 이벤트가 올바르게 처리되는지 확인합니다.
* 사용자를 가져오는 경우 만료된 토큰 가져오기를 방지하기 위해 지난 270일 동안 앱에서 활성 상태였던 Android 및 iOS 사용자를 내보냅니다. 자세한 내용은 [FCM Expired Token FAQ](./fcm-expired-token-faq)를 참조하세요.

***

## 앱/사이트 릴리스

* 대부분의 사용자는 앱이 자동으로 최신 버전으로 업데이트됩니다.
* 사용자가 업데이트된 앱을 열 때 필수 권한 프롬프트 또는 앱의 알림 설정을 통해 이미 권한이 부여된 경우 푸시 알림 구독 프롬프트가 표시되지 않습니다.

**사용자를 가져오지 않은 경우:**

* 사용자가 업데이트된 버전의 앱을 열면 OneSignal에서 자동으로 생성됩니다. 이전에 구독한 경우 푸시 프롬프트가 표시되지 않습니다.
* 메시지를 보내기 전에 업데이트된 앱을 열 때까지 기다려야 합니다.
* OneSignal에 충분한 사용자가 표시될 때까지 며칠 동안 이전 푸시 제공업체에서 알림 및 In-App 메시지를 계속 보냅니다. 앱을 최신 버전으로 업데이트하도록 요청하는 추가 알림을 보냅니다.

***

## 결과 모니터링

**개발자용:**

* 배포 후 오류율 및 충돌을 모니터링합니다.
* 예기치 않은 토큰 무효화를 관찰합니다.
* SDK 통합 분석을 확인합니다.

**마케터용:**

* 앱 릴리스 날짜를 표시하고 개발자에게 어떤 마이그레이션 경로([클린 또는 단계적](#4-remove-your-legacy-implementation))를 선택했는지, 사용자를 가져왔는지 여부를 확인하세요.
* 이전 플랫폼에서 아직 새 앱 버전으로 업데이트하지 않은 사용자의 Segment를 만드세요. 이 그룹에 계속 이전 제공업체에서 메시지를 보내 업데이트를 유도하세요.
* OneSignal의 구독자 수가 안정화되면 이전 제공업체에서 보내기를 중지하세요.
* **단계적 마이그레이션**을 따르는 경우 마감일 이후 다음 앱 릴리스에서 이전 제공업체의 SDK를 제거하세요.

***

## FAQ

### 현재 푸시 제공업체와 OneSignal을 함께 사용할 수 있나요?

예, 하지만 일시적으로만 가능합니다. 두 푸시 SDK를 병렬로 실행하면 토큰 충돌과 중복 알림이 발생할 수 있습니다. 단계적 마이그레이션이 필요한 경우 [단계적 마이그레이션](#phased-migration-mobile-apps-only) 가이드를 따라 충돌을 방지하고 명확한 마감일을 설정하세요.

### 웹 푸시 구독자를 가져올 수 있나요?

아니요. 브라우저 보안 제한으로 인해 제공업체 간에 웹 푸시 Subscription을 이전할 수 없습니다. 사이트에 OneSignal을 통합하면 기존 구독자가 다음 방문 시 자동으로 다시 등록됩니다. 새 프롬프트는 표시되지 않습니다. [웹 푸시 마이그레이션](#5-web-push-migration)을 참조하세요.

### 마이그레이션 후 사용자에게 푸시 권한을 다시 요청해야 하나요?

아니요. 사용자가 이미 앱 또는 사이트에 푸시 권한을 부여한 경우 OneSignal은 기존 권한을 사용합니다. 새 프롬프트는 표시되지 않습니다.

### 이메일 워밍업이 필요한가요?

발신 도메인에 확립된 발신 평판이 있는 경우 필요하지 않습니다. 워밍업은 전용 IP 주소를 사용하는 경우에만 필요합니다.

### 전용 IP 주소를 받을 수 있나요?

예, 플랜 유형 및 발송량에 따라 가능합니다. 자세한 내용은 계정 관리자에게 문의하세요.

### 이전 제공업체에서 얼마나 오래 계속 보내야 하나요?

대부분의 사용자가 OneSignal SDK가 포함된 업데이트된 앱을 열 때까지 이전 제공업체에서 계속 보내세요. 두 시스템의 구독자 수를 모니터링하고 수치가 안정화되면 이전 제공업체에서 보내기를 중지하세요.

***

<Check>
  OneSignal로 성공적으로 마이그레이션되었습니다! 마이그레이션 계획에 대한 전략 질문은 고객 성공 팀에 문의하여 개인화된 가이드를 받으세요.
</Check>

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

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

  다음을 포함해 주세요:

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

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