메인 콘텐츠로 건너뛰기
이 가이드는 Google Tag Manager(GTM)를 사용하여 OneSignal Web SDK를 로드하고 초기화한 다음, 선택적으로 초기화 후 External ID 및 OneSignal 태그를 설정하는 방법을 보여줍니다.

전제 조건

  • HTTPS를 지원하는 사이트.
  • 사이트의 컨테이너에 대해 GTM에서 변경 사항을 게시할 수 있어야 합니다.
  • OneSignal Web SDK 설정 플로우를 사이트에 코드 추가 단계까지 완료했어야 합니다. 이를 통해 다음을 얻게 됩니다:

설정

1. OneSignal 웹 앱 설정

Web SDK 설정사이트에 코드 추가 단계까지 따라가세요. 여기에서 OneSignal App ID를 얻게 됩니다.
OneSignal Web SDK 설정 대시보드의 사이트에 코드 추가 단계
OneSignal Service Worker 파일을 서버에 직접 업로드해야 합니다. OneSignal Service Worker를 참조하세요.

2. GTM 변수 생성

태그 전체에서 참조하는 값에 대한 GTM 변수를 생성합니다. 이를 통해 하드코딩을 피하고 설정을 더 쉽게 유지 관리할 수 있습니다. ONESIGNAL_APP_ID 변수 생성
  1. GTM에서 Variables > New로 이동합니다.
  2. Constant를 선택합니다.
  3. 이름을 ONESIGNAL_APP_ID로 지정합니다
  4. 값을 OneSignal App ID로 설정합니다.
  5. 저장
Google Tag Manager에서 OneSignal App ID 변수 생성
이제 GTM의 어디에서나 {{ ONESIGNAL_APP_ID }}를 사용하여 App ID를 참조할 수 있습니다.
ONESIGNAL_EXTERNAL_ID 변수 생성(권장) 사용자를 외부 식별자와 연결하는 경우(예: 데이터베이스 또는 인증 시스템의 사용자 ID) 이 변수를 사용하세요. 사이트에서 값을 사용할 수 있는 방식에 따라 변수 유형을 선택하세요. 일반적인 옵션:
  • Data Layer Variable(권장)
  • First-Party Cookie
  • DOM Variable(고급)

3. OneSignal init 태그 생성

  1. GTM에서 Tags > New로 이동합니다
  2. 태그 이름 지정: OneSignal - Init
  3. Tag Type: Custom HTML
  4. 아래 코드를 붙여넣습니다.
  5. Advanced Settings > Tag firing options 아래에서 Once per page로 설정합니다.
  6. Triggering 아래에서 Initialization - All Pages를 선택합니다.
HTML
<!--
  OneSignal – Google Tag Manager를 사용한 Web SDK 초기화

  이 스니펫:
  - OneSignal Web SDK를 로드합니다
  - App ID로 OneSignal을 초기화합니다
  - 구독 벨(notifyButton)을 활성화합니다

  대부분의 사이트에서 바로 작동합니다.
-->

<!-- 1. OneSignal Web SDK (v16) 로드 -->
<!-- 이 스크립트는 OneSignal을 사용하려는 모든 페이지에서 로드되어야 합니다 -->
<script
  src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js"
  defer>
</script>

