> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OneSignal service worker

> OneSignalSDKWorker.js 파일을 설정하고 구성하여 웹사이트가 OneSignal을 통해 웹 푸시 알림을 수신하고 표시할 수 있도록 합니다.

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

<Frame caption="OneSignal service worker가 푸시 알림을 처리하는 방식">
  <img src="https://mintcdn.com/onesignal/MUgio66t0sYhGEvj/images/docs/67882a5-onesignsal-service-worker.jpg?fit=max&auto=format&n=MUgio66t0sYhGEvj&q=85&s=e0b50cfe6ccc36c1b2b6d36219b6e3ad" alt="Diagram showing the OneSignal service worker receiving a push event and displaying a notification" width="2016" height="949" data-path="images/docs/67882a5-onesignsal-service-worker.jpg" />
</Frame>

<Note>
  WordPress 플러그인을 사용하는 경우 service worker가 자동으로 추가됩니다. 이 가이드를 건너뛰고 [WordPress 설정](./wordpress)으로 돌아가세요.
</Note>

## Service worker 설정

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

<Steps>
  <Step title="OneSignalSDKWorker.js 다운로드 또는 생성">
    [Web SDK 설정](./web-sdk-setup) 중에 OneSignal 대시보드에서 파일을 다운로드하거나 [GitHub에서 다운로드](https://github.com/OneSignal/OneSignal-Website-SDK/files/11480764/OneSignalSDK-v16-ServiceWorker.zip)하세요.

    또는 `OneSignalSDKWorker.js`라는 파일을 만들고 다음 한 줄의 코드를 작성하세요:

    ```javascript theme={null}
    importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
    ```

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

  <Step title="웹 서버에 업로드">
    `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`를 하위 디렉토리에 배치하세요.

    <Warning>
      **영구적인** URL 경로를 선택하세요. 브라우저가 특정 URL에 service worker를 등록하면 해당 URL 변경 시 [마이그레이션](#migration-guide)이 필요합니다.
    </Warning>
  </Step>

  <Step title="파일 접근 가능 여부 확인">
    브라우저에서 파일 URL로 이동하세요(예: `https://yoursite.com/push/onesignal/OneSignalSDKWorker.js`).

    1단계의 `importScripts` 줄이 표시되어야 합니다:

    <Frame caption="브라우저에서 예상되는 service worker 파일 내용">
      <img src="https://mintcdn.com/onesignal/eSOC1PsvyAo3Gten/images/push/service-worker-code-example.png?fit=max&auto=format&n=eSOC1PsvyAo3Gten&q=85&s=3add122d37c9f12a39f1d7e3d40eeaba" alt="Browser displaying the single importScripts line inside OneSignalSDKWorker.js" width="1678" height="322" data-path="images/push/service-worker-code-example.png" />
    </Frame>

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

  <Step title="SDK 경로 구성 (하위 디렉토리만 해당)">
    파일을 사이트 루트에 배치한 경우 추가 구성이 필요하지 않습니다——다음 단계로 건너뛰세요.

    파일을 하위 디렉토리에 배치한 경우 SDK에 파일 위치를 알려주세요:

    #### 일반적인 사이트 설정

    1. OneSignal 대시보드에서 **설정 > Push & In-App > Web 설정**으로 이동합니다.
    2. **고급 푸시 설정**에서 **service worker 경로 및 파일 이름 사용자 지정**을 활성화합니다.

    <Frame caption="대시보드의 service worker 경로 구성">
      <img src="https://mintcdn.com/onesignal/npQH4TNAoIbyiAie/images/dashboard/service-worker-configuration-typical-site-setup.png?fit=max&auto=format&n=npQH4TNAoIbyiAie&q=85&s=0bc69998eea5273d287af408c6e925b3" alt="OneSignal dashboard fields for service worker path, filename, and registration scope" width="1840" height="794" data-path="images/dashboard/service-worker-configuration-typical-site-setup.png" />
    </Frame>

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

    #### 커스텀 코드 설정

    [`OneSignal.init()`](./web-push-custom-code-setup) 호출에서 `serviceWorkerPath`와 `serviceWorkerParam`을 전달하세요:

    ```html theme={null}
    <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.scope` | service worker가 제어하는 URL 경로. 파일이 호스팅된 디렉토리 이하에 있어야 합니다. 사용자 대면 페이지를 제공하지 않는 경로를 사용하세요. | `"/push/onesignal/"`                     |
  </Step>

  <Step title="Service worker 요구 사항 검토">
    `OneSignalSDKWorker.js` 파일은 다음 모든 요구 사항을 충족해야 합니다. 충족되지 않으면 푸시 알림이 작동하지 않습니다.

    | 요구 사항          | 세부 정보                                                                                                                                                                                         |
    | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **공개 접근 가능**   | 브라우저에서 파일 URL로 이동하여 JavaScript 코드가 표시되는지 확인하세요.                                                                                                                                               |
    | **올바른 콘텐츠 유형** | 서버는 `Content-Type: application/javascript; charset=utf-8`을 반환해야 합니다.                                                                                                                          |
    | **동일 출처**      | 파일은 사이트와 동일한 도메인에 호스팅되어야 합니다. CDN과 하위 도메인은 허용되지 않습니다. [MDN: 워커 등록](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers#Registering_your_worker)을 참조하세요. |
    | **HTTPS**      | Service worker는 보안 컨텍스트가 필요합니다. `localhost`는 개발 중 유일한 예외입니다.                                                                                                                                  |

    <Check>
      Service worker 설정이 완료되었습니다.
    </Check>

    <Card title="Web SDK 설정" icon="browsers" href="./web-sdk-setup">
      다음 단계는 Web SDK 설정 가이드를 계속 따르세요.
    </Card>
  </Step>
</Steps>

***

## 여러 service worker 결합

사이트의 각 service worker 파일은 **범위**——어떤 페이지를 제어할지를 결정하는 URL 경로——에 등록됩니다. 주어진 범위에서 하나의 service worker만 활성화될 수 있습니다. 이미 service worker(예: PWA 또는 캐싱 워커)가 있고 OneSignal이 동일한 파일을 공유하게 하려면 결합할 수 있습니다.

<Warning>
  별도의 범위를 가진 별도의 파일에 service worker를 유지하는 것이 유지 관리가 더 쉽고 충돌을 방지합니다. 설정에 단일 service worker 파일이 필요한 경우에만 결합하세요.
</Warning>

결합하려면 OneSignal `importScripts` 줄을 **기존** service worker 파일에 추가하세요:

```javascript theme={null}
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
importScripts("https://yoursite.com/your-other-service-worker.js");
```

결합 후, 결합된 파일의 경로와 파일 이름을 사용하여 [4단계: SDK 경로 구성](#step-4-configure-the-sdk-path-subdirectory-only)에 따라 OneSignal 구성을 업데이트하세요.

***

## 마이그레이션 가이드

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

<Accordion title="service worker를 마이그레이션하는 시기와 방법">
  **마이그레이션 이유:**

  * 루트 범위 OneSignal service worker가 프로그레시브 웹 앱(PWA)과 충돌
  * Service worker가 AMP 또는 다른 캐싱 service worker와 충돌
  * 보안 정책이 루트 범위에서 타사 service worker 코드를 금지

  **옵션 1: 범위만 변경 (권장)**

  범위만 변경하는 것이 가장 안전한 마이그레이션입니다. 파일이 현재 URL에 유지되므로 기존 구독자는 중단 없이 알림을 계속 받습니다.

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

  `OneSignalSDKWorker.js`에 다음만 포함되어 있는지 확인하세요:

  ```javascript theme={null}
  importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
  ```

  [4단계: SDK 경로 구성](#step-4-configure-the-sdk-path-subdirectory-only)에 설명된 대로 대시보드 또는 `serviceWorkerParam`을 사용하여 범위를 업데이트하세요. 다른 변경은 필요하지 않습니다.

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

  **파일에 OneSignal + 다른 코드가 포함된 경우**

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

  분리해야 하는 경우:

  <Steps>
    <Step title="기존 파일에 보존 주석 추가">
      현재 service worker의 OneSignal `importScripts` 줄 위에 추가하세요:

      ```javascript theme={null}
      // 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년** 후로 설정하세요.
    </Step>

    <Step title="새로운 전용 OneSignal service worker 생성">
      하위 디렉토리(예: `/push/onesignal/`)에 다음만 포함하는 `OneSignalSDKWorker.js`를 생성하세요:

      ```javascript theme={null}
      importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
      ```
    </Step>

    <Step title="OneSignal 구성 업데이트">
      [4단계: SDK 경로 구성](#step-4-configure-the-sdk-path-subdirectory-only)에 설명된 대로 대시보드 또는 `OneSignal.init()`을 사용하여 새 경로와 범위를 설정하세요.
    </Step>

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

    <Step title="정리">
      선택한 보존 기간보다 오래된 [비활성 사용자를 삭제](./delete-users)하고, 원래 service worker 파일에서 OneSignal `importScripts` 줄을 제거하세요.
    </Step>
  </Steps>

  **옵션 2: 파일 이름 또는 파일 위치 변경**

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

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

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

  <Steps>
    <Step title="이전 파일에 보존 주석 추가">
      ```javascript theme={null}
      // 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");
      ```
    </Step>

    <Step title="새 위치에 새 파일 생성">
      새 디렉토리에 `OneSignalSDKWorker.js`(또는 선택한 파일 이름)를 배치하고 다음을 작성하세요:

      ```javascript theme={null}
      importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
      ```
    </Step>

    <Step title="OneSignal 구성 업데이트">
      [4단계: SDK 경로 구성](#step-4-configure-the-sdk-path-subdirectory-only)에 설명된 대로 새 경로, 파일 이름 및 범위를 설정하세요.
    </Step>

    <Step title="구독자 마이그레이션 대기">
      신규 방문자와 재방문자는 자동으로 새 파일에 등록됩니다. 최소 1년을 기다리세요.
    </Step>

    <Step title="정리">
      보존 기간보다 오래된 [비활성 사용자를 삭제](./delete-users)하고, 이전 파일을 제거하세요.
    </Step>
  </Steps>

  **파일에 OneSignal + 다른 코드가 포함된 경우**

  위의 **옵션 1: 범위만 변경** 단계를 따르세요. 프로세스는 동일합니다.
</Accordion>

***

## 일반적인 문제

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

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

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

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

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

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

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

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

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

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

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

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