Web SDK 문제 해결

개요

이 가이드는 OneSignal Web SDK 설정 문제 해결 과정을 안내합니다. 계속하기 전에 Web SDK 설정을 검토하여 모든 단계를 완료했는지 확인하세요. 웹 푸시가 작동하지 않는 것처럼 보이는 가장 일반적인 이유는 브라우저 및 기기의 알림 설정과 관련이 있습니다:

브라우저 호환성

사용자는 웹 권한 프롬프트를 볼 수 있지만 시크릿, 프라이빗 또는 게스트 브라우저 모드에서는 푸시 알림을 구독할 수 없습니다.

운영 체제별 브라우저 호환성

Browser	Windows	macOS	Android	iOS
Chrome	✅	✅	✅	✅ ¹
Firefox	✅	✅	✅	✅ ¹
Safari 10+	❌	✅	❌	✅ ¹
Microsoft Edge	✅	✅	✅	✅ ¹
Opera ²	✅	✅	✅	✅ ¹
Samsung Internet ²	❌	❌	✅	✅ ¹
Yandex ²	✅	✅	✅	✅ ¹
UC Browser ²	✅	❌	✅	✅ ¹
Internet Explorer	❌	❌	❌	❌
DuckDuckGo	❌	❌	❌	❌

¹ iOS는 웹 앱 설치가 필요합니다(iOS 웹 푸시 설정 참조)² Chromium 기반 브라우저는 OneSignal 분석에서 “Chrome”으로 표시됩니다

기기 알림 설정

기기 알림 설정은 웹 푸시 알림이 기기에 표시되지 않는 가장 일반적인 원인입니다. 다른 원인을 확인하기 전에 집중 모드(방해 금지, 배터리 부족 등)를 포함한 다음 설정을 먼저 확인하세요.

아래 탭에서 올바른 운영 체제를 선택하세요. Windows, macOS, Android, iOS가 표시되어야 합니다.

Windows
macOS
Android
iOS

Windows 10 알림 설정

시작 > 설정 > 알림 및 작업 > 앱 및 기타 보낸 사람의 알림 받기를 선택합니다
사이트와 브라우저도 활성화되어 있는지 확인하세요.

Windows 11 알림 설정:

시작 > 설정 > 시스템 > 알림을 선택합니다

알림을 켭니다
방해 금지를 끕니다 (테스트 중에는 이 옵션을 비활성화하면 푸시가 표시됩니다)
앱 및 기타 보낸 사람의 알림 아래로 스크롤합니다

Windows 11 Settings showing the Notifications from apps and other senders list — Windows 11 앱 및 기타 보낸 사람의 알림

브라우저가 켜져 있는지 확인하세요.

프롬프트 표시 문제

다음은 웹 푸시 알림 프롬프트가 예상대로 표시되지 않는 일반적인 이유입니다.

프롬프트가 구성되었는지 확인

웹 권한 프롬프트 설정을 검토하여 프롬프트를 구성했으며 다양한 브라우저 동작을 이해하고 있는지 확인하세요.예를 들어, Safari와 같은 일부 브라우저는 네이티브 프롬프트가 나타나기 전에 사용자 제스처(버튼 클릭)가 필요합니다. 각 브라우저에 대한 자세한 내용은 웹 권한 프롬프트 > 네이티브 권한 프롬프트 섹션에서 확인할 수 있습니다.

브라우저 호환성, 시크릿, 프라이빗 브라우저 또는 게스트 브라우저 모드 확인

브라우저는 이러한 모드에서 사용자가 알림을 구독하는 것을 허용하지 않습니다. 이것이 슬라이드 프롬프트는 표시되지만 네이티브 권한 프롬프트는 표시되지 않는 이유입니다.웹 푸시를 지원하는 브라우저와 기기를 사용하고 있는지 확인하세요.

브라우저의 알림 설정 확인

브라우저 설정으로 이동하여 “알림” 권한 설정을 확인하세요. Chrome 예시: chrome://settings/content/notifications

이 예시에서:

