OneSignal service worker

OneSignal service worker(OneSignalSDKWorker.js)는 웹 푸시 알림에 필요한 서버에 호스팅된 JavaScript 파일입니다. 사용자가 페이지를 벗어난 경우에도 사이트가 알림을 수신하고 표시할 수 있게 해줍니다.

WordPress 플러그인을 사용하는 경우 이 가이드를 건너뛰세요. 플러그인은 sdk_files 디렉토리에 OneSignalSDKWorker.js를 호스팅하고 경로를 자동으로 구성합니다. 파일을 사이트 루트에 업로드하거나 대시보드 또는 코드에서 사용자 지정 경로를 설정하지 마세요. WordPress 설정을 참조하세요. Shopify도 워커를 자동으로 배포합니다. Shopify 설정을 참조하세요.

Service worker 설정

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

OneSignalSDKWorker.js 다운로드 또는 생성

Web SDK 설정 중에 OneSignal 대시보드에서 파일을 다운로드하거나 GitHub에서 다운로드하세요.또는 OneSignalSDKWorker.js라는 파일을 만들고 다음 한 줄의 코드를 작성하세요:

importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");

필요한 경우 파일 이름을 변경할 수 있습니다(예: onesignalsdkworker.js, ossw.js). 변경하는 경우 이 가이드의 OneSignalSDKWorker.js를 해당 파일 이름으로 교체하세요.

웹 서버에 업로드

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 변경 시 마이그레이션이 필요합니다.

파일 접근 가능 여부 확인

브라우저에서 파일 URL로 이동하세요(예: https://yoursite.com/push/onesignal/OneSignalSDKWorker.js). 1단계의 importScripts 줄이 표시되어야 합니다:

Browser displaying the single importScripts line inside OneSignalSDKWorker.js — 브라우저에서 예상되는 service worker 파일 내용

404 오류, 빈 페이지 또는 로그인 프롬프트가 표시되면 파일이 올바르게 업로드되지 않았거나 인증 뒤에 있는 것입니다.

SDK에 파일 위치 알려주기

Web SDK는 다른 위치를 알려주지 않는 한 사이트 루트(https://yoursite.com/OneSignalSDKWorker.js)에서 OneSignalSDKWorker.js를 찾습니다. 알려주는 방법은 통합 유형에 따라 다릅니다.파일을 사이트 루트에 배치한 경우 추가 구성이 필요하지 않습니다. 다음 단계로 건너뛰세요.파일을 하위 디렉토리에 배치한 경우 경로를 설정해야 합니다. 일반 사이트는 대시보드에서 설정합니다. 사용자 지정 코드는 OneSignal.init()에서 설정합니다. 둘을 혼합하면 작동하지 않습니다: 대시보드 경로 필드는 사용자 지정 코드에 적용되지 않고, serviceWorkerPath는 일반 사이트에 적용되지 않습니다.

일반 사이트

OneSignal 대시보드에서 경로를 설정하세요. 코드에서 serviceWorkerPath를 전달하지 마세요.

Settings > Push & In-App > Web으로 이동합니다.
Advanced Push Settings에서 Customize service worker paths and filenames를 활성화합니다.

OneSignal dashboard fields for service worker path, filename, and registration scope — 대시보드의 service worker 경로 구성

필드	설명	예시
Path to service worker files	`OneSignalSDKWorker.js`가 호스팅된 디렉토리.	`/push/onesignal/`
Service worker filename	`.js` 파일 이름.	`OneSignalSDKWorker.js`
Service worker registration scope	service worker가 제어하는 URL 경로. 파일이 호스팅된 디렉토리 이하에 있어야 합니다. 사용자 대면 페이지를 제공하지 않는 경로를 사용하세요.	`/push/onesignal/`

일반 사이트 절차는 Web SDK 설정을 참조하세요.

사용자 지정 코드

OneSignal.init() 호출에서 serviceWorkerPath와 serviceWorkerParam을 전달하세요. 사용자 지정 코드는 대시보드의 Customize service worker paths and filenames 필드를 사용하지 않습니다.

<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_ONESIGNAL_APP_ID",
      serviceWorkerPath: "push/onesignal/OneSignalSDKWorker.js",
      serviceWorkerParam: { scope: "/push/onesignal/" },
    });
  });
