Web push SDK 3.0
Интеграция
Anchor link toПолучите Pushwoosh Web Push SDK и распакуйте его. У вас должны быть следующие файлы:
Anchor link to- pushwoosh-service-worker.js
Поместите все эти файлы в корневой каталог вашего сайта.
Anchor link toИнициализируйте SDK:
Anchor link to- Подключите SDK из нашего CDN асинхронно.
<script type="text/javascript" src="//cdn.pushwoosh.com/webpush/v3/pushwoosh-web-notifications.js" async></script>- Инициализируйте Web Push 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 Token safariWebsitePushID: 'web.com.example.domain', // уникальная строка обратного домена, полученная на вашем портале разработчика Apple. Требуется только если вы отправляете push-уведомления в браузер Safari defaultNotificationTitle: 'Pushwoosh', // устанавливает заголовок по умолчанию для push-уведомлений defaultNotificationImage: 'https://yoursite.com/img/logo-medium.png', // URL для пользовательского изображения уведомления autoSubscribe: false, // или true. Если true, запрашивает у пользователя подписку на push-уведомления при инициализации SDK subscribeWidget: { enable: true }, userId: 'user_id', // необязательно, установите пользовательский ID tags: { 'Name': 'John Smith' // необязательно, установите пользовательские Теги }}]);</script>Web popups
Anchor link toДобавьте webPopups в ваш объект init, чтобы включить кампании Web popup на вашем сайте.
webPopups: { enable: true, autoShow: true, // необязательно, установите в false, чтобы загружать всплывающие окна без их автоматического отображения — см. методы WebPopups ниже},Кампании Web popup отображают оверлеи, которые вы настраиваете в Панели управления, такие как промо-акции, объявления или формы для сбора лидов. В отличие от пользовательского всплывающего окна подписки (subscribePopup), которое обрабатывает только подписку на web push, кампании Web popup могут отображать любой настроенный вами контент.
Для настройки в Панели управления см. Обзор Web popups.
Для программного управления см. методы WebPopups и события Web popup.
Кнопка подписки на push-уведомления
Anchor link toЧтобы предложить вашим пользователям подписаться на push-уведомления, мы рекомендуем реализовать кнопку подписки на push-уведомления на вашем сайте. Улучшите пользовательский опыт и получите больше подписчиков!
Конфигурация
Anchor link toЧтобы завершить внедрение push-уведомлений на ваш сайт, вам необходимо настроить веб-платформы в вашей Панели управления Pushwoosh, следуя нашим пошаговым руководствам:
Регистрация service worker в другой области видимости
Anchor link toИногда вы не можете разместить файл service worker в корневом каталоге сайта, а только в подкаталоге.
В этом случае измените конфигурацию (шаг 4.3), добавив параметр
serviceWorkerUrl: “/push-notifications/pushwoosh-service-worker.js”
где /push-notifications/pushwoosh-service-worker.js — это путь к файлу pushwoosh-service-worker.js.
Обработчики событий
Anchor link toВ Pushwoosh Web SDK 3.0 вы можете подписываться на определенные события для их отслеживания** или** отписываться от событий, если вам больше не нужно их отслеживать.
Чтобы отследить загрузку Web SDK 3.0, вызовите событие onLoad следующим образом:
// Событие загрузкиPushwoosh.push(['onLoad', (api) => { console.log('Pushwoosh загружен!');}]);Чтобы отследить корректную инициализацию Web SDK, вызовите событие onReady:
// Событие готовностиPushwoosh.push((api) => { console.log('Pushwoosh готов!');});Чтобы подписаться или отписаться от любого из событий SDK, используйте обработчики после загрузки SDK:
Pushwoosh.push(['onLoad', (api) => { function onEventNameHandler() { console.log('Сработало событие: event-name!'); }
// Чтобы подписаться на событие: Pushwoosh.addEventHandler('event-name', onEventNameHandler)
// Чтобы отписаться от события: Pushwoosh.removeEventHandler('event-name', onEventNameHandler)}]);События SDK
Anchor link toСобытие подписки (subscribe)
Anchor link toВыполняется после того, как пользователь соглашается получать push-уведомления.
Pushwoosh.push(['onLoad', (api) => { Pushwoosh.addEventHandler('subscribe', (payload) => { console.log('Сработало событие: subscribe'); });}]);Событие отписки (unsubscribe)
Anchor link toВыполняется после отмены регистрации устройства для получения уведомлений.
Pushwoosh.push(['onLoad', (api) => { Pushwoosh.addEventHandler('unsubscribe', (payload) => { console.log('Сработало событие: unsubscribe'); });}]);События виджета подписки
Anchor link toОтслеживание отображения виджета запроса на подписку.
Pushwoosh.push(['onLoad', (api) => { // Выполняется при отображении виджета запроса на подписку Pushwoosh.addEventHandler('show-subscription-widget', (payload) => { console.log('Сработало событие: show-subscription-widget'); });
// Выполняется при скрытии виджета запроса на подписку Pushwoosh.addEventHandler('hide-subscription-widget', (payload) => { console.log('Сработало событие: hide-subscription-widget'); });}]);События диалогового окна разрешения на уведомления
Anchor link toОтслеживание отображения нативного диалогового окна подписки.
Pushwoosh.push(['onLoad', function (api) { // Выполняется при отображении диалогового окна разрешения Pushwoosh.addEventHandler('show-notification-permission-dialog', (payload) => { console.log('Сработало событие: show-notification-permission-dialog'); });
// Выполняется при скрытии диалогового окна разрешения с одним из трех возможных статусов: // 1. default - диалоговое окно закрыто // 2. granted - разрешение предоставлено // 3. denied - в разрешении отказано Pushwoosh.addEventHandler('hide-notification-permission-dialog', (payload) => { console.log('Сработало событие: hide-notification-permission-dialog', payload.permission); });}]);События разрешений
Anchor link toПроверка статуса разрешения на push-уведомления при инициализации SDK; отслеживание обновления этого статуса всякий раз, когда оно происходит.
Pushwoosh.push(['onLoad', (api) => { // Выполняется во время инициализации SDK, если 'autoSubscribe: false' и/или если пользователь игнорирует запрос на push-уведомления. Pushwoosh.addEventHandler('permission-default', (payload) => { console.log('Сработало событие: permission-default'); });
// Выполняется во время инициализации SDK, если уведомления заблокированы, или как только пользователь блокирует push-уведомления. Pushwoosh.addEventHandler('permission-denied', (payload) => { console.log('Сработало событие: permission-denied'); });
// Выполняется во время инициализации SDK, если уведомления разрешены, или как только пользователь разрешает push-уведомления. Pushwoosh.addEventHandler('permission-granted', (payload) => { console.log('Сработало событие: permission-granted'); });}]);Событие получения push-уведомления
Anchor link toОтслеживание доставки push-уведомления на устройство.
Pushwoosh.push(['onLoad', (api) => { // Выполняется, когда отображается push-уведомление. Pushwoosh.addEventHandler('receive-push', (payload) => { console.log('Сработало событие: receive-push', payload.notification); });}]);События уведомлений
Anchor link toОтслеживание, открыто или закрыто push-уведомление пользователем.
Pushwoosh.push(['onLoad', (api) => { // Выполняется, когда пользователь нажимает на уведомление. Pushwoosh.addEventHandler('open-notification', (payload) => { console.log('Сработало событие: open-notification', payload.notification); });
// Выполняется, когда пользователь закрывает push-уведомление. Pushwoosh.addEventHandler('hide-notification', (payload) => { console.log('Сработало событие: hide-notification', payload.notification); });}]);События Inbox
Anchor link toОтслеживание уведомлений, отправленных в Inbox.
Pushwoosh.push(['onLoad', (api) => { // Выполняется ServiceWorker после получения сообщения Inbox и его сохранения в indexedDB. Pushwoosh.addEventHandler('receive-inbox-message', (payload) => { console.log('Сработало событие: receive-inbox-message', payload.message); });
// Выполняется после автоматического обновления Inbox во время загрузки страницы. Pushwoosh.addEventHandler('update-inbox-messages', (payload) => { console.log('Сработало событие: receive-inbox-message', payload.messages); });}]);События кастомного всплывающего окна подписки
Anchor link toДля получения подробной информации об обработке событий кастомного всплывающего окна подписки, пожалуйста, обратитесь к Руководству по событиям кастомного всплывающего окна подписки.
События Web popup
Anchor link toPushwoosh.push(['onLoad', (api) => { // Выполняется после загрузки web popups и запуска конвейера автоматического отображения для текущей страницы Pushwoosh.addEventHandler('web-popups-ready', () => { console.log('Сработало событие: web-popups-ready'); });
// Выполняется, когда web popup отображается, автоматически или через webPopups.show() Pushwoosh.addEventHandler('show-web-popup', (payload) => { console.log('Сработало событие: show-web-popup', payload.code, payload.trigger); // trigger: 'auto' | 'api' });
// Выполняется, когда web popup скрывается Pushwoosh.addEventHandler('hide-web-popup', (payload) => { console.log('Сработало событие: hide-web-popup', payload.code, payload.reason); // reason: 'user' | 'api' | 'preempted' });}]);После инициализации Web Push SDK вы можете делать следующие вызовы к Pushwoosh API. Все методы возвращают объекты Promise.
Pushwoosh.push((api) => { // Установить теги для пользователя api.setTags({ 'Tag Name 1': 'value1', 'Tag Name 2': 'value2' });
// Получить теги для пользователя с сервера api.getTags();
// Зарегистрировать ID пользователя api.registerUser('user123');
// Зарегистрировать email пользователя api.registerEmail('user@example.com');
// Зарегистрировать номер SMS api.registerSmsNumber('+15551234567');
// Зарегистрировать номер WhatsApp api.registerWhatsappNumber('+1234567890');
// Отправить Событие api.postEvent('myEventName', {attributeName: 'attributeValue'});
//Отписаться от уведомлений api.unregisterDevice();
// Установить язык устройства (переопределяет значение в теге "Language") 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', // Необязательно: Email для сообщений по электронной почте sms_phone_number: '+1234567890', // Необязательно: Номер телефона для SMS (формат E.164) whatsapp_phone_number: '+1234567890', // Необязательно: Номер WhatsApp (формат E.164) kakao_phone_number: '+1234567890', // Необязательно: Номер KakaoTalk (формат 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: [ // Необязательно: Массив push-устройств { 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): Платформа SafariTPlatformChrome(11): Платформа ChromeTPlatformFirefox(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('успешно'); } 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 toPushwoosh.subscribe()
Этот метод используется для запроса разрешения пользователя на push-уведомления. Если пользователь уже подписан, выполнение метода прекратится.
Если пользователь еще не подписан на push-уведомления:
1. Запрашивается разрешение на push-уведомления.

2. Если пользователь разрешает уведомления, срабатывает событие onSubscribe.
Pushwoosh.subscribe() выполняется автоматически, если при инициализации SDK установлено autoSubscribe: true.
Вызовите этот метод, если вы решили вручную запрашивать у пользователя подписку на push-уведомления, используя параметр autoSubscribe: false во время инициализации:
<button onclick="Pushwoosh.subscribe()">Подписаться</button><script> Pushwoosh.push(['onSubscribe', (api) => { console.log('Пользователь успешно подписан'); }]);</script>Pushwoosh.unsubscribe()
- Выполняется метод
/unregisterDevice. - Срабатывает событие
onUnsubscribe.
<button onclick="Pushwoosh.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()
Возвращает push-токен, если он доступен.
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 tomessagesWithNoActionPerformedCount(): 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('Сообщения были синхронизированы'); });Методы WebPopups
Anchor link toПрограммный API Web popups требует webPopups: {enable: true} в объекте init; он доступен через Pushwoosh.moduleRegistry.webPopups после срабатывания события web-popups-ready.
show(code: string): Promise<boolean>
Показывает всплывающее окно немедленно, обходя все условия отображения (задержка, правила страницы, тип устройства/посетителя, ограничение частоты, тип триггера). Закрывает уже видимое всплывающее окно, чтобы освободить место. Возвращает false вместо отклонения, когда всплывающее окно не может быть показано.
Pushwoosh.moduleRegistry.webPopups.show('popup_code') .then((shown) => console.log('Всплывающее окно показано:', shown));hide(code?: string): boolean
Скрывает видимое всплывающее окно. Если передан code, скрывает его только тогда, когда он совпадает с видимым всплывающим окном. Возвращает false, если ничего не было скрыто.
Pushwoosh.moduleRegistry.webPopups.hide();hideAll(): boolean
Скрывает видимое всплывающее окно и отменяет все, что еще ожидает отображения для текущей загрузки страницы. show() продолжает работать после этого.
Pushwoosh.moduleRegistry.webPopups.hideAll();isVisible(code?: string): boolean
Проверяет, видно ли в данный момент всплывающее окно. Без code проверяет, видно ли какое-либо всплывающее окно.
Pushwoosh.moduleRegistry.webPopups.isVisible('popup_code');getVisibleCode(): string | null
Возвращает код всплывающего окна, которое в данный момент отображается на экране, или null, если ни одно не видно.
Pushwoosh.moduleRegistry.webPopups.getVisibleCode();getAvailableCodes(): Array<string>
Возвращает коды всех всплывающих окон, которые сервер вернул для этого устройства.
Pushwoosh.moduleRegistry.webPopups.getAvailableCodes();getState(): object
Возвращает снимок состояния Web popup: visible (код на экране или null), queued (коды, ожидающие слота для отображения), waiting (коды с активированным таймером задержки) и available (все коды, которые вернул сервер).
Pushwoosh.moduleRegistry.webPopups.getState();Поддержка Progressive Web App
Anchor link toЧтобы интегрировать Pushwoosh в ваше Progressive Web Application (PWA), выполните описанные ниже шаги.
1. Скопируйте путь к вашему файлу Service Worker:
if ('serviceWorker' in navigator) { window.addEventListener('load', () => { navigator.serviceWorker.register('/service-worker.js') // <- URL вашего service worker });}Затем используйте параметр serviceWorkerUrl при инициализации WebSDK следующим образом:
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 вашего service worker}]);WebSDK не регистрирует новый Service Worker немедленно; Service Worker регистрируется, когда это необходимо:
- когда устройство получает push-токен (при регистрации устройства или повторной подписке),
- когда push-токен удаляется (при удалении устройства из базы пользователей).
Это ускоряет загрузку ваших страниц за счет сокращения количества запросов к серверу.
Браузеры не позволяют регистрировать два разных Service Worker одновременно (подробнее: https://github.com/w3c/ServiceWorker/issues/921), поэтому для корректной работы вашего PWA необходимо зарегистрировать общий Service Worker для вашей кодовой базы и кодовой базы Pushwoosh.
2. Добавьте следующую строку в ваш Service Worker (в начало или в конец, это не имеет значения):
importScripts('https://cdn.pushwoosh.com/webpush/v3/pushwoosh-service-worker.js' + self.location.search);Таким образом, вы включаете получение и обработку push-уведомлений, отправленных через сервисы Pushwoosh, для вашего Service Worker.
Установка из Google Tag Manager
Anchor link toИспользуйте следующий код в вашем Google Tag Manager для инициализации Pushwoosh SDK. Создайте пользовательский тег HTML и вставьте код ниже. Убедитесь, что вы изменили код вашего приложения Pushwoosh, Safari Website 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>