사용자가 “사이트에서 알림을 보낼 수 없음”을 선택하여 네이티브 권한 프롬프트가 표시되지 않습니다. 네이티브 권한 프롬프트를 표시하려면 “사이트에서 알림 전송을 요청할 수 있음”으로 표시되어야 합니다.
사용자가 https://yoursite.com을 “알림 전송이 허용되지 않음” 목록에 추가하여 네이티브 권한 프롬프트가 표시되지 않습니다. 네이티브 권한 프롬프트를 표시하려면 이 목록에서 제거해야 합니다.

브라우저별 문서:

Chrome - 이 페이지에서는 설정 > 개인정보 및 보안 > 사이트 설정 > 알림으로 이동하여 Chrome에서 알림을 관리하는 방법을 설명하며, 여기서 기본 동작을 제어하고 개별 웹사이트에 대한 권한을 관리할 수 있습니다.
Firefox - 이 가이드는 Firefox의 웹 푸시 알림을 다루며, 설정 > 개인정보 및 보안 > 알림을 통해 알림 권한을 관리하는 방법과 주소 표시줄의 사이트 정보 아이콘을 통해 특정 사이트에 대한 권한을 제어하는 방법을 설명합니다.
Safari - 이 Apple 가이드는 Safari > 환경설정 > 웹사이트 > 알림을 통해 Mac에서 Safari 알림을 사용자 지정하는 방법을 설명하며, 여기서 어떤 사이트가 알림을 보낼 수 있는지 관리하고 시스템 환경설정을 통해 알림 동작을 제어할 수 있습니다.
Edge - 이 문서에서는 설정 > 개인정보, 검색 및 서비스 > 사이트 권한 > 알림으로 이동하거나 주소 표시줄의 사이트 정보 아이콘을 클릭하여 Edge 알림을 관리하는 방법을 자세히 설명합니다.

iOS/iPadOS 요구 사항이 충족되지 않음

iOS의 경우 사용자에게 구독을 요청하기 위한 몇 가지 추가 요구 사항이 있습니다. 자세한 내용은 iOS/iPadOS용 모바일 웹 푸시 가이드에서 확인할 수 있습니다.

문제 해결 단계

위의 사항을 확인한 후 다음 단계에 따라 OneSignal Web SDK 설정 문제를 해결하세요.

브라우저 개발자 도구 콘솔 열기

브라우저의 개발자 도구를 사용하면 OneSignal Web SDK와 상호 작용하고 로깅을 활성화하여 오류를 확인할 수 있습니다.

Desktop
Android
iOS

Chrome: 페이지를 마우스 오른쪽 버튼으로 클릭하고 검사를 클릭한 다음 열리는 팝업 창의 콘솔 탭을 클릭합니다.
Firefox: 페이지를 마우스 오른쪽 버튼으로 클릭하고 요소 검사를 클릭한 다음 열리는 팝업 창의 콘솔 탭을 클릭합니다.
Safari: Safari → 환경설정 → 고급으로 이동하여 메뉴 막대에서 개발자용 메뉴 보기가 체크되어 있는지 확인합니다. 그런 다음 웹페이지에서 마우스 오른쪽 버튼을 클릭하고 요소 검사를 클릭한 다음 열리는 팝업 창의 콘솔 탭을 클릭합니다.

Browser developer tools console open on a webpage — 데스크톱 개발자 도구 콘솔

Android의 Chrome: USB 디버깅을 활성화하고 기기를 컴퓨터에 연결한 다음 데스크톱 Chrome 브라우저에서 chrome://inspect#devices로 개발자 도구에 액세스합니다.
Android의 Firefox: USB 디버깅을 활성화하고 기기를 컴퓨터에 연결한 다음 데스크톱 Firefox 브라우저에서 about:debugging으로 개발자 도구에 액세스합니다.

Web SDK 로깅 활성화

개발자 도구 콘솔에서 다음 명령을 실행합니다:

OneSignal.Debug.setLogLevel('trace');

결과로 undefined가 표시되어야 합니다.
탭을 닫고 동일한 페이지에 대해 새 탭을 엽니다. 새로고침만으로는 모든 SDK 초기화 이벤트가 트리거되지 않습니다.
콘솔에서 OneSignal SDK 로그가 표시되기 시작합니다.

