전제 조건
- HTTPS를 지원하는 사이트.
- 사이트의 컨테이너에 대해 GTM에서 변경 사항을 게시할 수 있어야 합니다.
- OneSignal Web SDK 설정 플로우를 사이트에 코드 추가 단계까지 완료했어야 합니다. 이를 통해 다음을 얻게 됩니다:
- OneSignal Web Push 앱 및 App ID.
- OneSignal Service Worker 설정.
설정
1. OneSignal 웹 앱 설정
Web SDK 설정을 사이트에 코드 추가 단계까지 따라가세요. 여기에서 OneSignal App ID를 얻게 됩니다.
이 단계에 도달하면 Google Tag Manager와 작동하도록 코드를 약간 조정해야 합니다.
2. GTM 변수 생성
태그 전체에서 참조하는 값에 대한 GTM 변수를 생성합니다. 이를 통해 하드코딩을 피하고 설정을 더 쉽게 유지 관리할 수 있습니다.ONESIGNAL_APP_ID 변수 생성
- GTM에서 Variables > New로 이동합니다.
- Constant를 선택합니다.
- 이름을
ONESIGNAL_APP_ID로 지정합니다 - 값을 OneSignal App ID로 설정합니다.
- 저장

OneSignal App ID 변수 생성
이제 GTM의 어디에서나
{{ ONESIGNAL_APP_ID }}를 사용하여 App ID를 참조할 수 있습니다.ONESIGNAL_EXTERNAL_ID 변수 생성(권장)
사용자를 외부 식별자와 연결하는 경우(예: 데이터베이스 또는 인증 시스템의 사용자 ID) 이 변수를 사용하세요.
사이트에서 값을 사용할 수 있는 방식에 따라 변수 유형을 선택하세요. 일반적인 옵션:
- Data Layer Variable(권장)
- First-Party Cookie
- DOM Variable(고급)
3. OneSignal init 태그 생성
- GTM에서 Tags > New로 이동합니다
- 태그 이름 지정:
OneSignal - Init - Tag Type: Custom HTML
- 아래 코드를 붙여넣습니다.
- Advanced Settings > Tag firing options 아래에서 Once per page로 설정합니다.
- Triggering 아래에서 Initialization - All Pages를 선택합니다.
HTML

OneSignal - Init 태그 구성
4. External ID 및 태그 설정
External ID 설정은 선택 사항이지만 권장됩니다. 이를 통해 여러 기기에서 사용자를 식별하고 백엔드와 동기화할 수 있습니다.ONESIGNAL_EXTERNAL_ID를 dataLayer에 푸시하기
이 예제는 GTM이 ONESIGNAL_EXTERNAL_ID 변수(2단계에서 생성)를 통해 읽을 수 있도록 사용자 ID를 dataLayer에 푸시하는 방법을 보여줍니다.
HTML
- 태그 이름:
OneSignal – Set External ID - 태그 유형: Custom HTML
- Tag firing options: Once per page
- Trigger:
OneSignalInitialized에 대한 사용자 정의 이벤트 트리거 생성(위의 OneSignal - Init 태그에서 설정) 그리고- 선택적으로 페이지 로드 시 사용자 ID를 사용할 수 있음을 알고 있는 경우.
태그 설정
Web SDK를 사용하여 OneSignal 태그를 전송합니다. 태그 구성:- 이름:
OneSignal - Add Tags - Tag Type: Custom HTML
- Tag firing options: Once per page
- Trigger:
OneSignalInitialized, 그리고- 태그 데이터를 사용할 수 있는 조건(예: 로그인 후, 프로필 페이지, 구매 후).
HTML
사용자 데이터를 사용할 수 있는 경우에만 태그를 보내세요(예: 로그인 후, 프로필 로드 후 또는 알려진 전환 이벤트 후).
Consent Mode 및 개인정보 보호 고려사항
사이트에서 Consent Mode / CMP를 사용하는 경우 OneSignal을 언제 로드할지 결정하세요:- 동의 후에만(EU/UK에서 일반적), 또는
- 즉시(기본적으로 “기능적” 스토리지가 허용되는 곳에서 일반적).
테스트
- GTM에서 Preview 모드를 엽니다.
- 사이트를 로드하고 확인합니다:
OneSignal - Init가 한 번 실행됩니다.OneSignalInitialized가 GTM 이벤트 타임라인에 나타납니다(이벤트 푸시를 유지한 경우).
- 웹사이트를 구독합니다. 프롬프트 세부사항은 웹 권한 프롬프트를 참조하세요.
- OneSignal 대시보드에서 Audience > Subscriptions로 이동하여 확인합니다:
- 옵트인 후 Subscription이 나타나는지.
- External ID를 설정한 경우 External ID가 표시되는지.
- Messages > New Push에서 테스트 푸시를 보냅니다.
초기화가 작동하는 경우 옵트인 후 OneSignal에 Subscription이 나타납니다.
문제 해결
-
Init 태그가 실행되지만 SDK가 로드되지 않음
- Content Security Policy(CSP)가
https://cdn.onesignal.com을 차단하는지 확인하세요. - 광고 차단기/스크립트 차단기를 확인하세요.
- Content Security Policy(CSP)가
-
dataLayer오류- 모든
dataLayer.push()호출 전에window.dataLayer = window.dataLayer || []가 설정되어 있는지 확인하세요.
- 모든
-
중복 프롬프트 / 중복 SDK 로드
- 사이트 코드, CMS 플러그인 또는 다른 GTM 태그를 통해 OneSignal을 로드하지 않는지 확인하세요.
-
Add Tags가 실행되지만 OneSignal에 나타나지 않음
- Trigger Group이
OneSignalInitialized를 기다리는지 확인하세요. - 사용자 작업 트리거가 실제로 실행되는지 확인하세요.
- 태그가 유효한 키/값 쌍이고 플랜 제한 내에 있는지 확인하세요.
- Trigger Group이