콘텐츠로 건너뛰기
사용자 가이드지원 데모 요청 로그인
Pushwoosh.com

웹 푸시 SDK 3.0

통합

Anchor link to

GitHub의 통합 샘플

Pushwoosh 웹 푸시 SDK를 다운로드하여 압축을 풉니다. 다음 파일이 있어야 합니다:

Anchor link to
  • pushwoosh-service-worker.js

이 모든 파일을 웹사이트 디렉토리의 최상위 루트에 배치하세요.

Anchor link to

SDK 초기화:

Anchor link to
  1. CDN에서 SDK를 비동기적으로 포함합니다.
<script type="text/javascript" src="//cdn.pushwoosh.com/webpush/v3/pushwoosh-web-notifications.js" async></script>
  1. 웹 푸시 SDK를 초기화하고 SDK가 완전히 로드될 때까지 초기화를 큐에 넣어야 합니다.
<script type="text/javascript">
var Pushwoosh = Pushwoosh || [];
Pushwoosh.push(['init', {
    logLevel: 'info', // 가능한 값: error, info, debug
    applicationCode: 'XXXXX-XXXXX', // Pushwoosh 제어판의 애플리케이션 코드
    apiToken: 'XXXXXXX', //  Device API 토큰
    safariWebsitePushID: 'web.com.example.domain', //  Apple 개발자 포털에서 얻은 고유한 역도메인 문자열. Safari 브라우저로 푸시 알림을 보낼 경우에만 필요합니다.
    defaultNotificationTitle: 'Pushwoosh', // 푸시 알림의 기본 제목을 설정합니다.
    defaultNotificationImage: 'https://yoursite.com/img/logo-medium.png', // 사용자 지정 알림 이미지의 URL
    autoSubscribe: false, // 또는 true. true인 경우 SDK 초기화 시 사용자에게 푸시 구독을 요청합니다.
    subscribeWidget: {
      enable: true
    },
    userId: 'user_id', // 선택 사항, 사용자 지정 User ID 설정
    tags: {
        'Name': 'John Smith'     // 선택 사항, 사용자 지정 태그 설정
    }
}]);
</script>

웹 팝업

Anchor link to

사이트에서 웹 팝업 캠페인을 활성화하려면 init 객체에 webPopups를 추가하세요.

webPopups: {
  enable: true,
},

웹 팝업 캠페인은 프로모션, 공지 또는 리드 캡처 양식과 같이 제어판에서 구성하는 오버레이를 표시합니다. 웹 푸시 옵트인만 처리하는 사용자 지정 구독 팝업 (subscribePopup)과 달리 웹 팝업 캠페인은 구성한 모든 콘텐츠를 표시할 수 있습니다. 제어판에서의 설정은 웹 팝업 이해하기를 참조하세요.

푸시 구독 버튼

Anchor link to

사용자에게 푸시 알림 구독을 유도하려면 웹사이트에 푸시 구독 버튼을 구현하는 것이 좋습니다. 사용자 경험을 향상시키고 더 많은 구독자를 확보하세요!

구성

Anchor link to

웹사이트에 푸시 알림 구현을 완료하려면 단계별 가이드에 따라 Pushwoosh 제어판에서 웹 플랫폼을 구성해야 합니다:

다른 범위에 서비스 워커 등록하기

Anchor link to

때로는 서비스 워커 파일을 웹사이트의 루트 디렉토리가 아닌 하위 디렉토리에 배치해야 할 수도 있습니다.

이 경우, 매개변수를 추가하여 구성(4.3단계)을 수정합니다.

serviceWorkerUrl: “/push-notifications/pushwoosh-service-worker.js”

여기서 /push-notifications/pushwoosh-service-worker.js는 pushwoosh-service-worker.js 파일의 경로입니다.

이벤트 핸들러

Anchor link to

Pushwoosh 웹 SDK 3.0에서는 특정 이벤트를 구독하여 추적하거나, 더 이상 추적이 필요하지 않은 경우 이벤트 구독을 취소할 수 있습니다.

웹 SDK 3.0 로드를 추적하려면 다음과 같이 onLoad 이벤트를 발생시키세요:

// 로드 이벤트
Pushwoosh.push(['onLoad', (api) => {
  console.log('Pushwoosh load!');
}]);

올바른 웹 SDK 초기화를 추적하려면 onReady 이벤트를 발생시키세요:

// 준비 이벤트
Pushwoosh.push((api) => {
  console.log('Pushwoosh ready!');
});

SDK 이벤트 중 하나를 구독하거나 구독 취소하려면 SDK 로드 후 핸들러를 사용하세요:

Pushwoosh.push(['onLoad', (api) => {
  function onEventNameHandler() {
    console.log('Triggered event: event-name!');
  }


  // 이벤트 구독하기:
  Pushwoosh.addEventHandler('event-name', onEventNameHandler)


  // 이벤트 구독 취소하기:
  Pushwoosh.removeEventHandler('event-name', onEventNameHandler)
}]);

SDK 이벤트

Anchor link to

구독 이벤트

Anchor link to

사용자가 푸시 알림 수신에 동의한 후 실행됩니다.

Pushwoosh.push(['onLoad', (api) => {
  Pushwoosh.addEventHandler('subscribe', (payload) => {
    console.log('Triggered event: subscribe');
  });
}]);

구독 취소 이벤트

Anchor link to

기기가 알림에서 등록 해제된 후 실행됩니다.

Pushwoosh.push(['onLoad', (api) => {
  Pushwoosh.addEventHandler('unsubscribe', (payload) => {
    console.log('Triggered event: unsubscribe');
  });
}]);

구독 위젯 이벤트

Anchor link to

구독 프롬프트 위젯의 표시를 추적합니다.

Pushwoosh.push(['onLoad', (api) => {
  // 구독 프롬프트 위젯이 표시될 때 실행됩니다.
  Pushwoosh.addEventHandler('show-subscription-widget', (payload) => {
    console.log('Triggered event: show-subscription-widget');
  });


  // 구독 프롬프트 위젯이 숨겨질 때 실행됩니다.
  Pushwoosh.addEventHandler('hide-subscription-widget', (payload) => {
    console.log('Triggered event: hide-subscription-widget');
  });
}]);

알림 권한 대화상자 이벤트

Anchor link to

네이티브 구독 대화상자의 표시를 추적합니다.

Pushwoosh.push(['onLoad', function (api) {
  // 권한 대화상자가 표시될 때 실행됩니다.
  Pushwoosh.addEventHandler('show-notification-permission-dialog', (payload) => {
    console.log('Triggered event: show-notification-permission-dialog');
  });


  // 다음 세 가지 가능한 상태 중 하나로 권한 대화상자가 숨겨질 때 실행됩니다:
  // 1. default - 대화상자가 닫힘
  // 2. granted - 권한이 허용됨
  // 3. denied - 권한이 거부됨
  Pushwoosh.addEventHandler('hide-notification-permission-dialog', (payload) => {
    console.log('Triggered event: hide-notification-permission-dialog', payload.permission);
  });
}]);

권한 이벤트

Anchor link to

SDK 초기화 시 푸시 알림 권한 상태를 확인하고, 이 상태가 변경될 때마다 업데이트를 추적합니다.

Pushwoosh.push(['onLoad', (api) => {
  // 'autoSubscribe: false'이거나 사용자가 푸시 알림 프롬프트를 무시하는 경우 SDK 초기화 중에 실행됩니다.
  Pushwoosh.addEventHandler('permission-default', (payload) => {
    console.log('Triggered event: permission-default');
  });


  // 알림이 차단되었거나 사용자가 푸시 알림을 차단하면 SDK 초기화 중에 실행됩니다.
  Pushwoosh.addEventHandler('permission-denied', (payload) => {
    console.log('Triggered event: permission-denied');
  });


  // 알림이 허용되었거나 사용자가 푸시 알림을 허용하면 SDK 초기화 중에 실행됩니다.
  Pushwoosh.addEventHandler('permission-granted', (payload) => {
    console.log('Triggered event: permission-granted');
  });
}]);

푸시 수신 이벤트

