OneSignal로 마이그레이션

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

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

사전 요구 사항

시작하기 전에:

OneSignal에서 계정 설정
팀원 초대

마이그레이션 단계

1. 현재 메시징 설정 감사

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

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

마케터용:

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

2. OneSignal 용어 매핑

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

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

3. OneSignal SDK 추가 (개발자)

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

Mobile SDK 설정

In-App 메시지에 필수이며 iOS 및 Android의 푸시 알림에 권장됩니다.

Web SDK 설정

웹 푸시 알림에 필수입니다.

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

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

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

Mobile SDK 참조

login, addEmail, addSms, 푸시 토큰 접근 및 알림 리스너 메서드.

Web SDK 참조

login, addEmail, addSms 및 웹 푸시 이벤트 처리 메서드.

4. 레거시 구현 제거

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

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

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

푸시 토큰 충돌 및 형식

푸시 토큰을 생성하는 모든 레거시 코드를 제거하세요. SDK가 초기화될 때 자동으로 발생하는 OneSignal만 푸시 토큰을 생성하도록 허용하세요. 필요한 경우 SDK를 사용하여 토큰을 가져와 다른 제공업체 또는 백엔드로 보낼 수 있습니다. 이를 위한 메서드:

Frontend Mobile SDK를 사용하여 장치의 푸시 토큰 식별자 가져오기
View user API를 사용하여 장치의 식별자 가져오기

푸시 토큰 형식은 플랫폼에 따라 다릅니다(iOS APNS vs. Android FCM). 자세한 내용은 Push token formats를 참조하세요.

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를 참조하세요.

푸시 페이로드 처리

OneSignal과 다른 푸시 제공업체를 병렬로 사용하는 경우 다른 SDK가 OneSignal 알림을 처리하지 않도록 하여 중복을 방지해야 합니다. OneSignal의 푸시 페이로드에는 다른 제공업체와 구별되는 rawPayload의 "custom" 키가 포함되어 있습니다. 두 SDK를 모두 실행하는 경우 레거시 SDK가 OneSignal 알림을 처리하지 않도록 이 키를 확인하는 알림 핸들러를 업데이트하세요. 자세한 내용은 OSNotification payload 참조 문서를 확인하세요.

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

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

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

5. 웹 푸시 마이그레이션

동일한 HTTPS 사이트 origin을 사용하는 경우 구독자는 다음 방문 시 자동으로 OneSignal에 추가됩니다. 프롬프트가 표시되지 않으며 즉시 푸시를 받을 수 있습니다. 브라우저 보안 제한으로 인해 웹 푸시 Subscription은 가져올 수 없습니다. OneSignal이 인계받기 전에 이전 푸시 Service Worker를 등록 취소해야 합니다:

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

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를 사용하세요:

OneSignal.init({
  appId: "YOUR_APP_B_ID",
});

사용자가 사이트를 다시 방문하면 브라우저의 기존 푸시 권한을 통해 OneSignal이 자동으로 앱 B에 등록합니다.
새 권한 프롬프트가 표시되지 않지만 앱 B에서 Subscription이 생성되려면 사용자가 사이트를 최소한 한 번 방문해야 합니다.
구독자는 비활성화될 때까지 앱 A에 계속 표시됩니다.

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

6. 이메일 및 SMS 설정

OneSignal로 이메일 및/또는 SMS를 보내는 경우 이메일 설정 및 SMS 설정 가이드를 따라야 합니다. 현재 이메일 발신 도메인을 OneSignal로 마이그레이션하려면 DNS 레코드를 업데이트하면 됩니다. 필요한 경우 OneSignal에서 여러 이메일 발신자를 설정할 수 있습니다. SMS 발신자 마이그레이션에는 시간이 걸릴 수 있습니다. 도움이 필요한 경우 support@onesignal.com으로 문의하세요.

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

지난 270일 동안 앱에서 활성 상태였던 구독 사용자를 가져오면 마이그레이션 중 중단을 최소화하는 데 도움이 됩니다. 알려진 테스트 사용자를 먼저 가져온 다음 앱 출시 전에 나머지 사용자를 가져오는 것이 좋습니다.

