OneSignal에서 Pushwoosh로 마이그레이션하기

OneSignal이 무료 요금제에 엄격한 상한선을 도입합니다. 월간 활성 사용자(MAU) 1,000명을 초과하면 모바일 푸시와 인앱 메시지가 더 이상 무료가 아닙니다. 신규 계정은 2026년 9월 1일부터, 기존 계정은 10월 1일부터 이 제한이 적용됩니다. 앱의 월간 활성 사용자가 1,000명을 넘는다면 선택지는 3가지입니다: 유지하며 비용을 지불하거나, 사용자 규모를 줄이거나, 다른 플랫폼으로 이전하는 것입니다.

무엇이 언제 바뀌는가

Source: OneSignal

• 무료 요금제는 1,000 MAU 이하에서는 그대로 작동합니다. 이를 초과하면 모바일 푸시와 인앱 메시지가 유료 등급으로 전환됩니다.
• 적용 시점: OneSignal 청구 FAQ에 따르면 신규 계정은 2026년 9월 1일, 기존 계정은 2026년 10월 1일부터 제한이 적용됩니다.
• 기준선: 모바일 푸시와 인앱 메시지 기준 1,000 MAU 미만. 이를 초과하면 업그레이드 전까지 해당 채널의 발송이 중단됩니다.
• 변경되지 않는 부분: 웹 푸시, 이메일, SMS는 기존과 동일한 요금제 한도 내에서 계속 작동합니다. 이번 변경은 모바일에만 적용됩니다.
• Journey에도 영향을 미칩니다: 푸시나 인앱 메시지를 발송하는 Journey 단계는 모바일 구독을 건너뛰게 됩니다.
• 구독자를 삭제해도 해결되지 않습니다. 지난 30일 이내 활성 상태였던 모바일 구독을 삭제해도, 요금제는 삭제 후 30일이 지나야 다시 활성화되며, 그 기간 내내 제한 이하를 유지해야만 가능합니다.

마이그레이션은 어떻게 진행되는가

이전을 결정했다면, 계획을 세우는 방식 자체가 달라지는 지점이 있습니다: 마이그레이션은 저희가 대신 진행합니다. 사용자가 해야 할 일은 세 가지뿐입니다 — 내보내기 파일, 푸시 자격 증명, 그리고 다음 앱 릴리스에서 SDK를 교체하는 것입니다. 그 외 모든 작업(데이터 정리, 플랫폼 매핑, 태그 재생성, 오디언스 임포트, 발송 가능 여부 검증)은 저희가 처리합니다.

전환은 두 트랙이 동시에 진행됩니다. 일회성 임포트가 기존 오디언스를 이전하므로, 단 한 명도 앱을 업데이트하기 전부터 오디언스는 도달 가능한 상태를 유지합니다. 이후 사용자가 새 빌드를 설치하면 SDK가 각 기기를 이어받습니다. 두 트랙 모두 필요하며, 어느 쪽도 다른 쪽을 막지 않습니다.

1. 마이그레이션 가능한 것과 불가능한 것

직접 조사할 필요는 없습니다. 마이그레이션 도중 예상치 못한 일이 없도록 전체 그림을 미리 정리했습니다.

소요 시간

SDK 교체와 정상적인 테스트 발송은 개발자 한 명이 하루면 끝나는 작업입니다. 임포트는 저희 쪽에서 병렬로 진행되며, 첫날부터 도달 범위를 그대로 유지시켜주는 부분입니다: 임포트된 기기는 누구도 앱을 업데이트하기 전부터 발송 가능한 상태입니다. 이후 사용자의 오디언스는 사용자들이 새 빌드를 설치하는 속도에 맞춰 Pushwoosh SDK로 넘어가며, 이는 몇 주가 걸리고 마지막 한 기기까지 도달하는 일은 사실상 없습니다. 바로 그래서 임포트가 존재하는 것입니다.

순서가 중요합니다:

1. 오디언스를 내보냅니다. OneSignal app_id와 App API 키를 보내주시면 저희가 직접 내보내기를 가져오거나, 직접 CSV를 내보내셔도 됩니다. 자세한 내용은 아래에 있습니다.
2. 푸시 자격 증명을 전달합니다. OneSignal이 이미 발송에 사용 중인 것과 동일한 키입니다. 임포트 전에 업로드해 두어 임포트된 모든 기기가 발송 가능하도록 합니다.
3. SDK를 교체합니다. OneSignal SDK를 제거하고 Pushwoosh SDK를 추가한 뒤, Pushwoosh 애플리케이션 코드와 기기 API 토큰으로 초기화합니다. 플랫폼별 단계는 버전 A~C에 있습니다.
4. 발송을 검증합니다. 프로덕션 트래픽을 건드리기 전에 테스트 기기를 등록하고 스스로에게 푸시를 보내 확인합니다.
5. 태그 시트를 승인합니다. 내보내기 파일을 기반으로 저희가 작성하며, 사용하지 않는 태그를 지우고 다중값 태그를 표시해 주시면 됩니다. 저희가 세그먼트를 임포트하고 재생성합니다.
6. 발송을 전환합니다. 테스트 발송이 정상이고 임포트가 확인되면, 캠페인을 Pushwoosh로 전환하고 OneSignal에서의 발송을 중단합니다.

2. 오디언스 내보내기

옵션 A (권장): 저희가 대신 처리합니다. OneSignal app_id와 App API 키를 보내주시면 저희가 직접 내보내기를 가져옵니다. 사용자가 할 일은 여기서 끝입니다.

옵션 B: 직접 처리합니다. OneSignal에서 Audience > Subscriptions로 이동해 CSV를 내보내거나, 내보내기 엔드포인트를 호출합니다:

curl -X POST 'https://api.onesignal.com/players/csv_export?app_id=YOUR_APP_ID' \
  -H 'Authorization: Key YOUR_APP_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"extra_fields":["external_user_id","timezone_id","notification_types"]}'

응답에는 csv_file_url이 반환되며, gzip으로 압축된 CSV로 3일간 다운로드할 수 있습니다.

Source: OneSignal

다음 컬럼은 파일에 반드시 포함되어야 합니다. 그 외 컬럼은 선택 사항이며 저희는 무시합니다.

참고: external_user_id와 timezone_id는 기본 내보내기에 포함되지 않습니다. 위의 extra_fields 파라미터로 명시적으로 요청하거나, 대시보드의 컬럼 선택 기능을 사용하세요.

3. 푸시 자격 증명 전달하기

이는 OneSignal이 이미 발송에 사용 중인 것과 동일한 자격 증명이므로 새로 만들 필요가 없습니다. 저희가 OneSignal에서 직접 가져올 수는 없습니다: 업로드된 키는 이후 다시 다운로드할 수 없으므로, 이 단계는 사용자가 직접 진행해야 합니다.

임포트가 시작되기 전에 자격 증명을 사용자의 Pushwoosh 애플리케이션에 업로드합니다. 이 순서가 중요합니다: 자격 증명 없이 임포트하면 아무것도 발송할 수 없는 기기로 가득한 데이터베이스만 남게 됩니다.

4. 태그와 세그먼트 검토하기

Source: OneSignal

태그는 마이그레이션되며, 직접 목록을 정리할 필요는 없습니다. OneSignal에서 태그는 타입이 지정되지 않은 단순한 key/value 문자열입니다. Pushwoosh에서는 각 태그가 애플리케이션당 한 번 타입(String, Integer, Boolean, Date, List, Price)과 함께 선언된 뒤에야 값을 가질 수 있습니다.

내보내기 파일을 받는 즉시, 그 파일을 기반으로 작성한 태그 검토 시트를 보내드립니다. 발견된 모든 태그가 나열되며, 샘플 값, 값을 가진 기기 수, 저희가 제안하는 타입까지 채워져 있습니다. 사용자가 할 일은 두 개 컬럼뿐입니다: 더 이상 쓰지 않는 태그를 지우고, 한 번에 여러 값을 가질 수 있는 태그를 표시하는 것입니다. 나머지는 그대로 승인해도 되는 제안입니다.