Anchor link to

기기로의 푸시 전송을 추적합니다.

Pushwoosh.push(['onLoad', (api) => {
  // 푸시 알림이 표시될 때 실행됩니다.
  Pushwoosh.addEventHandler('receive-push', (payload) => {
    console.log('Triggered event: receive-push', payload.notification);
  });
}]);

알림 이벤트

Anchor link to

사용자가 푸시 알림을 열었는지 또는 닫았는지 추적합니다.

Pushwoosh.push(['onLoad', (api) => {
  // 사용자가 알림을 클릭할 때 실행됩니다.
  Pushwoosh.addEventHandler('open-notification', (payload) => {
    console.log('Triggered event: open-notification', payload.notification);
  });


  // 사용자가 푸시 알림을 닫을 때 실행됩니다.
  Pushwoosh.addEventHandler('hide-notification', (payload) => {
    console.log('Triggered event: hide-notification', payload.notification);
  });
}]);

인박스 이벤트

Anchor link to

인박스로 전송된 알림을 추적합니다.

Pushwoosh.push(['onLoad', (api) => {
  // 인박스 메시지를 수신하고 indexedDB에 저장한 후 ServiceWorker에 의해 실행됩니다.
  Pushwoosh.addEventHandler('receive-inbox-message', (payload) => {
    console.log('Triggered event: receive-inbox-message', payload.message);
  });


  // 페이지 로딩 중 인박스가 자동으로 업데이트된 후 실행됩니다.
  Pushwoosh.addEventHandler('update-inbox-messages', (payload) => {
    console.log('Triggered event: receive-inbox-message', payload.messages);
  });
}]);

사용자 지정 구독 팝업 이벤트

Anchor link to

사용자 지정 구독 팝업 이벤트 처리에 대한 자세한 내용은 사용자 지정 구독 팝업 이벤트 가이드를 참조하세요.

API

Anchor link to

웹 푸시 SDK가 초기화된 후 Pushwoosh API에 다음 호출을 할 수 있습니다. 모든 메서드는 Promise 객체를 반환합니다.

Pushwoosh.push((api) => {
  // 사용자에 대한 태그 설정
  api.setTags({
    'Tag Name 1': 'value1',
    'Tag Name 2': 'value2'
  });


  // 서버에서 사용자에 대한 태그 가져오기
  api.getTags();


  // User ID 등록
  api.registerUser('user123');


    // 사용자 이메일 등록
  api.registerEmail('user@example.com');


  // SMS 번호 등록
  api.registerSmsNumber('+15551234567');


  // WhatsApp 번호 등록
  api.registerWhatsappNumber('+1234567890');


  // 이벤트 게시
  api.postEvent('myEventName', {attributeName: 'attributeValue'});


  //알림에서 등록 해제
  api.unregisterDevice();


  // 기기 언어 설정("언어" 태그의 값을 덮어씁니다)
  api.setLanguage('es');


  // 또는 기기 및 채널로 사용자 다중 등록
  api.multiRegisterDevice({
    user_id: 'user123',
    email: 'user@example.com',
    sms_phone_number: '+1234567890',
    tags: {
      'UserType': { operation: TTagOperationSet, value: 'Premium' },
      'Interests': { operation: TTagOperationAppend, values: ['sports', 'technology'] }
    }
  });
});

multiRegisterDevice

Anchor link to

단일 API 호출로 여러 기기 및 메시징 채널이 있는 사용자 프로필을 등록할 수 있는 향상된 등록 방법입니다. 이 방법은 크로스 플랫폼 애플리케이션이나 옴니채널 메시징 전략을 구현할 때 특히 유용합니다.

