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

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이