메인 콘텐츠로 건너뛰기

개요

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

브라우저 호환성

사용자는 웹 권한 프롬프트를 볼 수 있지만 시크릿, 프라이빗 또는 게스트 브라우저 모드에서는 푸시 알림을 구독할 수 없습니다.
BrowserWindowsmacOSAndroidiOS
Chrome✅ ¹
Firefox✅ ¹
Safari 10+✅ ¹
Microsoft Edge✅ ¹
Opera ²✅ ¹
Samsung Internet ²✅ ¹
Yandex ²✅ ¹
UC Browser ²✅ ¹
Internet Explorer
DuckDuckGo
¹ iOS는 웹 앱 설치가 필요합니다(iOS 웹 푸시 설정 참조)² Chromium 기반 브라우저는 OneSignal 분석에서 “Chrome”으로 표시됩니다

기기 알림 설정

기기의 알림 설정 및 집중 모드(방해 금지, 배터리 부족 등)가 알림 표시를 차단할 수 있습니다. 또한 브라우저와 같은 특정 앱에 대한 알림이 꺼져 있을 수도 있습니다. 기기가 알림을 수신하도록 구성되어 있는지 확인하려면 다음을 확인하세요.
  • Windows
  • macOS
  • Android
  • iOS
  1. 시작 > 설정 > 알림 및 작업 > 앱 및 기타 보낸 사람의 알림 받기를 선택합니다
  2. 사이트와 브라우저도 활성화되어 있는지 확인하세요.

Windows 10 알림 설정

Windows 11 알림 설정:
  1. 시작 > 설정 > 시스템 > 알림을 선택합니다

Windows 11 알림 설정

  1. 알림을 켭니다
  2. 방해 금지를 끕니다 (테스트 중에는 이 옵션을 비활성화하면 푸시가 표시됩니다)
  3. 앱 및 기타 보낸 사람의 알림 아래로 스크롤합니다
  1. 브라우저가 켜져 있는지 확인하세요.

Windows 11 알림 설정 브라우저 목록

프롬프트 표시 문제

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

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

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

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

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

브라우저의 알림 설정 확인

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

Chrome 알림 설정

이 예시에서:
  • 사용자가 “사이트에서 알림을 보낼 수 없음”을 선택하여 네이티브 권한 프롬프트가 표시되지 않습니다. 네이티브 권한 프롬프트를 표시하려면 “사이트에서 알림 전송을 요청할 수 있음”으로 표시되어야 합니다.
  • 사용자가 https://yoursite.com을 “알림 전송이 허용되지 않음” 목록에 추가하여 네이티브 권한 프롬프트가 표시되지 않습니다. 네이티브 권한 프롬프트를 표시하려면 이 목록에서 제거해야 합니다.
브라우저별 문서:
  • Chrome - 이 페이지에서는 설정 > 개인정보 및 보안 > 사이트 설정 > 알림으로 이동하여 Chrome에서 알림을 관리하는 방법을 설명하며, 여기서 기본 동작을 제어하고 개별 웹사이트에 대한 권한을 관리할 수 있습니다.
  • Firefox - 이 가이드는 Firefox의 웹 푸시 알림을 다루며, 설정 > 개인정보 및 보안 > 알림을 통해 알림 권한을 관리하는 방법과 주소 표시줄의 사이트 정보 아이콘을 통해 특정 사이트에 대한 권한을 제어하는 방법을 설명합니다.
  • Safari - 이 Apple 가이드는 Safari > 환경설정 > 웹사이트 > 알림을 통해 Mac에서 Safari 알림을 사용자 지정하는 방법을 설명하며, 여기서 어떤 사이트가 알림을 보낼 수 있는지 관리하고 시스템 환경설정을 통해 알림 동작을 제어할 수 있습니다.
  • Edge - 이 문서에서는 설정 > 개인정보, 검색 및 서비스 > 사이트 권한 > 알림으로 이동하거나 주소 표시줄의 사이트 정보 아이콘을 클릭하여 Edge 알림을 관리하는 방법을 자세히 설명합니다.
4

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

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

문제 해결 단계

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

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

브라우저의 개발자 도구를 사용하여 웹페이지에서 Web SDK와 상호 작용하고 로깅을 활성화하여 오류를 확인할 수 있습니다.
  • Desktop
  • Android
  • iOS
  • Chrome: 페이지를 마우스 오른쪽 버튼으로 클릭하고 검사를 클릭한 다음 팝업 창의 콘솔 탭을 클릭합니다.
  • Firefox: 페이지를 마우스 오른쪽 버튼으로 클릭하고 요소 검사를 클릭한 다음 팝업 창의 콘솔 탭을 클릭합니다.
  • Safari: Safari → 환경설정 → 고급으로 이동하여 메뉴 막대에서 개발자용 메뉴 보기가 체크되어 있는지 확인합니다. 그런 다음 웹페이지에서 마우스 오른쪽 버튼을 클릭하고 요소 검사를 클릭한 다음 팝업 창의 콘솔 탭을 클릭합니다.