플랫폼 고려 사항

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

가져오기 단계

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

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

8. 마이그레이션 테스트

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

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

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

OneSignal SDK를 추가하기 전에 OneSignal에서 가져온 사용자에게 테스트 알림을 보냅니다.
- iOS에서는 푸시를 받아야 하지만 확인된 전달 또는 클릭 분석은 받지 못합니다.
- 다른 푸시 SDK가 있고 아직 페이로드 처리 요구 사항을 구현하지 않은 경우 Android에서 푸시를 받을 수 있습니다. 알림에 데이터가 누락되어 클릭 시 예상대로 작동하지 않을 수 있습니다.
OneSignal SDK를 추가한 후 OneSignal에서 가져온 사용자에게 테스트 알림을 보냅니다.
- 확인된 전달 및 클릭 분석과 함께 Android 및 iOS 모두에서 푸시를 받아야 합니다.
앱이 다른 상태일 때 알림 동작을 테스트합니다.
Deep Link 및 사용자 지정 작업이 올바르게 작동하는지 확인합니다.

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

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

사전 릴리스 체크리스트

마케터용:

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

개발자용:

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

앱/사이트 릴리스

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

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

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

결과 모니터링

개발자용:

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

마케터용:

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

FAQ

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

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

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

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

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

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

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

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

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

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

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

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

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

도움이 필요하신가요?지원 팀과 채팅하거나 support@onesignal.com으로 이메일을 보내주세요.다음을 포함해 주세요:

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

기꺼이 도와드리겠습니다!

시작하기 & 설정

메시지 채널

Journeys

오디언스 & 사용자 지정 이벤트

분석 & 통합

개인 정보 보호 & 보안

OneSignal로 마이그레이션

사전 요구 사항

마이그레이션 단계

1. 현재 메시징 설정 감사

2. OneSignal 용어 매핑

3. OneSignal SDK 추가 (개발자)

Mobile SDK 설정

Web SDK 설정

Mobile SDK 참조

Web SDK 참조

4. 레거시 구현 제거

푸시 토큰 충돌 및 형식

Firebase Messaging SDK 충돌

푸시 페이로드 처리

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

5. 웹 푸시 마이그레이션

OneSignal 앱 간 마이그레이션

6. 이메일 및 SMS 설정

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

플랫폼 고려 사항

가져오기 단계

8. 마이그레이션 테스트

사전 릴리스 체크리스트

앱/사이트 릴리스

결과 모니터링

FAQ

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

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

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

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

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

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

시작하기 & 설정

메시지 채널

Journeys

오디언스 & 사용자 지정 이벤트

분석 & 통합

개인 정보 보호 & 보안

​사전 요구 사항

​마이그레이션 단계

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

​2. OneSignal 용어 매핑

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

Mobile SDK 설정

Web SDK 설정

Mobile SDK 참조

Web SDK 참조

​4. 레거시 구현 제거

​푸시 토큰 충돌 및 형식

​Firebase Messaging SDK 충돌

​푸시 페이로드 처리

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

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

​OneSignal 앱 간 마이그레이션

​6. 이메일 및 SMS 설정

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

​플랫폼 고려 사항

​가져오기 단계

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

​사전 릴리스 체크리스트

​앱/사이트 릴리스

​결과 모니터링

​FAQ

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

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

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

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

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

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

사전 요구 사항

마이그레이션 단계

1. 현재 메시징 설정 감사

2. OneSignal 용어 매핑

3. OneSignal SDK 추가 (개발자)

4. 레거시 구현 제거

푸시 토큰 충돌 및 형식

Firebase Messaging SDK 충돌

푸시 페이로드 처리

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

5. 웹 푸시 마이그레이션

OneSignal 앱 간 마이그레이션

6. 이메일 및 SMS 설정

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

플랫폼 고려 사항

가져오기 단계

8. 마이그레이션 테스트

사전 릴리스 체크리스트

앱/사이트 릴리스

결과 모니터링

FAQ

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

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

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

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

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

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