메인 콘텐츠로 건너뛰기
OneSignal service worker(OneSignalSDKWorker.js)는 웹 푸시 알림에 필요한 서버에 호스팅된 JavaScript 파일입니다. 사용자가 페이지를 벗어난 경우에도 사이트가 알림을 수신하고 표시할 수 있게 해줍니다.
Diagram showing the OneSignal service worker receiving a push event and displaying a notification
WordPress 플러그인을 사용하는 경우 service worker가 자동으로 추가됩니다. 이 가이드를 건너뛰고 WordPress 설정으로 돌아가세요.

​
Service worker 설정

OneSignal 푸시 알림을 위한 전용 OneSignalSDKWorker.js 파일을 생성합니다. 사이트에 이미 service worker가 있고 단일 파일을 사용하려면 대신 여러 service worker 결합을 참조하세요.
1

OneSignalSDKWorker.js 다운로드 또는 생성

Web SDK 설정 중에 OneSignal 대시보드에서 파일을 다운로드하거나 GitHub에서 다운로드하세요.또는 OneSignalSDKWorker.js라는 파일을 만들고 다음 한 줄의 코드를 작성하세요:
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
필요한 경우 파일 이름을 변경할 수 있습니다(예: onesignalsdkworker.js). 변경하는 경우 이 가이드의 OneSignalSDKWorker.js를 해당 파일 이름으로 교체하세요.
2

웹 서버에 업로드

OneSignalSDKWorker.js를 서버에 배치하여 HTTPS를 통해 공개적으로 접근할 수 있게 합니다. 파일 접근에 인증이나 로그인이 필요하지 않아야 합니다.권장: 페이지를 제공하지 않는 전용 하위 디렉토리(예: /push/onesignal/)에 파일을 호스팅하세요. 이렇게 하면 사이트의 다른 service worker(예: PWA 또는 AMP service worker)와의 충돌을 방지하고 URL 경로를 안정적으로 유지할 수 있습니다.
  • 예: https://yoursite.com/push/onesignal/OneSignalSDKWorker.js
대안: 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 줄이 표시되어야 합니다:
Browser displaying the single importScripts line inside OneSignalSDKWorker.js
404 오류, 빈 페이지 또는 로그인 프롬프트가 표시되면 파일이 올바르게 업로드되지 않았거나 인증 뒤에 있는 것입니다.
4

SDK 경로 구성 (하위 디렉토리만 해당)

파일을 사이트 루트에 배치한 경우 추가 구성이 필요하지 않습니다——다음 단계로 건너뛰세요.파일을 하위 디렉토리에 배치한 경우 SDK에 파일 위치를 알려주세요:

​
일반적인 사이트 설정

  1. OneSignal 대시보드에서 설정 > Push & In-App > Web 설정으로 이동합니다.
  2. 고급 푸시 설정에서 service worker 경로 및 파일 이름 사용자 지정을 활성화합니다.
OneSignal dashboard fields for service worker path, filename, and registration scope
필드설명예시
Path to service worker filesOneSignalSDKWorker.js가 호스팅된 디렉토리./push/onesignal/
Service worker filename.js 파일 이름.OneSignalSDKWorker.js
Service worker registration scopeservice worker가 제어하는 URL 경로. 파일이 호스팅된 디렉토리 이하에 있어야 합니다. 사용자 대면 페이지를 제공하지 않는 경로를 사용하세요./push/onesignal/

​
커스텀 코드 설정

OneSignal.init() 호출에서 serviceWorkerPath와 serviceWorkerParam을 전달하세요:
<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
<script>
  window.OneSignalDeferred = window.OneSignalDeferred || [];
  window.OneSignalDeferred.push(async function(OneSignal) {
    await OneSignal.init({
      appId: "YOUR_APP_ID",
      serviceWorkerPath: "push/onesignal/OneSignalSDKWorker.js",
      serviceWorkerParam: { scope: "/push/onesignal/" },
    });
  });
</script>
매개변수설명예시
serviceWorkerPath사이트 루트에서 .js 파일까지의 상대 경로(앞에 슬래시 없음)."push/onesignal/OneSignalSDKWorker.js"
serviceWorkerParam.scopeservice worker가 제어하는 URL 경로. 파일이 호스팅된 디렉토리 이하에 있어야 합니다. 사용자 대면 페이지를 제공하지 않는 경로를 사용하세요."/push/onesignal/"
5

Service worker 요구 사항 검토

OneSignalSDKWorker.js 파일은 다음 모든 요구 사항을 충족해야 합니다. 충족되지 않으면 푸시 알림이 작동하지 않습니다.
요구 사항세부 정보
공개 접근 가능브라우저에서 파일 URL로 이동하여 JavaScript 코드가 표시되는지 확인하세요.
올바른 콘텐츠 유형서버는 Content-Type: application/javascript; charset=utf-8을 반환해야 합니다.
동일 출처파일은 사이트와 동일한 도메인에 호스팅되어야 합니다. CDN과 하위 도메인은 허용되지 않습니다. MDN: 워커 등록을 참조하세요.
HTTPSService worker는 보안 컨텍스트가 필요합니다. localhost는 개발 중 유일한 예외입니다.
Service worker 설정이 완료되었습니다.

Web SDK 설정

다음 단계는 Web SDK 설정 가이드를 계속 따르세요.

​
여러 service worker 결합

