메인 콘텐츠로 건너뛰기

​
개요

이 가이드는 Web Push 알림을 위한 OneSignal Service Worker를 구성하는 방법을 다룹니다.
WordPress 플러그인을 사용하는 경우 OneSignal Service Worker 파일이 자동으로 추가되므로 이러한 파일을 사이트에 수동으로 추가해서는 안 됩니다. 자세한 내용은 WordPress setup으로 돌아가세요.

​
Service Worker란 무엇인가요?

Service Worker는 메인 페이지와 별도의 스레드에서 실행되는 백그라운드 스크립트입니다. 푸시 알림, 오프라인 캐싱 및 백그라운드 동기화와 같은 기능을 활성화합니다. 사이트가 등록할 때 설치되며 항상 실행되는 것은 아니지만 사용자가 이동한 후에도 이벤트(푸시 포함)를 처리하기 위해 깨어날 수 있습니다.

Service Worker 작동 방식

​
OneSignal의 Service Worker를 통합하는 방법

Web SDK Setup 가이드를 따르면 OneSignalSDKWorker.js Service Worker 파일이 제공됩니다.

​
.js 파일 다운로드

OneSignal 대시보드에서 OneSignalSDKWorker.js 파일을 다운로드하거나 여기에서 OneSignal Service Worker 파일 다운로드하세요.

​
.js 파일을 서버에 업로드

SDK는 기본적으로 사이트의 루트에서 OneSignalSDKWorker.js 파일을 찾습니다. 예: https://yoursite.com/OneSignalSDKWorker.js 이 파일을 사이트의 루트 디렉토리에 간단히 업로드하고 다음 단계는 Web push setup 가이드로 돌아갈 수 있습니다. 그러나 이 OneSignalSDKWorker.js 파일을 사용자를 절대 링크하지 않을 하위 디렉토리 경로에 배치하는 것이 좋습니다. 예: https://yoursite.com/push/onesignal/OneSignalSDKWorker.js. 이 파일을 루트에 배치할 수 있지만 현재 있거나 향후 추가할 수 있는 다른 Service Worker와 충돌할 수 있습니다. 또한 파일은 절대 변경되지 않을 영구적인 위치 경로에 배치되어야 합니다. Service Worker가 브라우저에 등록되면 변경하기 어렵습니다.

​
Service Worker 구성

OneSignal Service Worker 파일 OneSignalSDKWorker.js는 다음 요구 사항을 충족해야 합니다:
  • 파일은 공개적으로 액세스할 수 있어야 합니다. 즉, 브라우저에서 파일로 이동하여 코드를 볼 수 있어야 합니다.
  • 파일은 application/javascript; charset=utf-8의 content-type으로 제공되어야 합니다.
  • 파일은 동일한 사이트 원본(사이트 도메인)을 가리켜야 합니다. 다른 원본의 Service Worker를 가리키는 것은 허용되지 않습니다. CDN이나 하위 도메인은 사용할 수 없습니다.

​
Service Worker가 올바르게 설정되었는지 확인

브라우저에서 Service Worker를 방문하세요. Service Worker의 코드가 표시되어야 합니다: importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");

Service Worker 코드 예제