데스크톱 개발자 도구 콘솔

2

페이지에서 OneSignal이 로드되고 초기화되었는지 확인

콘솔에서 다음을 실행합니다:
JavaScript
  OneSignal.initialized
결과의 의미:
  • true ✅ - OneSignal이 초기화되어 준비되었습니다. 다음 단계로 계속 진행하세요.
  • false ⚠️ - OneSignal이 로드되었지만 아직 초기화를 완료하지 않았습니다. 잠시 기다렸다가 다시 시도하세요.
  • Uncaught ReferenceError: OneSignal is not defined ❌ OneSignal JavaScript 스니펫이 사이트의 <head> 섹션에 있는지 확인하고, OneSignal 메서드를 사용하기 전에 스크립트가 로드되는지 확인하세요. Web SDK 설정 가이드를 검토하세요.
  • OneSignal is already defined SDK가 동일한 페이지에서 두 번 이상 초기화되고 있습니다. 하나의 초기화 메서드를 제거하세요. WordPress 플러그인을 사용하는 경우 테마 파일에서 수동 OneSignal 코드를 제거하세요.
3

Web SDK 로깅 활성화

이제 개발자 도구 콘솔에서 명령을 실행할 수 있습니다. 다음 코드를 실행합니다:
JavaScript
  OneSignal.Debug.setLogLevel('trace');
  • 결과로 undefined가 표시되어야 합니다.
  • 탭을 닫고 동일한 페이지에 대해 새 탭을 엽니다. 새로고침만으로는 모든 SDK 초기화 이벤트가 트리거되지 않습니다.
  • 콘솔에서 OneSignal SDK 로그가 표시되기 시작합니다.

자세한 SDK 로그가 있는 콘솔

구성 오류

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

중복 SDK 초기화 오류

이것이 의미하는 것: OneSignal Web SDK init 코드가 두 번 이상 호출되고 있습니다. 이는 종종 WordPress 플러그인 설정과 수동 코드를 결합하거나 실수로 OneSignal init 코드를 여러 번 추가하여 발생합니다. 수정 방법: 중복된 init 호출을 제거하세요. WordPress 플러그인을 사용하는 경우 테마 파일에서 수동 OneSignal 코드를 제거하세요.
오류: Can only be used on: (OneSignal 대시보드에 설정된 URL)

예시는 OneSignal 대시보드에 설정된 URL `http://127.0.0.1:5501`이 현재 방문 중인 사이트 출처가 아님을 보여줍니다.

이것이 의미하는 것: 현재 방문 중인 도메인이 OneSignal 대시보드에 구성된 사이트 URL과 일치하지 않습니다. 수정 방법: 브라우저에서 사이트 URL을 복사하여 OneSignal 대시보드 설정 > Push 및 인앱 > Web > 사이트 URL 구성에 붙여넣습니다. 다음 형식을 사용하여 사이트 출처인지 확인하세요:
  • 프로토콜: https://이어야 합니다 (로컬 테스트의 경우 Localhost 구성 참조)
  • 도메인: example.com vs www.example.com
  • 서브도메인: app.example.com vs example.com
세 가지 구성 요소 모두 실제 사이트 URL과 대시보드 구성 간에 일치해야 합니다.

서비스 워커 설치 오류