사이트의 각 service worker 파일은 범위——어떤 페이지를 제어할지를 결정하는 URL 경로——에 등록됩니다. 주어진 범위에서 하나의 service worker만 활성화될 수 있습니다. 이미 service worker(예: PWA 또는 캐싱 워커)가 있고 OneSignal이 동일한 파일을 공유하게 하려면 결합할 수 있습니다.
별도의 범위를 가진 별도의 파일에 service worker를 유지하는 것이 유지 관리가 더 쉽고 충돌을 방지합니다. 설정에 단일 service worker 파일이 필요한 경우에만 결합하세요.
결합하려면 OneSignal importScripts 줄을 기존 service worker 파일에 추가하세요: 
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
importScripts("https://yoursite.com/your-other-service-worker.js");
결합 후, 결합된 파일의 경로와 파일 이름을 사용하여 4단계: SDK 경로 구성에 따라 OneSignal 구성을 업데이트하세요.

​
마이그레이션 가이드

이 섹션은 service worker 파일 경로, 파일 이름 또는 범위를 변경해야 하는 기존 OneSignal 고객을 위한 것입니다. 현재 구성을 변경할 특별한 이유가 없다면 이 단계를 따르지 마세요.
마이그레이션 이유:
  • 루트 범위 OneSignal service worker가 프로그레시브 웹 앱(PWA)과 충돌
  • Service worker가 AMP 또는 다른 캐싱 service worker와 충돌
  • 보안 정책이 루트 범위에서 타사 service worker 코드를 금지
옵션 1: 범위만 변경 (권장)범위만 변경하는 것이 가장 안전한 마이그레이션입니다. 파일이 현재 URL에 유지되므로 기존 구독자는 중단 없이 알림을 계속 받습니다.파일에 OneSignal 코드만 포함된 경우OneSignalSDKWorker.js에 다음만 포함되어 있는지 확인하세요:
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.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를 생성하세요:
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
3

OneSignal 구성 업데이트

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(또는 선택한 파일 이름)를 배치하고 다음을 작성하세요:
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
3

OneSignal 구성 업데이트

4단계: SDK 경로 구성에 설명된 대로 새 경로, 파일 이름 및 범위를 설정하세요.
4

구독자 마이그레이션 대기

신규 방문자와 재방문자는 자동으로 새 파일에 등록됩니다. 최소 1년을 기다리세요.
5

정리

보존 기간보다 오래된 비활성 사용자를 삭제하고, 이전 파일을 제거하세요.
파일에 OneSignal + 다른 코드가 포함된 경우위의 옵션 1: 범위만 변경 단계를 따르세요. 프로세스는 동일합니다.

​
일반적인 문제

​
service worker가 404를 반환하는 이유는 무엇인가요?

파일이 SDK가 예상하는 URL에 없습니다. 브라우저에서 전체 파일 URL로 이동하여 접근 가능한지 확인하세요. 파일을 하위 디렉토리에 배치한 경우 serviceWorkerPath(커스텀 코드) 또는 대시보드 경로 설정이 디렉토리와 파일 이름을 포함하여 실제 파일 위치와 일치하는지 확인하세요.

​
service worker 파일을 이동한 후 알림이 표시되지 않는 이유는 무엇인가요?

기존 구독자는 여전히 이전 service worker URL을 참조합니다. 브라우저는 푸시가 도착할 때마다 등록된 URL을 가져옵니다(최대 24시간 캐시). 이전 URL이 404를 반환하면 해당 구독자는 알림을 받지 못합니다. 구독자가 사이트를 재방문하여 자연스럽게 마이그레이션할 때까지 최소 1년 동안 이전 파일 호스팅을 계속하세요. 마이그레이션 가이드 및 웹 푸시 알림이 표시되지 않음 가이드를 참조하세요.

​
CDN 또는 하위 도메인에서 service worker를 호스팅할 수 있나요?

아니요. 브라우저는 service worker가 등록하는 페이지와 동일한 출처에서 제공되어야 한다고 요구합니다. 파일은 기본 도메인에 있어야 합니다——CDN, 하위 도메인 또는 다른 도메인은 안됩니다.

​
PWA가 OneSignal service worker와 충돌하는 이유는 무엇인가요?

둘 다 루트 범위(/)에 등록되어 있을 가능성이 높으며, 특정 범위에는 하나의 service worker만 등록될 수 있습니다. OneSignal service worker를 하위 디렉토리 범위(예: /push/onesignal/)로 이동하여 PWA가 루트 범위를 유지하도록 하거나, 여러 service worker 결합에 설명된 대로 service worker를 결합하세요.

​
OneSignalSDKWorker.js 파일 이름을 변경할 수 있나요?

예. 서버에 특정 명명 규칙(예: 모두 소문자)이 필요한 경우 onesignalsdkworker.js와 같은 이름으로 파일을 변경할 수 있습니다. 그렇게 하면 OneSignal 구성에서 파일 이름을 업데이트하세요——대시보드의 Service worker filename 필드 또는 OneSignal.init() 호출의 serviceWorkerPath 매개변수에서. 자세한 내용은 4단계를 참조하세요.

​
서버가 service worker 파일에 반환해야 하는 콘텐츠 유형은 무엇인가요?

서버는 Content-Type: application/javascript; charset=utf-8을 반환해야 합니다. 일부 서버 또는 CDN 구성은 잘못된 MIME 유형을 반환할 수 있으며, 이로 인해 브라우저가 service worker 등록을 거부합니다.