필요한 경우 파일 이름을 변경할 수 있습니다(예: onesignalsdkworker.js). 변경하는 경우 이 가이드의 OneSignalSDKWorker.js를 해당 파일 이름으로 교체하세요.
2
웹 서버에 업로드
OneSignalSDKWorker.js를 서버에 배치하여 HTTPS를 통해 공개적으로 접근할 수 있게 합니다. 파일 접근에 인증이나 로그인이 필요하지 않아야 합니다.권장: 페이지를 제공하지 않는 전용 하위 디렉토리(예: /push/onesignal/)에 파일을 호스팅하세요. 이렇게 하면 사이트의 다른 service worker(예: PWA 또는 AMP service worker)와의 충돌을 방지하고 URL 경로를 안정적으로 유지할 수 있습니다.
대안: OneSignal Web SDK는 기본적으로 사이트 루트(https://yoursite.com/OneSignalSDKWorker.js)에서 파일을 찾습니다. 루트 디렉토리에 파일을 업로드할 수 있지만, 루트 범위가 필요한 다른 service worker와 충돌할 수 있습니다. 예를 들어 PWA를 사용하는 경우 OneSignalSDKWorker.js를 하위 디렉토리에 배치하세요.
영구적인 URL 경로를 선택하세요. 브라우저가 특정 URL에 service worker를 등록하면 해당 URL 변경 시 마이그레이션이 필요합니다.
3
파일 접근 가능 여부 확인
브라우저에서 파일 URL로 이동하세요(예: https://yoursite.com/push/onesignal/OneSignalSDKWorker.js).1단계의 importScripts 줄이 표시되어야 합니다:
브라우저에서 예상되는 service worker 파일 내용
404 오류, 빈 페이지 또는 로그인 프롬프트가 표시되면 파일이 올바르게 업로드되지 않았거나 인증 뒤에 있는 것입니다.
4
SDK 경로 구성 (하위 디렉토리만 해당)
파일을 사이트 루트에 배치한 경우 추가 구성이 필요하지 않습니다——다음 단계로 건너뛰세요.파일을 하위 디렉토리에 배치한 경우 SDK에 파일 위치를 알려주세요:
사이트의 각 service worker 파일은 범위——어떤 페이지를 제어할지를 결정하는 URL 경로——에 등록됩니다. 주어진 범위에서 하나의 service worker만 활성화될 수 있습니다. 이미 service worker(예: PWA 또는 캐싱 워커)가 있고 OneSignal이 동일한 파일을 공유하게 하려면 결합할 수 있습니다.
별도의 범위를 가진 별도의 파일에 service worker를 유지하는 것이 유지 관리가 더 쉽고 충돌을 방지합니다. 설정에 단일 service worker 파일이 필요한 경우에만 결합하세요.
결합하려면 OneSignal importScripts 줄을 기존 service worker 파일에 추가하세요:
이 섹션은 service worker 파일 경로, 파일 이름 또는 범위를 변경해야 하는 기존 OneSignal 고객을 위한 것입니다. 현재 구성을 변경할 특별한 이유가 없다면 이 단계를 따르지 마세요.
service worker를 마이그레이션하는 시기와 방법
마이그레이션 이유:
루트 범위 OneSignal service worker가 프로그레시브 웹 앱(PWA)과 충돌
Service worker가 AMP 또는 다른 캐싱 service worker와 충돌
보안 정책이 루트 범위에서 타사 service worker 코드를 금지
옵션 1: 범위만 변경 (권장)범위만 변경하는 것이 가장 안전한 마이그레이션입니다. 파일이 현재 URL에 유지되므로 기존 구독자는 중단 없이 알림을 계속 받습니다.파일에 OneSignal 코드만 포함된 경우OneSignalSDKWorker.js에 다음만 포함되어 있는지 확인하세요:
4단계: SDK 경로 구성에 설명된 대로 대시보드 또는 serviceWorkerParam을 사용하여 범위를 업데이트하세요. 다른 변경은 필요하지 않습니다.
OneSignalSDKWorker.js가 현재 도메인 루트에 호스팅되어 있지 않다면, 최소 1년 동안 Service-Worker-Allowed 헤더와 함께 현재 URL에서 계속 호스팅해야 합니다. 파일이 실수로 제거되지 않도록 백엔드 코드나 내부 문서에 주석을 추가하세요.
파일에 OneSignal + 다른 코드가 포함된 경우Service worker에 추가적인 importScripts 호출이 포함되어 있을 수 있습니다(예: 여러 service worker 결합 가이드를 따른 경우). 현재 설정이 여전히 작동한다면 그대로 유지하세요——병합된 service worker 분리는 2단계 롤아웃이 필요합니다.분리해야 하는 경우:
1
기존 파일에 보존 주석 추가
현재 service worker의 OneSignal importScripts 줄 위에 추가하세요:
// KEEP until YYYY-MM-DD: Required for push delivery to subscribers who have not revisited.importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
날짜를 최소 1년 후로 설정하세요.
2
새로운 전용 OneSignal service worker 생성
하위 디렉토리(예: /push/onesignal/)에 다음만 포함하는 OneSignalSDKWorker.js를 생성하세요:
4단계: SDK 경로 구성에 설명된 대로 대시보드 또는 OneSignal.init()을 사용하여 새 경로와 범위를 설정하세요.
4
구독자 마이그레이션 대기
신규 방문자와 재방문자는 자동으로 새 service worker에 등록됩니다. 기존 구독자 대부분이 사이트를 재방문할 때까지 최소 1년을 기다리세요.
5
정리
선택한 보존 기간보다 오래된 비활성 사용자를 삭제하고, 원래 service worker 파일에서 OneSignal importScripts 줄을 제거하세요.
옵션 2: 파일 이름 또는 파일 위치 변경파일 이름이나 디렉토리 변경은 더 복잡합니다. 브라우저가 원래 등록된 URL에서 service worker를 가져오기 때문입니다. 사이트를 재방문하지 않은 구독자는 여전히 이전 URL을 참조합니다.
최소 1년 동안 원래 파일을 이전 URL에서 계속 호스팅해야 합니다. 제거하면 브라우저가 service worker를 업데이트하려 할 때 404 오류가 발생하고, 영향받는 구독자는 알림을 받지 못합니다.
파일에 OneSignal 코드만 포함된 경우
1
이전 파일에 보존 주석 추가
// KEEP until YYYY-MM-DD: Required for push delivery to subscribers still on the old service worker URL.importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
2
새 위치에 새 파일 생성
새 디렉토리에 OneSignalSDKWorker.js(또는 선택한 파일 이름)를 배치하고 다음을 작성하세요:
파일이 SDK가 예상하는 URL에 없습니다. 브라우저에서 전체 파일 URL로 이동하여 접근 가능한지 확인하세요. 파일을 하위 디렉토리에 배치한 경우 serviceWorkerPath(커스텀 코드) 또는 대시보드 경로 설정이 디렉토리와 파일 이름을 포함하여 실제 파일 위치와 일치하는지 확인하세요.
기존 구독자는 여전히 이전 service worker URL을 참조합니다. 브라우저는 푸시가 도착할 때마다 등록된 URL을 가져옵니다(최대 24시간 캐시). 이전 URL이 404를 반환하면 해당 구독자는 알림을 받지 못합니다. 구독자가 사이트를 재방문하여 자연스럽게 마이그레이션할 때까지 최소 1년 동안 이전 파일 호스팅을 계속하세요. 마이그레이션 가이드 및 웹 푸시 알림이 표시되지 않음 가이드를 참조하세요.
둘 다 루트 범위(/)에 등록되어 있을 가능성이 높으며, 특정 범위에는 하나의 service worker만 등록될 수 있습니다. OneSignal service worker를 하위 디렉토리 범위(예: /push/onesignal/)로 이동하여 PWA가 루트 범위를 유지하도록 하거나, 여러 service worker 결합에 설명된 대로 service worker를 결합하세요.
예. 서버에 특정 명명 규칙(예: 모두 소문자)이 필요한 경우 onesignalsdkworker.js와 같은 이름으로 파일을 변경할 수 있습니다. 그렇게 하면 OneSignal 구성에서 파일 이름을 업데이트하세요——대시보드의 Service worker filename 필드 또는 OneSignal.init() 호출의 serviceWorkerPath 매개변수에서. 자세한 내용은 4단계를 참조하세요.