OneSignalSDKWorker.js 파일을 사이트의 루트에 업로드한 경우(https://yoursite.com/OneSignalSDKWorker.js에서 액세스 가능) 추가 조치가 필요하지 않습니다. 그러나 https://yoursite.com/push/onesignal/OneSignalSDKWorker.js와 같은 하위 디렉토리에 배치한 경우 다음과 같이 등록 범위를 설정해야 합니다:
  • Typical site setup
  • Custom Code Setup
OneSignal 대시보드에서 앱의 Settings > Push & In-App > Web Settings로 이동합니다Advanced Push Settings 아래에서 Customize service workers paths and filenames 스위치를 토글하고 데이터를 입력합니다.

일반 사이트 설정을 위한 Service Worker 구성

  • Path to service worker files는 OneSignal Service Worker 파일을 사용할 수 있는 디렉토리입니다. Service Worker가 https://yoursite.com/push/onesignal/OneSignalSDKWorker.js에서 사용 가능한 경우 경로는 /push/onesignal/입니다
  • Main and Updater service worker filenames는 Service Worker 파일의 이름입니다. OneSignalSDKWorker.js여야 하지만 변경한 경우 .js 파일 확장자를 사용해야 합니다. 예를 들어 서버가 파일을 소문자로 강제하는 경우 파일 이름을 onesignalsdkworker.js로 설정할 수 있습니다
  • Service worker registration scope는 이 파일이 작동할 수 있는 페이지입니다. 이는 사용자를 절대 링크하지 않고 현재 또는 향후 어떤 페이지도 호스팅하지 않을 경로여야 합니다. 일반적인 경로 예: /push/onesignal/ 및 범위는 동일한 경로이거나 /push/onesignal/js/와 같이 더 깊을 수 있습니다
Service Worker 설정이 완료되었습니다!다음 단계는 Web SDK Setup 가이드로 돌아가세요.

​
OneSignal Service Worker 마이그레이션 가이드

이 섹션은 이미 OneSignal을 사용하고 있고 많은 양의 Web Push Subscriber가 있으며 OneSignal Service Worker 설정을 변경하려는 고객만을 위한 것입니다. 특정 이유가 없는 한 권장하지 않습니다.
이 가이드는 현재 웹사이트에서 이미 OneSignal을 사용하고 있고 OneSignalSDKWorker.js 파일을 다른 경로 또는 범위로 이동하려는 고객만을 위한 것입니다.
OneSignal의 Service Worker는 기본적으로 루트 범위로 설정되어 사이트에 다음과 같은 문제를 일으킬 수 있습니다:
  • PWA와 충돌
  • AMP 설정과 충돌
  • 캐싱 Service Worker 또는 루트 범위가 필요한 다른 Service Worker 기능과 충돌
  • 사이트에 사용자가 방문할 페이지를 제어하는 범위에서 타사 Service Worker 코드 실행을 허용하지 않는 보안 요구 사항이 있습니다.
하나 이상이 해당되는 경우 이 가이드를 따르세요.

​
OneSignal Service Worker 범위 선택

사용자를 절대 링크하지 않지만 여전히 수행하는 작업이 명확한 Service Worker 범위 경로를 선택하는 것이 좋습니다. 예: /push/onesignal/. 이렇게 하면 PWA, AMP 또는 다른 캐싱 ServiceWorker가 사용자가 보는 페이지를 제어하여 올바르게 작동할 수 있습니다.동일한 위치 경로에 여러 Service Worker를 배치할 수 있지만 고유한 범위 경로를 가져야 합니다.
  • Option 1: Change scope
  • Option 2: Change filename or location

​
OneSignal Service Worker 범위를 안전하게 변경

가능하면 범위만 변경하는 것이 좋습니다. Service Worker 자체의 파일 이름이나 위치 경로를 변경하는 것은 추가 고려 사항이 있습니다. Subscriber를 잃거나 알림 표시 문제가 발생하지 않도록 어떤 시나리오가 적용되는지에 대한 세부 정보와 각 단계를 주의 깊게 살펴보세요

​
설정 유형 1. 기본 OneSignal 설정 - 범위 루트 ”/” 및 기본 OneSignalSDKWorker.js 콘텐츠

OneSignalSDKWorker.js 파일의 콘텐츠가 여기에서 OneSignal Service Worker 파일 다운로드에 있는 것과 동일한지 확인하세요. (필요할 수 있는 다른 non-OneSignal 코드가 없는 경우)이 경우 루트 범위에 다른 Service Worker를 배치할 공간을 만들기 위해 OneSignal 범위를 선택한 항목으로 변경할 수 있습니다. 위의 Customize Your Service Worker Integration를 참조하세요.
오늘 OneSignalSDKWorker.js가 도메인의 루트에 호스팅되지 않은 경우, 예를 들어 https://mysite.com/OneSignalSDKWorker.js와 같이 호스팅하지 않은 경우 장기간(1년 이상 권장) 동안 Service-Worker-Allowed 헤더와 함께 계속 호스팅해야 합니다.가능하면 백엔드 코드 또는 내부 문서에 주석을 추가하여 실수로 제거되지 않도록 하는 것이 좋습니다.

​
설정 유형 2. 일반적이지 않음 - 범위 루트 ”/” 및 OneSignalSDKWorker.js(또는 구성된 파일 이름)에 OneSignal + 기타 코드 또는 importScripts 포함

이것은 덜 일반적이지만 이 OneSignal 가이드 “Integrating Multiple Service Workers”를 따라 이미 수행했을 수 있습니다. 이 설정이 여전히 모든 요구 사항을 충족하는 경우 푸시 이벤트를 처리하는 병합된 ServiceWorker 파일을 분해하는 데 필요한 복잡하고 2단계 롤아웃으로 인해 설정을 그대로 유지하는 것이 좋습니다.
이 섹션은 OneSignal과 현재 Service Worker에 다음과 같은 다른 사용자 지정 코드 또는 importScript가 있는 경우 적용됩니다.
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
//그리고 동일한 파일의 다른 사이트별 코드 예제.
importScripts("https://site.com/my-other-service-worker.js");
1

기존 Service Worker 코드 유지

기존 ServiceWorker 파일의 importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js"); 줄 위에 코드 주석을 추가하여 장기간(1년 이상 권장, 사이트를 다시 방문하지 않는 사용자에게 푸시를 계속 보내려는 기간에 따라 다름) 동안 유지하세요. 예: // YYYY-MM-DD까지 유지: 새로운 OneSignal 전용 ServiceWorker로 마이그레이션하기 위해 다시 방문하지 않은 사용자에게 푸시가 올바르게 작동하는 데 필요합니다.
2

새 Service Worker 파일 생성

/push/onesignal/과 같은 다른 디렉토리 아래에 다음 단일 코드 줄로 새 OneSignalSDKWorker.js를 생성합니다 importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
3

"Customizing Your Service Worker Integration" 가이드를 따라 범위, 파일 이름 및 경로를 변경하세요.

4

이 시점에서 신규 및 재방문 사용자는 자동으로 새 OneSignal ServiceWorker에 구독됩니다.

5

1단계에서 언급한 시간(약 1년)을 기다리세요.

6

선택한 타임라인보다 오래된 사용자를 삭제하려면 OneSignal - "Delete Users" 가이드를 따르세요.

7

원래 Service Worker에서 주석 제거

마지막으로 원래 루트 ServiceWorker에서 주석과 함께 importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js"); 줄을 제거합니다.

​
OneSignal ServiceWorker 범위 마이그레이션 - FAQ

이름 또는 위치 경로를 변경하는 경우 원래 ServiceWorker 파일 URL을 계속 호스팅해야 하는 이유는 무엇인가요?
이는 새 파일 이름을 가져오기 위해 사이트를 다시 방문하지 않은 사용자에게 필요합니다. 원래 ServiceWorker 파일은 푸시를 보낼 때마다(캐시 만료 시간을 초과한 경우, 최대 캐시는 24시간) 브라우저에서 가져옵니다. 원래 ServiceWorker 파일을 사용할 수 없는 경우 푸시를 보낼 때 호스팅 제공업체에서 반환되는 404 오류가 급증합니다. 이로 인해 서버에 더 많은 요청이 발생할 수 있습니다. 또한 이는 해당 사용자가 새로운 OneSignal 기능 및 수정 사항을 얻지 못한다는 것을 의미합니다.