Pushwoosh.push((api) => {
  api.multiRegisterDevice({
    user_id: 'user123',              // 선택 사항: 사용자 식별자
    email: 'user@example.com',       // 선택 사항: 이메일 메시징을 위한 이메일
    sms_phone_number: '+1234567890', // 선택 사항: SMS 전화번호 (E.164 형식)
    whatsapp_phone_number: '+1234567890', // 선택 사항: WhatsApp 번호 (E.164 형식)
    kakao_phone_number: '+1234567890',    // 선택 사항: 카카오톡 번호 (E.164 형식)
    language: 'en',                  // 선택 사항: 언어 코드 (ISO 639-1)
    timezone: 'America/New_York',    // 선택 사항: 시간대 식별자
    city: 'New York',               // 선택 사항: 타겟팅을 위한 도시
    country: 'US',                  // 선택 사항: 타겟팅을 위한 국가
    state: 'NY',                    // 선택 사항: 타겟팅을 위한 주
    tags: {                         // 선택 사항: 연산이 포함된 태그 값
      'UserType': {
        operation: TTagOperationSet,     // 태그 값 설정 (0)
        value: 'Premium'
      },
      'Interests': {
        operation: TTagOperationAppend,  // 태그 값에 추가 (1)
        values: ['sports', 'technology']
      },
      'LoginCount': {
        operation: TTagOperationIncrement, // 태그 값 증가 (3)
        value: '1'
      }
    },
    push_devices: [                 // 선택 사항: 푸시 기기 배열
      {
        hwid: 'web-device-456',
        platform: TPlatformChrome, // Chrome 플랫폼 (11)
        push_token: 'fcm-token-here',
        app_version: '2.1.0',
        platformData: {
          public_key: 'web-push-public-key',
          auth_token: 'web-push-auth-token',
          browser: 'chrome'
        }
      }
    ]
  })
  .then((response) => {
    console.log('다중 등록 성공:', response);
  })
  .catch((error) => {
    console.error('다중 등록 실패:', error);
  });
});

플랫폼 유형:

  • TPlatformSafari (10): Safari 플랫폼
  • TPlatformChrome (11): Chrome 플랫폼
  • TPlatformFirefox (12): Firefox 플랫폼

태그 연산 유형:

  • TTagOperationSet (0): 태그 값 설정 (기존 값 교체)
  • TTagOperationAppend (1): 태그 값에 추가 (목록에 추가)
  • TTagOperationRemove (2): 태그 값 제거 (목록에서 제거)
  • TTagOperationIncrement (3): 태그 값 증가 (숫자 증가)

이점:

  • 단일 API 호출: 여러 기기와 채널을 한 번에 등록
  • 원자적 연산: 모든 등록이 함께 성공하거나 실패
  • 사용자 중심: 모든 기기를 단일 사용자 프로필과 연결
  • 고급 태깅: 복잡한 태그 연산 지원
  • 크로스 플랫폼: 여러 플랫폼을 동시에 처리

Pushwoosh로 태그를 보내는 예:

Pushwoosh.push((api) => {
  var myCustomTags = {
    'Tag 1': 123,
    'Tag 2': 'some string'
  };
  api.setTags(myCustomTags)
    .then((res) => {
      var skipped = res && res.skipped || [];
      if (!skipped.length) {
        console.log('success');
      }
      else {
        console.warn('건너뛴 태그:', skipped);
      }
    })
    .catch((err) => {
      console.error('setTags 오류:', err);
    });
});

태그 값 증가

Anchor link to

숫자 태그의 값을 증가시키려면 operation 매개변수를 ‘increment’ 값과 함께 다음과 같이 사용합니다:

Pushwoosh.push((api) => {
  api.setTags({
    'Tag 1': {
      operation: 'increment',
      value: 1
    }
  })
});

태그 값 추가

Anchor link to

기존 목록 태그에 새 값을 추가하려면 operation 매개변수를 ‘append’ 값과 함께 다음과 같이 사용합니다:

Pushwoosh.push((api) => {
  api.setTags({
    'Tag 3': {
      operation: 'append',
      value: ['Value3']
    }
  })
});

태그 값 제거

Anchor link to

목록 태그에서 값을 제거하려면 operation 매개변수를 ‘remove’ 값과 함께 다음과 같이 사용합니다:

Pushwoosh.push((api) =>{
  api.setTags({
    'Tag 3': {
      operation: 'remove',
      value: ['Value2']
    }
  })
});

공개 메서드

Anchor link to

Pushwoosh.subscribe()