<script>
  // GTM dataLayer가 존재하는지 확인
  // 여기서는 선택적으로 "OneSignalInitialized" 이벤트를 푸시하는 데만 사용
  window.dataLayer = window.dataLayer || [];

  // OneSignalDeferred는 SDK가 완전히 로드된 후 실행되는 큐입니다
  window.OneSignalDeferred = window.OneSignalDeferred || [];

  // 2. SDK가 준비되면 OneSignal 초기화
  window.OneSignalDeferred.push(function (OneSignal) {

    OneSignal.init({
      /*
        필수
        OneSignal App ID를 GTM 변수로 설정하는 것이 권장됩니다.
        OneSignal 대시보드에서 찾을 수 있습니다:
        Settings > Keys & IDs
      */
      appId: "{{ONESIGNAL_APP_ID}}",

      /*
        선택 사항 – SERVICE WORKER가 루트에 없는 경우에만 필요

        service worker가 다음 위치에 호스팅된 경우:
          /OneSignalSDKWorker.js

        …serviceWorkerPath 또는 serviceWorkerParam을 설정하지 마세요.

        service worker가 하위 디렉토리에 호스팅된 경우에만
        아래 옵션의 주석을 해제하고 업데이트하세요
        (예: /push/onesignal/).
      */

      //serviceWorkerPath: "push/onesignal/OneSignalSDKWorker.js",
      //serviceWorkerParam: { scope: "/push/onesignal/" },

      /*
        선택 사항
        OneSignal 구독 벨(notifyButton)을 활성화합니다.
        사용자가 알림을 구독하거나 구독 해제할 수 있습니다.
        더 많은 프롬프트 옵션은 다음을 참조하세요: https://documentation.onesignal.com/docs/en/permission-requests
      */
      notifyButton: {
        enable: true
      }
    })
    .then(function () {
      // OneSignal 초기화 성공
      console.log("[OneSignal] init success");

      // 권장: 다른 태그를 트리거하기 위해 GTM에 이벤트 푸시
      window.dataLayer.push({
        event: "OneSignalInitialized"
      });
    })
    .catch(function (e) {
      // 초기화 실패(잘못된 App ID, service worker 누락 등)
      console.log("[OneSignal] init failed", e);
    });
  });
</script>
Google Tag Manager에서 OneSignal - Init 태그 구성
동의 배너 / CMP를 사용하는 경우 아래의 Consent Mode 및 개인정보 보호 고려사항 옵션을 참조하세요.

4. External ID 및 태그 설정

External ID 설정은 선택 사항이지만 권장됩니다. 이를 통해 여러 기기에서 사용자를 식별하고 백엔드와 동기화할 수 있습니다. ONESIGNAL_EXTERNAL_ID를 dataLayer에 푸시하기 이 예제는 GTM이 ONESIGNAL_EXTERNAL_ID 변수(2단계에서 생성)를 통해 읽을 수 있도록 사용자 ID를 dataLayer에 푸시하는 방법을 보여줍니다.
HTML
<script>
  window.dataLayer = window.dataLayer || [];

  // 데이터베이스 또는 인증 시스템에서 사용자 ID를 가져옵니다.
  // 이것이 문자열 값인지 확인하세요.
  var userId = "your_user_id_here";

  dataLayer.push({
    ONESIGNAL_EXTERNAL_ID: String(userId),
  });
</script>
External ID를 설정하는 GTM 태그 생성 태그 구성:
  • 태그 이름: OneSignal – Set External ID
  • 태그 유형: Custom HTML
  • Tag firing options: Once per page
  • Trigger:
    • OneSignalInitialized에 대한 사용자 정의 이벤트 트리거 생성(위의 OneSignal - Init 태그에서 설정) 그리고
    • 선택적으로 페이지 로드 시 사용자 ID를 사용할 수 있음을 알고 있는 경우.
External ID를 설정하는 데 필요한 메서드는 OneSignal.login(externalId)이며, 여기서 externalId는 문자열입니다.{{ONESIGNAL_EXTERNAL_ID}}가 비어 있거나(GTM이 “undefined” / “null”로 대체한 경우) login 호출이 건너뛰어지고 External ID가 설정되지 않습니다. 이는 일반적인 GTM 타이밍 문제입니다.
<script>
  // OneSignalDeferred는 OneSignal SDK가 준비된 후에 실행되도록 보장합니다
  window.OneSignalDeferred = window.OneSignalDeferred || [];

  window.OneSignalDeferred.push(function (OneSignal) {
    /*
      Google Tag Manager에서 External ID를 읽습니다.
      이것은 GTM 변수(Data Layer Variable 또는 Custom JS Variable)여야 합니다.
    */
    var externalId = "{{ONESIGNAL_EXTERNAL_ID}}";

    console.log("[OneSignal] raw external ID from GTM:", externalId);

    /*
      기본 유효성 검사:
      - GTM은 undefined/null을 문자열로 대체할 수 있습니다
      - OneSignal.login은 문자열이 필요합니다
    */
    if (!externalId || externalId === "undefined" || externalId === "null") {
      console.log("[OneSignal] External ID missing, skipping login");
      return;
    }

    // External ID가 깨끗한 문자열인지 확인
    externalId = String(externalId).trim();

    console.log("[OneSignal] Calling OneSignal.login with External ID:", externalId);

    /*
      External ID를 사용하여 사용자를 OneSignal에 로그인합니다.
      이렇게 하면 현재 브라우저/기기가 이 사용자에 연결됩니다.
    */
    OneSignal.login(externalId)
      .then(function () {
        console.log("[OneSignal] External ID set successfully:", externalId);
      })
      .catch(function (e) {
        console.log("[OneSignal] Failed to set External ID", e);
      });
  });