Browser console showing OneSignal SDK trace-level log output — 자세한 SDK 로그가 있는 콘솔

구성 오류

OneSignal이 초기화된 후 다음과 같은 오류가 발생할 수 있습니다:

오류: SDK already initialized

Console error showing SDK already initialized message — 중복 SDK 초기화 오류

이것이 의미하는 것: OneSignal Web SDK init 코드가 두 번 이상 호출되고 있습니다. 이는 종종 WordPress 플러그인 또는 Shopify 통합 설정과 수동 코드를 결합하거나 실수로 OneSignal init 코드를 여러 번 추가하여 발생합니다. 수정 방법: 중복된 init 호출을 제거하세요. WordPress 플러그인 또는 Shopify 통합을 사용하는 경우 파일에서 수동 OneSignal 코드를 제거하세요.

오류: Can only be used on: (OneSignal 대시보드에 설정된 URL)

Console error showing site origin mismatch between dashboard URL and current page — 예시는 OneSignal 대시보드에 설정된 URL `http://127.0.0.1:5501`이 현재 방문 중인 사이트 출처가 아님을 보여줍니다.

이것이 의미하는 것: 현재 방문 중인 도메인이 OneSignal 대시보드에 구성된 사이트 URL과 일치하지 않습니다. 수정 방법: 브라우저에서 사이트 URL을 복사하여 OneSignal 대시보드 Settings > Push & In-app > Web > Site URL 구성에 붙여넣습니다. 다음 형식을 사용하는 사이트 출처인지 확인하세요:

프로토콜: https://이어야 합니다(로컬 테스트의 경우 Localhost 구성 참조)
도메인: example.com 대 www.example.com
서브도메인: app.example.com 대 example.com

세 가지 구성 요소 모두 실제 사이트 URL과 대시보드 구성 간에 일치해야 합니다.

오류: OneSignalSDK: The “My site is not fully HTTPS” option is no longer supported starting with version 16 (User Model) of the OneSignal SDK.

Console error showing HTTP site not supported in SDK v16 — HTTP 사이트가 지원되지 않는 오류 예시

이것이 의미하는 것: OneSignal 대시보드가 HTTP 사이트를 사용하도록 구성되어 있으며 HTTPS를 사용하도록 업데이트했을 가능성이 있습니다. HTTP를 사용하거나 “내 사이트가 완전히 HTTPS가 아닙니다” 옵션을 사용하는 동안 구독한 사용자는 실제 사이트 출처가 아닌 https://your-label.os.tc 형식의 서브도메인에 구독되어 있습니다. 웹 푸시는 HTTP 사이트 또는 서비스 워커를 호스팅할 수 없는 웹사이트에서 지원되지 않습니다. 수정 방법: 두 옵션 모두 사용자가 사이트가 아닌 os.tc 서브도메인에 구독되어 있기 때문에 다시 구독해야 합니다.

새 OneSignal 앱을 생성하고 init 코드에 새 App ID를 설정합니다. 이렇게 하면 이전 앱에서 계속 푸시를 보내 사용자에게 알릴 수 있습니다. 사이트가 업데이트되었으며 다시 구독해야 한다고 알리는 알림을 보내세요. 할인이나 인센티브를 제공하면 도움이 됩니다. “Launch URL”을 재구독 프롬프트(벨, 사용자 지정 링크 또는 카테고리 슬라이드)가 있는 랜딩 페이지로 설정하세요. 자세한 내용은 권한 프롬프트를 참조하세요.
동일한 App ID를 유지하려면 앱 업데이트 API를 사용하여 chrome_web_origin 및 safari_site_origin을 HTTPS 출처로 업데이트하세요. 사용자가 os.tc 서브도메인에 구독되어 있기 때문에 브라우저에는 실제 도메인에 대한 푸시 권한이 없습니다. 다시 프롬프트가 표시되고, 다시 구독하면 동일한 브라우저에 두 개의 웹 푸시 구독이 생겨 중복 알림이 발생합니다. 중복을 방지하려면 업데이트하기 전에 현재 모든 웹 푸시 구독자를 삭제하세요. 삭제하기 전에 사용자에게 다시 구독해야 한다고 알리는 알림을 몇 개 먼저 보내세요. 프롬프트 옵션은 권한 프롬프트를 참조하세요.