이 메서드는 사용자에게 푸시 알림 권한을 요청하는 데 사용됩니다. 사용자가 이미 구독한 경우 메서드 실행이 중지됩니다.

사용자가 아직 푸시를 구독하지 않은 경우:

1. 푸시 알림에 대한 권한이 요청됩니다.

2. 사용자가 알림을 허용하면 onSubscribe 이벤트가 트리거됩니다.

SDK 초기화 중에 autoSubscribe: true.가 설정된 경우 Pushwoosh.subscribe()가 자동으로 실행됩니다.

초기화 중에 autoSubscribe: false 매개변수를 사용하여 사용자에게 수동으로 푸시 구독을 요청하도록 선택한 경우 이 메서드를 호출하세요:

<button onclick="Pushwoosh.subscribe()">Subscribe</button>
<script>
  Pushwoosh.push(['onSubscribe', (api) => {
    console.log('사용자가 성공적으로 구독했습니다');
  }]);
</script>

Pushwoosh.unsubscribe()

  1. /unregisterDevice 메서드가 실행됩니다.
  2. onUnsubscribe 이벤트가 트리거됩니다.
<button onclick="Pushwoosh.unsubscribe()">Unsubscribe</button>
<script type="text/javascript">
  Pushwoosh.push(['onUnsubscribe', (api) => {
    console.log('사용자가 성공적으로 구독을 취소했습니다');
  }]);
</script>

Pushwoosh.isSubscribed()

사용자가 구독했는지 확인하고 true/false 플래그를 반환합니다.

Pushwoosh.isSubscribed().then((isSubscribed) => {
  console.log('isSubscribed', isSubscribed);
});

Pushwoosh.getHWID()

Pushwoosh HWID를 반환합니다.

Pushwoosh.getHWID().then((hwid) => {
  console.log('hwid:', hwid);
});

Pushwoosh.getPushToken()

푸시 토큰이 사용 가능한 경우 반환합니다.

Pushwoosh.getPushToken().then((pushToken) => {
  console.log('pushToken:', pushToken);
});

Pushwoosh.getUserId()

User ID가 사용 가능한 경우 반환합니다.

Pushwoosh.getUserId().then((userId) => {
  console.log('userId:', userId);
});

Pushwoosh.getParams()

다음 매개변수 목록을 반환합니다:

Pushwoosh.getParams().then((params) => {
  params = params || {};
  var hwid = params.hwid;
  var pushToken = params.pushToken;
  var userId = params.userId;
});

Pushwoosh.isAvailableNotifications()

브라우저가 Pushwoosh WebSDK 3.0을 지원하는지 확인하고 ‘true’ 또는 ‘false’를 반환합니다.

Pushwoosh.isAvailableNotifications() // true/false

InboxMessages 메서드

Anchor link to

messagesWithNoActionPerformedCount(): Promise<number>

열린 메시지 수를 반환합니다.

Pushwoosh.pwinbox.messagesWithNoActionPerformedCount()
  .then((count) => {
    console.log(`${count}개의 메시지가 열렸습니다`);
  });

unreadMessagesCount()

읽지 않은 메시지 수를 반환합니다.

Pushwoosh.pwinbox.unreadMessagesCount()
  .then((count) => {
    console.log(`${count}개의 메시지를 읽지 않았습니다`);
  });

messagesCount(): Promise<number>

총 메시지 수를 반환합니다.

Pushwoosh.pwinbox.messagesCount()
  .then((count) => {
    console.log(`${count}개의 메시지`);
  });

loadMessages(): Promise<Array>

삭제되지 않은 메시지 목록을 로드합니다.

Pushwoosh.pwinbox.loadMessages()
  .then(() => {
    console.log('메시지가 로드되었습니다');
  });

readMessagesWithCodes(codes: Array<string>): Promise<void>

Inbox_Ids로 메시지를 읽음으로 표시합니다.

Pushwoosh.pwinbox.readMessagesWithCodes(codes)
  .then(() => {
    console.log('메시지를 읽었습니다');
  });

performActionForMessageWithCode(code: string): Promise<void>