</script>

매개변수	설명	예시
`serviceWorkerPath`	사이트 루트에서 `.js` 파일까지의 상대 경로(앞에 슬래시 없음).	`"push/onesignal/OneSignalSDKWorker.js"`
`serviceWorkerParam.scope`	service worker가 제어하는 URL 경로. 파일이 호스팅된 디렉토리 이하에 있어야 합니다. 사용자 대면 페이지를 제공하지 않는 경로를 사용하세요.	`"/push/onesignal/"`

파일이 사이트 루트에 없고 이러한 옵션을 생략하면 SDK는 여전히 https://yoursite.com/OneSignalSDKWorker.js를 가져오고 등록에 실패합니다.전체 init 스니펫에 이러한 옵션을 추가하려면 사용자 지정 코드 설정을 참조하세요.

Service worker 요구 사항 검토

푸시 알림이 작동하려면 OneSignalSDKWorker.js 파일이 다음 모든 요구 사항을 충족해야 합니다.

요구 사항	세부 정보
공개 접근 가능	브라우저에서 파일 URL로 이동하여 JavaScript 코드가 표시되는지 확인하세요.
올바른 콘텐츠 유형	서버는 `Content-Type: application/javascript; charset=utf-8`을 반환해야 합니다.
동일 출처	파일은 사이트와 동일한 도메인에 호스팅되어야 합니다. CDN과 하위 도메인은 허용되지 않습니다. MDN: 워커 등록을 참조하세요.
HTTPS	Service 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");

결합 후, OneSignal 구성이 기존 service worker 파일을 가리키도록 업데이트하세요. 결합된 파일의 경로와 파일 이름을 사용하여 SDK에 파일 위치 알려주기를 따르세요.

마이그레이션 가이드

이 섹션은 service worker 파일 경로, 파일 이름 또는 범위를 변경해야 하는 기존 OneSignal 고객을 위한 것입니다. 현재 구성을 변경할 특별한 이유가 없다면 이 단계를 따르지 마세요.

service worker를 마이그레이션하는 시기와 방법

마이그레이션 이유:

루트 범위 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");

SDK에 파일 위치 알려주기에 설명된 대로 대시보드(일반 사이트) 또는 serviceWorkerParam(사용자 지정 코드)을 사용하여 범위를 업데이트하세요. 다른 변경은 필요하지 않습니다.

OneSignalSDKWorker.js가 현재 도메인 루트에 호스팅되어 있지 않다면, 최소 1년 동안 Service-Worker-Allowed 헤더와 함께 현재 URL에서 계속 호스팅해야 합니다. 파일이 실수로 제거되지 않도록 백엔드 코드나 내부 문서에 주석을 추가하세요.

파일에 OneSignal + 다른 코드가 포함된 경우Service worker에 추가적인 importScripts 호출이 포함되어 있을 수 있습니다(예: 여러 service worker 결합 가이드를 따른 경우). 현재 설정이 여전히 작동한다면 그대로 유지하세요—병합된 service worker 분리는 2단계 롤아웃이 필요합니다.분리해야 하는 경우:

기존 파일에 보존 주석 추가

현재 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년 후로 설정하세요.

새로운 전용 OneSignal service worker 생성

하위 디렉토리(예: /push/onesignal/)에 다음만 포함하는 OneSignalSDKWorker.js를 생성하세요:

importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");

OneSignal 구성 업데이트

SDK에 파일 위치 알려주기에 설명된 대로 대시보드(일반 사이트) 또는 OneSignal.init()(사용자 지정 코드)을 사용하여 새 경로와 범위를 설정하세요.

구독자 마이그레이션 대기

신규 방문자와 재방문자는 자동으로 새 service worker에 등록됩니다. 기존 구독자 대부분이 사이트를 재방문할 때까지 최소 1년을 기다리세요.

정리

선택한 보존 기간보다 오래된 비활성 사용자를 삭제하고, 원래 service worker 파일에서 OneSignal importScripts 줄을 제거하세요.