추측 대신 확인을 요청하는 이유는 다음과 같습니다: 태그의 타입은 한번 생성되면 고정되므로, 다중값 태그를 단순 String으로 생성하면 삭제 후 재임포트해야 합니다. 내보내기에서 단일값처럼 보이는 태그가 바로 데이터만으로는 판단할 수 없는 경우입니다. 답변이 없으면 저희가 추론한 타입으로 모든 태그를 임포트하고, 어떤 것을 추측했는지 알려드립니다.

세그먼트는 재구축됩니다. OneSignal API는 세그먼트로 내보내기를 필터링하고 세그먼트 이름을 나열할 수 있지만, 그 뒤에 있는 필터 조건은 반환하지 않아 임포트할 대상이 없습니다. 두 가지 방법이 있습니다:

1. 조건을 재구축합니다 (권장). 필터 조건이 포함된 세그먼트 목록을 보내주세요; 스크린샷도 괜찮습니다. 임포트된 태그 위에 재생성합니다. 재구축된 세그먼트는 동적이어서 오디언스가 변할 때마다 계속 업데이트됩니다.
2. 멤버십을 고정합니다. 세그먼트별로 하나씩 내보내기를 받아 각 파일에 마커 태그를 표시합니다. 예를 들어 os_segment = vip_users처럼요. 빠르지만 결과물은 스스로 업데이트되지 않는 스냅샷입니다.

OneSignal 자체의 행동 데이터(세션 수, 플레이타임, “Active Users”, “Engaged Users”)로 만들어진 세그먼트는 임포트 시점에 재현할 수 없습니다. 해당 이력이 OneSignal에만 남아있기 때문입니다. Pushwoosh에서의 동등한 세그먼트는 저희 SDK가 앱에 반영되는 즉시 데이터가 쌓이기 시작합니다.

5. 저희가 처리하는 작업

1. Pushwoosh 애플리케이션을 생성 및 설정하고, 3단계의 자격 증명을 업로드합니다.
2. 내보내기 데이터를 정리합니다: 구독 해제된 행과 토큰이 비어 있는 행을 제거하고, OneSignal 플랫폼 코드를 저희 코드로 매핑하며, 태그를 변환하고, external_user_id를 저희 User ID로 매핑합니다.
3. 태그 스키마를 생성한 뒤, 오디언스를 배치 단위로 임포트하며 각 배치를 검증합니다.
4. 소규모 컨트롤 그룹에 테스트 푸시를 보내고 예상 결과와 비교합니다.
5. 결과를 보고합니다: 파일에 있던 구독 수, 임포트된 수, 그리고 건너뛴 모든 행의 사유입니다.

6. 다음 앱 릴리스에 Pushwoosh SDK 반영하기

임포트는 기존 오디언스를 즉시 도달 가능하게 만들지만, 이는 다리일 뿐 최종 목적지가 아닙니다. 앱 안의 Pushwoosh SDK만이 OS가 토큰을 갱신할 때(재설치, 복원, OS 업그레이드) 새 토큰을 받아오고, 마이그레이션 이후 설치한 사용자를 등록하며, 오픈·인앱 메시지·삭제를 보고할 수 있습니다.

같은 릴리스에서 OneSignal SDK를 제거하세요. 하나의 빌드에 두 개의 푸시 SDK가 있으면 동일한 알림 콜백을 두고 충돌하며, 저희는 그 조합을 테스트하지 않습니다. 새 빌드가 배포되는 동안 OneSignal이 계속 발송하는 것은 정상이고 예상된 상황이지만, 하나의 빌드 안에 두 SDK를 함께 두는 것은 그렇지 않습니다. 플랫폼별 단계는 아래 버전 A~C에 있습니다.

7. 웹 푸시: 구독자가 돌아오는 방식