네이티브 권한 프롬프트가 표시되고 “허용”을 클릭하면 다음과 같은 서비스 워커 설치 오류가 발생할 수 있습니다:
Y: 서비스 워커 등록에 실패했습니다.
[서비스 워커 설치] 서비스 워커 설치 실패 TypeError: 범위(‘https://your-site.com/’)에 대해 스크립트(‘https://your-site.com/...’)로 ServiceWorker를 등록하지 못했습니다: 스크립트를 가져올 때 잘못된 HTTP 응답 코드(404)를 받았습니다.
[서비스 워커 설치] 서비스 워커 설치 실패 TypeError: 범위(‘https://www.yoursite.com/’)에 대해 스크립트(‘https://www.yoursite.com/...’)로 ServiceWorker를 등록하지 못했습니다: 스크립트를 가져올 때 잘못된 HTTP 응답 코드(403)를 받았습니다.

서비스 워커 설치 오류 예시

스크립트에 지원되지 않는 MIME 유형(‘현재 MIME 유형’)이 있습니다. [서비스 워커 설치] 서비스 워커 설치 실패 SecurityError: 범위(‘https://your-site.com/‘)에 대해 스크립트(‘https://your-site.com/…’)로 ServiceWorker를 등록하지 못했습니다: 스크립트에 지원되지 않는 MIME 유형(‘현재 MIME 유형’)이 있습니다.

서비스 워커의 MIME 유형 오류

[서비스 워커 설치] 서비스 워커 설치 실패 SecurityError: 범위(‘https://your-site.com/‘)에 대해 스크립트(‘https://your-site.com/…’)로 ServiceWorker를 등록하지 못했습니다: 스크립트 리소스가 리디렉션 뒤에 있으며 이는 허용되지 않습니다.

콘솔의 리디렉션 오류

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

서비스 워커 경로 찾기

SDK는 서비스 워커 설정 가이드에 설명된 대로 사용자 지정 파일 이름이나 위치를 지정하지 않는 한 사이트의 루트 디렉터리에서 OneSignalSDKWorker.js 서비스 워커 파일을 찾습니다.SDK가 서비스 워커 파일을 찾을 수 있도록 올바른 파일 이름, 위치 및 범위를 구성했는지 확인하세요.
2

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

구성에 따라 브라우저에서 파일을 직접 엽니다.
  • 사용자 지정 위치를 구성하지 않은 경우 사이트의 루트에서 서비스 워커 파일의 JavaScript 코드를 볼 수 있어야 합니다: https://yoursite.com/OneSignalSDKWorker.js
  • WordPress를 사용하는 경우 여기에서 볼 수 있어야 합니다: https://yoursite.com/wp-content/plugins/onesignal-free-web-push-notifications/sdk_files/OneSignalSDKWorker.js
  • 사용자 지정 위치를 사용하는 경우 여기에서 볼 수 있어야 합니다: https://yoursite.com/your-custom-location/OneSignalSDKWorker.js
파일 이름은 대소문자를 구분합니다. OneSignalSDKWorker.js 또는 구성한 파일 이름을 사용하는지 확인하세요.일부 서버는 파일 이름을 자동으로 소문자로 변환합니다. 파일을 찾을 수 없는 경우 이를 고려하세요.
3

파일이 로드되는지 확인

  • 다음 JavaScript 코드가 표시되어야 합니다:
    JavaScript
    importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
    
  • 이 파일은 content-typeapplication/javascript로 제공되어야 합니다.
  • 이 파일에 대한 리디렉션이 없어야 합니다. 파일은 사이트와 동일한 도메인에 호스팅되어야 합니다(CDN 또는 프록시 도메인 없음)
보다 자세한 설정 지침은 서비스 워커 설정 가이드를 검토하세요.

알림이 표시되지 않음

이 섹션에서는 다음을 가정합니다:
  1. 기기에서 알림이 표시되지 않는 일반적인 이유에 대한 알림이 표시되지 않음: Web Push 가이드를 검토했습니다.
  2. 네이티브 권한 프롬프트가 표시되고 “허용”을 클릭했습니다. 네이티브 권한 프롬프트를 통해 구독하지 않은 경우 위의 프롬프트 표시 문제를 참조하세요.
위의 사항이 사실인 경우 다음 단계에 따라 구독 ID를 확인하고 푸시 알림을 전송하세요:
1

구독 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입니다.

    사용자 정보 예시

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

알림 전송

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

Chrome으로 테스트

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

GCM 내부 로깅

  • “Data msg received”가 표시되지 않으면 Chrome 브라우저가 전혀 알림을 받지 못하고 있는 것입니다. 이에 대해 지원팀에 알려주세요.
  • “Data msg received”가 표시되지만 여전히 알림을 받지 못한 경우 다음 단계로 계속 진행하세요.
  1. 새 탭에서 chrome://serviceworker-internals를 엽니다.
  2. Scope: https://your-site.com을 검색합니다 (your-site.com을 실제 사이트 도메인으로 교체).
  3. Inspect 또는 Start -> Inspect를 클릭합니다. Chrome 개발자 도구 팝업이 나타납니다.

서비스 워커 검사

  1. 서비스 워커의 Chrome 개발자 도구 팝업에서 Console 탭을 클릭하고 OneSignalWorker.log.trace();를 실행합니다. undefined를 반환해야 합니다. 서비스 워커의 모든 메시지가 이제 이 팝업에 표시됩니다.
도움이 필요하신가요?지원 팀과 채팅하거나 support@onesignal.com으로 이메일을 보내주세요.다음을 포함해 주세요:
  • 발생한 문제의 세부 정보 및 재현 단계(가능한 경우)
  • OneSignal 앱 ID
  • External ID 또는 Subscription ID(해당하는 경우)
  • OneSignal 대시보드에서 테스트한 메시지의 URL(해당하는 경우)
  • 관련 로그 또는 오류 메시지
기꺼이 도와드리겠습니다!