메시지에 할당된 작업을 수행하고 메시지를 읽음으로 표시합니다.

Pushwoosh.pwinbox.performActionForMessageWithCode(code)
  .then(() => {
    console.log('작업이 수행되었습니다');
  });

deleteMessagesWithCodes(codes: Array<string>): Promise<void>

메시지를 삭제됨으로 표시합니다.

Pushwoosh.pwinbox.deleteMessagesWithCodes([code])
  .then(() => {
    console.log('메시지가 삭제되었습니다');
  });

syncMessages(): Promise<void>

서버와 메시지를 동기화합니다.

Pushwoosh.pwinbox.syncMessages()
  .then(() => {
    console.log('메시지가 동기화되었습니다');
  });

프로그레시브 웹 앱 지원

Anchor link to

Pushwoosh를 프로그레시브 웹 애플리케이션(PWA)에 통합하려면 아래 설명된 단계를 따르세요.

1. 서비스 워커 파일의 경로를 복사합니다:

if ('serviceWorker' in navigator) {
  window.addEventListener('load', () => {
    navigator.serviceWorker.register('/service-worker.js') // <- 서비스 워커 URL
  });
}

그런 다음, WebSDK를 초기화하는 동안 다음과 같이 serviceWorkerUrl 매개변수를 사용합니다:

var Pushwoosh = Pushwoosh || [];
Pushwoosh.push(['init', {
  logLevel: 'error',
  applicationCode: 'XXXXX-XXXXX',
  safariWebsitePushID: 'web.com.example.domain',
  defaultNotificationTitle: 'Pushwoosh',
  defaultNotificationImage: 'https://yoursite.com/img/logo-medium.png',
  serviceWorkerUrl: '/service-worker.js', // <- 서비스 워커 URL
}]);

WebSDK는 새 서비스 워커를 즉시 등록하지 않습니다. 서비스 워커는 필요할 때 등록됩니다:

  • 기기가 푸시 토큰을 수신할 때 (기기 등록 또는 재구독 시),
  • 푸시 토큰이 삭제될 때 (사용자 기반에서 기기 제거 시).

서버 요청 수를 줄여 페이지 로딩 속도를 높입니다.

브라우저는 두 개의 다른 서비스 워커가 동시에 등록되는 것을 허용하지 않으므로(자세히 보기: https://github.com/w3c/ServiceWorker/issues/921), PWA가 올바르게 작동하려면 코드베이스와 Pushwoosh 코드베이스에 공통 서비스 워커를 등록해야 합니다.

2. 서비스 워커에 다음 문자열을 추가합니다(시작 또는 끝 부분, 상관없음):

importScripts('https://cdn.pushwoosh.com/webpush/v3/pushwoosh-service-worker.js' + self.location.search);

따라서 서비스 워커가 Pushwoosh 서비스를 통해 전송된 푸시 알림을 수신하고 처리할 수 있도록 합니다.

Google Tag Manager에서 설치하기

Anchor link to

Google Tag Manager에서 다음 코드를 사용하여 Pushwoosh SDK를 초기화하세요. 사용자 지정 HTML 태그를 만들고 아래 코드를 붙여넣습니다. Pushwoosh 애플리케이션 코드, Safari 웹사이트 ID 및 기본 알림 이미지 URL을 변경해야 합니다.
또한 높은 태그 실행 우선순위(예: 100)를 설정하고 모든 페이지에서 트리거하세요. 아래 스크린샷을 참조하세요.복사

<script type="text/javascript" src="//cdn.pushwoosh.com/webpush/v3/pushwoosh-web-notifications.js" async></script>
<script type="text/javascript">
  var Pushwoosh = Pushwoosh || [];
  Pushwoosh.push(['init', {
    logLevel: 'error',
    applicationCode: 'XXXXX-XXXXX',
    safariWebsitePushID: 'web.com.example.domain',
    defaultNotificationTitle: 'Pushwoosh',
    defaultNotificationImage: 'https://yoursite.com/img/logo-medium.png',
    autoSubscribe: true,
    subscribeWidget: {
      enable: false
    },
    userId: 'user_id'
  }]);
</script>