웹 푸시는 임포트되지 않으며, 이는 Pushwoosh의 선택이 아니라 확실한 기술적 한계입니다. 웹 푸시 구독은 이를 생성한 주체의 VAPID 키 쌍으로 서명되며, OneSignal의 개인 키는 OneSignal 밖으로 나가지 않습니다 — OneSignal 자체 문서에도 웹 구독 키는 OneSignal SDK에서만 사용 가능하다고 명시되어 있습니다. 어떤 프로바이더도 다른 프로바이더의 웹 구독을 임포트할 수 없습니다. 대신 작동하는 방식은 조용한 재구독입니다:

1. OneSignal 스니펫을 제거하고 해당 서비스 워커를 명시적으로 등록 해제합니다. 이전 워커를 그대로 두면 동일한 도메인에서 두 워커가 충돌합니다.
2. Pushwoosh Web Push SDK를 설치하고, 저희 서비스 워커를 도메인 루트에 배치합니다.
3. 애플리케이션 코드와 기기 API 토큰(apiToken)으로 초기화한 뒤, 자동 구독(autoSubscribe: true, 또는 Pushwoosh.subscribe() 호출)을 활성화합니다. 토큰이 없으면 SDK 호출은 401로 응답합니다.

이후 방문자가 돌아오면 조용히 재구독됩니다. 브라우저가 저장하는 알림 권한은 이전 프로바이더가 아니라 사용자의 도메인에 속하므로, 두 번째 프롬프트는 뜨지 않고 사용자는 아무것도 눈치채지 못합니다. 오디언스가 얼마나 빨리 회복되는지는 사람들이 얼마나 빨리 돌아오는지에 달려 있습니다: 대부분의 오디언스는 보통 일주일 이내에 돌아오고, 이후 한 달에 걸쳐 나머지가 서서히 돌아옵니다.

유의해야 할 3가지 사례가 있습니다:

• 알림을 차단한 방문자는 재구독될 수 없습니다. 브라우저가 이를 거부하고 다시 프롬프트를 띄우지 않습니다. 이들은 제외된 상태로 남으며, 이것이 올바른 결과입니다.
• 사이트에서는 수신 거부했지만 브라우저 권한은 계속 허용 상태였던 방문자는 조용히 재구독됩니다. 기술적으로는 유효하지만, 의도적으로 이탈한 사람들을 다시 데려오는 셈입니다. 억제 목록(사용자 자체 user id 또는 이메일 기준)이 있다면 저희에게 보내주세요. 모든 캠페인에서 해당 사용자를 제외하겠습니다. 없다면, 자동이 아니라 명시적 클릭(벨 아이콘이나 프롬프트)을 통한 구독을 권장합니다.
• 웹 푸시가 사용자의 도메인이 아니라 이전 벤더가 제공한 서브도메인에서 운영되었다면, 권한은 그 서브도메인에 속합니다. 이 구독자들은 복구할 수 없으며 사이트에서 다시 옵트인해야 합니다. 전환을 계획하기 전에 어떤 구성인지 확인하세요.

8. 임포트 이후 예상되는 변화

• 한동안 하나의 기기가 두 번 나타날 수 있습니다. 임포트된 레코드는 OneSignal 식별자를 갖고 있으며, 같은 기기에서 저희 SDK가 실행되면 자체 식별자로 등록됩니다. 오래된 레코드는 삭제 추적 또는 자동 90일 비활성 정리로 제거됩니다. 그 사이 external_user_id를 제공하면 두 레코드가 하나의 사용자 프로필 아래 유지됩니다.
• 죽은 토큰은 첫 캠페인에서 정리됩니다. Apple과 Google은 메시지가 실제로 발송될 때만 토큰이 유효하지 않다는 것을 알려주므로, 마이그레이션 이후 첫 발송이 동시에 데이터베이스도 정리해 줍니다.
• 임포트된 수는 OneSignal 카운터보다 낮게 나옵니다. 구독 해제된 행, 토큰이 빈 행, 웹 푸시 행은 설계상 제외됩니다. 리포트에서 각 그룹에 정확히 몇 건이 해당하는지 알려드립니다.

9. 어디를 클릭해야 하는가