</script>

데이터 태그 설정

Web SDK를 사용하여 OneSignal 사용자 태그를 전송합니다. 태그 구성:
  • 이름: OneSignal - Add Tags
  • Tag Type: Custom HTML
  • Tag firing options: Once per page
  • Trigger:
    • OneSignalInitialized, 그리고
    • 태그 데이터를 사용할 수 있는 조건(예: 로그인 후, 프로필 페이지, 구매 후).
이 코드를 붙여넣고 예제 태그 TAG 및 VALUE를 교체합니다.
HTML
<script>
  window.OneSignalDeferred = window.OneSignalDeferred || [];
  window.OneSignalDeferred.push(function (OneSignal) {
    OneSignal.User.addTags({
      TAG_1: "VALUE_1",
      TAG_2: "VALUE_2",
    });
  });
</script>
사용자 데이터를 사용할 수 있는 경우에만 태그를 보내세요(예: 로그인 후, 프로필 로드 후 또는 알려진 전환 이벤트 후).
사이트에서 Consent Mode / CMP를 사용하는 경우 OneSignal을 언제 로드할지 결정하세요:
  • 동의 후에만(EU/UK에서 일반적), 또는
  • 즉시(기본적으로 “기능적” 스토리지가 허용되는 곳에서 일반적).
GTM은 Consent Initialization 트리거와 태그 수준 동의 제어를 지원하여 사용자 동의에 따라 태그 동작을 관리합니다. 그러나 OneSignal은 SDK가 로드되는 시점을 제어하기 위한 개인정보 보호 동의 메서드도 제공합니다.

테스트

  1. GTM에서 Preview 모드를 엽니다.
  2. 사이트를 로드하고 확인합니다:
    • OneSignal - Init가 한 번 실행됩니다.
    • OneSignalInitialized가 GTM 이벤트 타임라인에 나타납니다(이벤트 푸시를 유지한 경우).
  3. 웹사이트를 구독합니다. 프롬프트 세부사항은 웹 권한 프롬프트를 참조하세요.
  4. OneSignal 대시보드에서 Audience > Subscriptions로 이동하여 확인합니다:
    • 옵트인 후 Subscription이 나타나는지.
    • External ID를 설정한 경우 External ID가 표시되는지.
  5. Messages > New Push에서 테스트 푸시를 보냅니다.
초기화가 작동하는 경우 옵트인 후 OneSignal에 Subscription이 나타납니다.

문제 해결

  • Init 태그가 실행되지만 SDK가 로드되지 않음
    • Content Security Policy(CSP)가 https://cdn.onesignal.com을 차단하는지 확인하세요.
    • 광고 차단기/스크립트 차단기를 확인하세요.
  • dataLayer 오류
    • 모든 dataLayer.push() 호출 전에 window.dataLayer = window.dataLayer || []가 설정되어 있는지 확인하세요.
  • 중복 프롬프트 / 중복 SDK 로드
    • 사이트 코드, CMS 플러그인 또는 다른 GTM 태그를 통해 OneSignal을 로드하지 않는지 확인하세요.
  • Add Tags가 실행되지만 OneSignal에 나타나지 않음
    • Trigger Group이 OneSignalInitialized를 기다리는지 확인하세요.
    • 사용자 작업 트리거가 실제로 실행되는지 확인하세요.
    • 태그가 유효한 키/값 쌍이고 플랜 제한 내에 있는지 확인하세요.
여전히 도움이 필요한 경우 일반적인 수정 사항은 Web SDK 문제 해결을 참조하세요.

다음 단계