서비스 워커 설치 오류

네이티브 권한 프롬프트가 표시되고 “허용”을 클릭하면 다음과 같은 서비스 워커 설치 오류가 발생할 수 있습니다:

Y: Registration of a Service Worker failed.

[Service Worker Installation] Installing service worker failed TypeError: Failed to register a ServiceWorker for scope (‘https://your-site.com/’) with script (‘https://your-site.com/...’): A bad HTTP response code (404) was received when fetching the script.

[Service Worker Installation] Installing service worker failed TypeError: Failed to register a ServiceWorker for scope (‘https://www.yoursite.com/’) with script (‘https://www.yoursite.com/...’): A bad HTTP response code (403) was received when fetching the script.

Console error showing service worker registration failure with 404 or 403 response — 서비스 워커 설치 오류 예시

The script has an unsupported MIME type (‘current MIME type’). [Service Worker Installation] Installing service worker failed SecurityError: Failed to register a ServiceWorker for scope (‘https://your-site.com/’) with script (‘https://your-site.com/…’): The script has an unsupported MIME type (‘current MIME type’).

Console error showing unsupported MIME type for service worker script — 서비스 워커의 MIME 유형 오류

[Service Worker Installation] Installing service worker failed SecurityError: Failed to register a ServiceWorker for scope (‘https://your-site.com/’) with script (‘https://your-site.com/…’): The script resource is behind a redirect, which is disallowed.

Console error showing service worker script blocked by a redirect — 콘솔의 리디렉션 오류

이것이 의미하는 것: 서비스 워커 파일이 잘못 구성되었습니다. 수정 방법:

서비스 워커 경로 찾기

일반 사이트 및 사용자 지정 코드: SDK는 사용자 지정 경로를 설정하지 않는 한 사이트 루트에서 OneSignalSDKWorker.js를 찾습니다. OneSignal 서비스 워커를 참조하세요.WordPress: 사이트 루트에 워커를 업로드하거나 사용자 지정 경로를 설정하지 마세요. 플러그인이 sdk_files에 파일을 호스팅합니다. 다음 단계에서 해당 URL을 여세요. WordPress 설정을 참조하세요.

브라우저에서 서비스 워커 파일에 직접 방문

브라우저에서 파일 URL을 엽니다.

일반 사이트 기본값(루트): https://yoursite.com/OneSignalSDKWorker.js
WordPress 플러그인(v3): https://yoursite.com/wp-content/plugins/onesignal-free-web-push-notifications/sdk_files/OneSignalSDKWorker.js(WordPress.org 폴더 이름이며 zip 설치는 다를 수 있음)
사용자 지정 경로(일반 사이트 대시보드 또는 사용자 지정 코드 init 전용): https://yoursite.com/your-custom-location/OneSignalSDKWorker.js

파일 이름은 대소문자를 구분합니다. OneSignalSDKWorker.js 또는 구성한 파일 이름을 사용하는지 확인하세요.일부 서버는 파일 이름을 자동으로 소문자로 변환합니다. 파일을 찾을 수 없는 경우 이를 고려하세요.

파일이 로드되는지 확인

다음 JavaScript 코드가 표시되어야 합니다:

JavaScript

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

이 파일은 content-type이 application/javascript로 제공되어야 합니다.
이 파일에 대한 리디렉션이 없어야 합니다. 파일은 사이트와 동일한 도메인에 호스팅되어야 합니다(CDN 또는 프록시 도메인 없음).

일반 사이트 및 사용자 지정 코드: 업로드 및 경로 설정은 OneSignal 서비스 워커를 참조하세요. WordPress 플러그인 사용자는 해당 가이드를 따르지 않아야 합니다. WordPress 설정을 참조하세요.

알림이 표시되지 않음

이 섹션에서는 다음을 가정합니다:

기기에서 알림이 표시되지 않는 일반적인 이유에 대한 알림이 표시되지 않음: Web Push 가이드를 검토했습니다.
네이티브 권한 프롬프트가 표시되고 “허용”을 클릭했습니다. 네이티브 권한 프롬프트를 통해 구독하지 않은 경우 위의 프롬프트 표시 문제를 참조하세요.

위의 사항이 사실인 경우 다음 단계에 따라 구독 ID를 확인하고 자신에게 푸시 알림을 전송하세요:

구독 ID 가져오기

브라우저 개발자 도구 콘솔에서 다음 코드를 실행합니다:

JavaScript

function getUserInfo() {
  console.log('getUserInfo()');
  Promise.all([
    OneSignal.Notifications.isPushSupported(),
    OneSignal.Notifications.permission,
    OneSignal.User.PushSubscription.optedIn,
    OneSignal.User.PushSubscription.id
  ]).then(([
    isPushSupported,
    isSubscribed,
    isOptedIn,
    subscriptionId
  ]) => {
    console.log('The current URL of this page: ', location.href);
    console.log('Push is supported on this browser: ', isPushSupported);
    console.log('You are subscribed to notifications in the browser: ', isSubscribed);
    console.log('You are opted-in with OneSignal: ' , isOptedIn);
    console.log('Your OneSignal Subscription ID: ', subscriptionId);
  }).catch(e => {
    console.error('Error getting user info:', e);
  });
}
getUserInfo();

다음 정보를 알려줍니다:

혼동이 있는 경우 현재 페이지의 URL.
현재 브라우저가 푸시 알림을 지원하는지 여부.
- true는 브라우저가 푸시 알림을 지원함을 의미합니다.
- false는 브라우저가 푸시 알림을 지원하지 않음을 의미합니다.
브라우저에서 알림을 구독했는지 여부.
- true는 이 URL에 대한 푸시 권한을 허용했음을 의미합니다.
- false는 이 URL에 대한 푸시 권한을 허용하지 않았거나 거부했음을 의미합니다.
OneSignal로 옵트인했는지 여부.
- true는 구독이 OneSignal의 푸시 알림에 구독되어 있음을 의미합니다.
- false는 구독이 OneSignal의 푸시 알림에 구독되어 있지 않음을 의미합니다. 사이트에서 optOut() 메서드가 호출되고 있는지 확인하세요.
OneSignal 구독 ID.
- 다음 단계를 위해 저장하세요. 이것은 자신에게 푸시 알림을 전송하는 데 사용할 ID입니다.
콘솔의 사용자 정보 출력 예시

추가 지원이 필요한 경우 이 콘솔 데이터를 텍스트 파일로 저장하여 OneSignal 지원팀과 공유하세요.

자신에게 알림 전송

알림을 구독하고 OneSignal로 옵트인했으며 구독 ID가 있는 경우 자신에게 알림을 전송할 수 있습니다.테스트 사용자의 단계에 따라 자신을 테스터로 설정하고 자신에게 알림을 전송하세요.

Chrome으로 테스트

Chrome에서 알림을 받지 못하는 경우 이러한 Chrome 전용 진단 도구를 사용하여 문제를 식별하세요.

새 탭에서 chrome://gcm-internals를 엽니다.
왼쪽 상단의 “Start Recording” 버튼을 클릭합니다. “Connection State: CONNECTED”가 표시되는지 확인하세요.
이것을 열어 둔 채로 Chrome 웹 푸시 구독에 다른 푸시 알림을 전송하세요.
받은 경우 “Receive Message Log”에 무언가가 표시되어야 합니다.

Chrome GCM internals page showing Receive Message Log with a received data message — GCM 내부 로깅

“Data msg received”가 표시되지 않으면 Chrome 브라우저가 알림을 전혀 받지 못하고 있는 것입니다. GCM 내부 로그와 함께 OneSignal 지원팀에 문의하세요.
“Data msg received”가 표시되지만 여전히 알림을 받지 못한 경우 다음 단계로 계속 진행하세요.

새 탭에서 chrome://serviceworker-internals를 엽니다.
Scope: https://your-site.com을 검색합니다(your-site.com을 실제 사이트 도메인으로 교체).
Inspect 또는 Start -> Inspect를 클릭합니다. Chrome 개발자 도구 팝업이 나타납니다.

Chrome service worker internals page showing the Inspect button for a registered service worker — 서비스 워커 검사

서비스 워커에 대한 Chrome 개발자 도구 팝업에서 Console 탭을 클릭하고 OneSignalWorker.log.trace();를 실행합니다. undefined를 반환해야 합니다. 서비스 워커의 모든 메시지가 이제 이 팝업에 표시됩니다.

도움이 필요하신가요?지원 팀과 채팅하거나 support@onesignal.com으로 이메일을 보내주세요.다음을 포함해 주세요:

발생한 문제의 세부 정보 및 재현 단계(가능한 경우)
OneSignal 앱 ID
External ID 또는 Subscription ID(해당하는 경우)
OneSignal 대시보드에서 테스트한 메시지의 URL(해당하는 경우)
관련 로그 또는 오류 메시지

기꺼이 도와드리겠습니다!

자주 묻는 질문

”SDK already initialized”가 표시되는 이유는 무엇인가요?

페이지에서 OneSignal Web SDK init 코드가 두 번 이상 호출되고 있습니다. 이는 일반적으로 WordPress 플러그인과 수동 코드를 결합하거나 init 태그가 여러 페이지 템플릿에 포함된 경우 발생합니다. 중복된 init 호출을 제거하여 해결하세요.

HTTP 사이트에서 웹 푸시를 사용할 수 있나요?

아니요. 푸시 전달을 처리하는 서비스 워커는 보안 출처에서만 작동하므로 웹 푸시에는 HTTPS가 필요합니다. 이전에 “내 사이트가 완전히 HTTPS가 아닙니다” 옵션을 사용한 경우 HTTPS로 마이그레이션해야 합니다. 마이그레이션 단계는 구성 오류를 참조하세요.

localhost에서 웹 푸시를 테스트하려면 어떻게 하나요?

개발 중에 localhost에서 테스트할 수 있습니다. 설정 지침은 Localhost 구성을 참조하세요. localhost 테스트는 Chromium 기반 브라우저에서만 작동합니다.

Web SDK 설정

OneSignal Web SDK 초기 설치 및 구성을 완료하세요.

서비스 워커 설정

사이트에 맞게 OneSignal 서비스 워커 파일을 구성하세요.

권한 프롬프트

방문자에게 웹 푸시 권한을 요청하는 방법과 시기를 구성하세요.

알림이 표시되지 않음

웹 푸시 알림이 기기에 나타나지 않는 일반적인 이유입니다.

개발자 문서

모바일 SDKs

웹 SDKs

실시간 현황

데스크탑 & 워치 설정

Web SDK 문제 해결

개요

브라우저 호환성

기기 알림 설정

프롬프트 표시 문제

문제 해결 단계

구성 오류

서비스 워커 설치 오류

알림이 표시되지 않음

자주 묻는 질문

”SDK already initialized”가 표시되는 이유는 무엇인가요?

HTTP 사이트에서 웹 푸시를 사용할 수 있나요?

localhost에서 웹 푸시를 테스트하려면 어떻게 하나요?

관련 페이지

Web SDK 설정

서비스 워커 설정

권한 프롬프트

알림이 표시되지 않음

​개요

​브라우저 호환성

​기기 알림 설정

​프롬프트 표시 문제

​문제 해결 단계

​구성 오류

​서비스 워커 설치 오류

​알림이 표시되지 않음

​자주 묻는 질문

​”SDK already initialized”가 표시되는 이유는 무엇인가요?

​HTTP 사이트에서 웹 푸시를 사용할 수 있나요?

​localhost에서 웹 푸시를 테스트하려면 어떻게 하나요?

​관련 페이지

Web SDK 설정

서비스 워커 설정

권한 프롬프트

알림이 표시되지 않음

개요

브라우저 호환성

기기 알림 설정

프롬프트 표시 문제

문제 해결 단계

구성 오류

서비스 워커 설치 오류

알림이 표시되지 않음

자주 묻는 질문

”SDK already initialized”가 표시되는 이유는 무엇인가요?

HTTP 사이트에서 웹 푸시를 사용할 수 있나요?

localhost에서 웹 푸시를 테스트하려면 어떻게 하나요?

관련 페이지