OneSignal로 마이그레이션

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

​

사전 요구 사항

• OneSignal에서 계정 설정
• 팀원 초대

​

마이그레이션 단계

​

1. 현재 메시징 설정 감사

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

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

​

2. 핵심 OneSignal 개념

• User - External ID를 통해 식별됩니다. User는 속성(태그, 세션 데이터 등) 및 Subscription(푸시, 이메일, SMS)으로 구성됩니다.
• Subscription - 사용자가 메시지를 받을 수 있는 방법을 나타냅니다. 4가지 유형의 Subscription이 있습니다:
  • Mobile: 푸시 알림, In-App 메시지 및 Live Activity를 받을 수 있습니다.
  • Web push: 웹 푸시 알림을 받을 수 있습니다.
  • Email: 이메일 알림을 받을 수 있습니다.
  • SMS: SMS 알림을 받을 수 있습니다.
• Segment - 공통 속성을 공유하는 사용자 그룹입니다.
• 태그 - 사용자 지정 사용자 속성입니다.
• Custom Event - 사용자가 수행하는 작업입니다.

​

3. OneSignal SDK 추가 (개발자)

​

External ID로 사용자 식별

• Mobile SDK
• Web SDK

​

새 이메일 및 전화번호 수집

• Email Subscription: Mobile SDK 및 Web SDK에서 addEmail 메서드 사용
• SMS Subscription: Mobile SDK 및 Web SDK에서 addSms 메서드 사용

​

4. 레거시 구현 제거

​

푸시 토큰 충돌 및 형식

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

• iOS Push APNS 토큰 형식: 64자, 16진수 문자만(0-9,a-f). deviceToken.map {String(format: "%02x", $0)}.joined()
• Android Push FCM 토큰 형식: 일반적으로 163자, 영숫자 문자, 하이픈, 콜론 및 밑줄 포함 가능.

​

푸시 페이로드 처리

​

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

• 여러 SDK가 푸시 토큰을 생성하도록 허용하지 마세요. OneSignal이 처리하도록 하고 필요한 경우 이전 시스템과 토큰을 공유하세요.
  • Frontend SDK 또는 View user API 사용
• 레거시 SDK가 OneSignal 푸시를 처리하지 않도록 페이로드 필터를 업데이트하세요.
  • OneSignal은 rawPayload에서 "custom" 키를 사용합니다(문서).
  • NotificationCompat(Android)에서 이 키를 확인하세요.
• 어떤 제공업체가 어떤 유형의 알림을 처리할지 결정하세요.
• 명확한 마감일을 설정하고 레거시 시스템에 대한 단계적 중단 계획을 세우세요.
  • 보내는 각 알림 유형에 대한 알림 템플릿을 만드세요.
  • 이전 버전의 앱 사용자에게는 이전 제공업체가 메시지를 보내고 새 버전의 앱 사용자에게는 OneSignal이 메시지를 보내도록 설정하세요.
  • 특정 사용자 그룹을 타겟팅하기 위한 Segment를 만드세요.

​

5. 웹 푸시 마이그레이션

• 브라우저 보안 제한으로 인해 웹 푸시 Subscription을 가져올 수 없습니다. OneSignal은 사용자가 돌아올 때 등록합니다.
• OneSignal이 인계받기 전에 이전 푸시 Service Worker를 등록 취소해야 합니다.

1. 레거시 SDK 제거: 웹사이트의 코드 및 Service Worker 파일.
2. Service Worker가 등록 취소되었는지 확인하려면 이 코드를 추가하세요.
3. 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 앱 간 마이그레이션

• 웹 푸시 Subscription은 앱 간에 직접 전송할 수 없습니다. 각 Subscription은 사이트의 도메인(origin)과 OneSignal 앱 ID 모두에 연결되어 있습니다.
• 마이그레이션하려면 사이트의 OneSignal 초기화 코드를 업데이트하여 앱 B의 appId를 사용하세요:

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

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

​

6. 이메일 및 SMS 설정

​

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

​

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

​

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

​

플랫폼 고려 사항

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

​

가져오기 단계

1. User 및 Subscription 문서를 검토하여 이해하세요.
2. 이전 시스템에서 테스트 사용자 데이터를 내보냅니다.
3. OneSignal의 Create user API에 맞게 데이터 형식을 지정합니다.
4. 테스트 사용자를 가져오고 성공적으로 테스트한 후 사전 릴리스 체크리스트에서 반복할 프로세스를 유지합니다.

• token - 푸시 토큰 또는 이메일 주소 또는 전화번호
• type - Subscription 유형: iOSPush, AndroidPush, WebPush, Email, SMS
• external_id - 사용자의 고유 식별자. 추적 및 분석에 사용하는 것이 좋습니다.

  {
    "identity": {
      "external_id": "user_12345"
    },
    "subscriptions": [
      {
        "type": "iOSPush",
        "token": "7abcd49d0affb7426a8f1202420e8f4e2fc4df58e49501adc383f3bd66df8636"
      },
      {
        "type": "AndroidPush",
        "token": "dQGm89TZQXiTvLsRIj_GBo:APA91bpgqFgqkP2qYvV1uW2kdK5Z3TjgCXB_1jkL6VJrgH3hoYn16MvFY19tzDE4OuSgKjYC7itbFpSJYHBfKLWt-xZYBpgCVhYn9K5neV_9-Zj7s9mOSjRUJ2IwEwVSYhR-j5ICF9WB"
      },
      {
        "type": "Email",
        "email": "test@example.com"
      },
      {
        "type": "SMS",
        "phone_number": "+1234567890"
      }
    ]
  }

​

7. 마이그레이션 테스트

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

• 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 또는 Cohort를 만듭니다. 세션 시간, 수신한 메시지 및 클릭 이벤트를 확인하세요.
  • 앱을 업데이트하지 않은 사용자만 계속 활성 상태이며 이 그룹에 포함되어야 합니다.
  • 이전 제공업체에서 이러한 사용자에게 푸시 및 In-App 메시지를 계속 보내 업데이트를 부드럽게 유도하세요.
  • OneSignal로 완전히 이동할 준비가 될 때까지 이전 제공업체에서 보내기를 중지하세요.
• 단계적 마이그레이션을 따르는 경우:
  • 이전 플랫폼에서 OneSignal 이전의 이전 앱 버전을 가진 사용자의 Segment 또는 Cohort를 만듭니다.
  • 이전 제공업체에서 이전 앱 사용자에게 푸시 및 In-App 메시지를 계속 보내 업데이트를 부드럽게 유도하세요.
  • OneSignal로 완전히 이동할 준비가 될 때까지 이전 제공업체에서 보내기를 중지하세요.
  • 다음 앱 릴리스에서 이전 푸시 제공업체의 코드를 제거하세요.