사용자가 해야 할 작업의 정확한 경로입니다. 대시보드를 헤매지 않도록 정리했습니다.

10월 1일 이전 체크리스트

진행하면서 계속 열어두세요. 다운로드할 서식은 필요 없습니다.

버전 A: 네이티브 iOS 및 Android

iOS. Pushwoosh iOS SDK를 추가한 뒤, Info.plist에 두 개의 키를 설정합니다: Pushwoosh 애플리케이션 코드를 담은 Pushwoosh_APPID와 기기 API 토큰을 담은 PW_API_TOKEN입니다. 현재 OneSignal 프롬프트를 트리거하는 지점에서 registerForPushNotifications()를 호출하고, 사용 중인 SDK 버전에 맞는 정확한 초기화 코드는 iOS 퀵스타트를 참고하세요. 두 SDK가 동시에 토큰을 요청하지 않도록 OneSignal SDK와 그 등록 호출을 제거하세요.

Android. com.pushwoosh:pushwoosh-firebase 의존성을 추가한 뒤, AndroidManifest.xml의 <application> 태그 안에 두 개의 meta-data 항목을 추가합니다: 애플리케이션 코드를 담은 com.pushwoosh.appid와 기기 API 토큰을 담은 com.pushwoosh.apitoken입니다. 초기화 로직에서 Pushwoosh.getInstance().registerForPushNotifications()를 호출하세요. Firebase 설정은 프로젝트 내 google-services.json과 함께 그대로 유지되며, FCM 자격 증명은 Control Panel의 Android 플랫폼 설정에 입력합니다.

OneSignal의 동등한 호출을 사용하던 지점에서 그대로 setTags()로 태그를, setUserId()로 사용자 식별자를 설정하면, 교체 이후에도 세그멘테이션이 계속 작동합니다.

버전 B: Flutter 및 FlutterFlow

FlutterFlow는 Pushwoosh Flutter SDK를 래핑하므로, 마이그레이션은 대부분 코드가 아니라 설정 작업입니다.

1. 프로젝트에 커스텀 의존성으로 Pushwoosh Flutter 패키지를 추가합니다.
2. 커스텀 액션에서 애플리케이션 코드로 SDK를 초기화하고 푸시 알림을 등록합니다. 현재 초기화 API는 Flutter 퀵스타트를 참고하세요.
3. 다른 Flutter 앱과 동일한 방식으로 네이티브 자격 증명을 설정합니다: iOS는 Info.plist에 Pushwoosh_APPID와 PW_API_TOKEN, Android는 AndroidManifest.xml에 com.pushwoosh.appid와 com.pushwoosh.apitoken입니다.
4. 두 SDK가 동시에 등록되지 않도록 OneSignal 연동을 제거합니다.
5. 커스텀 액션에서 setTags()와 setUserId()로 태그와 user id를 매핑합니다.

버전 C: React Native

1. 플러그인을 설치합니다: npm install pushwoosh-react-native-plugin --save, iOS는 이어서 pod install을 실행합니다.
2. 루트 컴포넌트에서 초기화하고 등록합니다:

import Pushwoosh from 'pushwoosh-react-native-plugin';

Pushwoosh.init({ pw_appid: "YOUR_APPLICATION_CODE" });
Pushwoosh.register();

3. 네이티브 레벨에서 기기 API 토큰을 추가합니다: iOS는 Info.plist에 PW_API_TOKEN, Android는 AndroidManifest.xml에 meta-data로 com.pushwoosh.apitoken을 추가합니다. Android에서는 프로젝트에 google-services.json을 그대로 유지하세요 — FCM 자격 증명 자체는 Control Panel에 있습니다.
4. OneSignal React Native 패키지와 그 init 호출을 제거합니다.
5. 플러그인 API의 setTags()와 setUserId()로 태그와 user id를 그대로 이전합니다.

FAQ

궁금한 점이 있으면 언제든 Pushwoosh 온보딩 담당자에게 문의하세요. 저희는 임포트 후에 수치를 맞추기보다, 임포트 전에 미리 답변드리는 편을 선호합니다.