옵션 2: 파일 이름 또는 파일 위치 변경파일 이름이나 디렉토리 변경은 더 복잡합니다. 브라우저가 원래 등록된 URL에서 service worker를 가져오기 때문입니다. 사이트를 재방문하지 않은 구독자는 여전히 이전 URL을 참조합니다.

최소 1년 동안 원래 파일을 이전 URL에서 계속 호스팅해야 합니다. 제거하면 브라우저가 service worker를 업데이트하려 할 때 404 오류가 발생하고, 영향받는 구독자는 알림을 받지 못합니다.

파일에 OneSignal 코드만 포함된 경우

이전 파일에 보존 주석 추가

// 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");

새 위치에 새 파일 생성

새 디렉토리에 OneSignalSDKWorker.js(또는 선택한 파일 이름)를 배치하고 다음을 작성하세요:

importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");

OneSignal 구성 업데이트

SDK에 파일 위치 알려주기에 설명된 대로 새 경로, 파일 이름 및 범위를 설정하세요.

구독자 마이그레이션 대기

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

정리

보존 기간보다 오래된 비활성 사용자를 삭제하고, 이전 파일을 제거하세요.

파일에 OneSignal + 다른 코드가 포함된 경우위의 옵션 1: 범위만 변경 단계를 따르세요. 프로세스는 동일합니다.

자주 묻는 질문

이 가이드가 WordPress에 적용되나요?

아니요. WordPress 플러그인은 sdk_files 디렉토리에 OneSignalSDKWorker.js를 호스팅하고 등록합니다. 워커를 사이트 루트에 업로드하거나 코드에서 serviceWorkerPath를 설정하지 마세요. WordPress 설정을 참조하세요.

일반 사이트와 사용자 지정 코드에서 service worker 경로를 어떻게 설정하나요?

Web SDK는 사용자 지정 경로를 설정하지 않는 한 사이트 루트에서 OneSignalSDKWorker.js를 찾습니다. 일반 사이트는 대시보드의 Customize service worker paths and filenames에서 해당 경로를 설정합니다. 사용자 지정 코드는 OneSignal.init()의 serviceWorkerPath 및 serviceWorkerParam으로 코드에서 설정합니다. 대시보드 경로 필드는 사용자 지정 코드에 적용되지 않습니다. SDK에 파일 위치 알려주기를 참조하세요.

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

파일이 SDK가 예상하는 URL에 없습니다. 브라우저에서 전체 파일 URL로 이동하여 접근 가능한지 확인하세요. 파일을 하위 디렉토리에 배치한 경우 구성된 경로가 디렉토리와 파일 이름을 포함하여 실제 파일 위치와 일치해야 합니다. 일반 사이트: 대시보드 경로 설정을 확인하세요. 사용자 지정 코드: OneSignal.init()의 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와 같은 이름으로 파일을 변경하세요. 일반 사이트: 대시보드의 Service worker filename 필드를 업데이트하세요. 사용자 지정 코드: OneSignal.init() 호출의 serviceWorkerPath를 업데이트하세요. SDK에 파일 위치 알려주기를 참조하세요.

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

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

개발자 문서

모바일 SDKs

웹 SDKs

실시간 현황

데스크탑 & 워치 설정

OneSignal service worker

Service worker 설정

일반 사이트

사용자 지정 코드

Web SDK 설정

여러 service worker 결합

마이그레이션 가이드

자주 묻는 질문

이 가이드가 WordPress에 적용되나요?

일반 사이트와 사용자 지정 코드에서 service worker 경로를 어떻게 설정하나요?

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

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

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

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

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

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

​Service worker 설정

​일반 사이트

​사용자 지정 코드

Web SDK 설정

​여러 service worker 결합

​마이그레이션 가이드

​자주 묻는 질문

​이 가이드가 WordPress에 적용되나요?

​일반 사이트와 사용자 지정 코드에서 service worker 경로를 어떻게 설정하나요?

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

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

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

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

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

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

Service worker 설정

일반 사이트

사용자 지정 코드

여러 service worker 결합

마이그레이션 가이드

자주 묻는 질문

이 가이드가 WordPress에 적용되나요?

일반 사이트와 사용자 지정 코드에서 service worker 경로를 어떻게 설정하나요?

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

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

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

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

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

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