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', // уникальная строка в формате reverse-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', // необязательно, установите собственный ID пользователя tags: { 'Name': 'John Smith' // необязательно, установите пользовательские теги }}]);</script>Веб-попапы
Anchor link toКампании с веб-попапами загружаются по умолчанию — запись webPopups в вашем объекте init не требуется. Добавляйте ее только для отказа или изменения настроек по умолчанию:
webPopups: { // enable: false, // необязательно, полный отказ: пакет никогда не загружается autoShow: true, // необязательно, установите false, чтобы загружать попапы без их автоматического отображения — см. методы WebPopups ниже colorScheme: 'auto', // необязательно, 'auto' (по умолчанию) | 'light' | 'dark'},Кампании с веб-попапами отображают оверлеи, которые вы настраиваете в Панели управления, такие как промо-акции, объявления или формы для сбора лидов. В отличие от пользовательского попапа подписки (subscribePopup), который обрабатывает только подписку на веб-пуши, кампании с веб-попапами могут отображать любой настроенный вами контент.
Для настройки в Панели управления см. Обзор веб-попапов.
colorScheme выбирает, с какой палитрой будет отображаться попап с настроенным темным режимом:
'auto'(по умолчанию): следует цветовой схеме на уровне ОС посетителя (prefers-color-scheme).'light'или'dark': всегда отображает эту палитру, независимо от настроек ОС посетителя.
Попап без настроенного темного режима в редакторе всегда отображается в светлой теме — colorScheme на него не влияет.
Для программного управления см. методы WebPopups и события веб-попапов.
Кнопка подписки на пуши
Anchor link toЧтобы предложить вашим пользователям подписаться на пуш-уведомления, мы рекомендуем реализовать кнопку подписки на пуши на вашем сайте. Улучшите пользовательский опыт и получите больше подписчиков!
Настройка
Anchor link toЧтобы завершить внедрение пуш-уведомлений на ваш сайт, вам необходимо настроить веб-платформы в вашей Панели управления 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 load!');}]);Чтобы отследить корректную инициализацию Web 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) => { // Выполняется во время инициализации SDK, если 'autoSubscribe: false' и/или если пользователь игнорирует запрос на пуш-уведомления. 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); });}]);События Inbox
Anchor link toОтслеживание уведомлений, отправленных в Inbox.
Pushwoosh.push(['onLoad', (api) => { // Выполняется ServiceWorker после получения сообщения Inbox и его сохранения в indexedDB. Pushwoosh.addEventHandler('receive-inbox-message', (payload) => { console.log('Triggered event: receive-inbox-message', payload.message); });
// Выполняется после автоматического обновления Inbox во время загрузки страницы. Pushwoosh.addEventHandler('update-inbox-messages', (payload) => { console.log('Triggered event: receive-inbox-message', payload.messages); });}]);События кастомного попапа подписки
Anchor link toДля получения подробной информации об обработке событий кастомного попапа подписки, пожалуйста, обратитесь к Руководству по событиям кастомного попапа подписки.
События веб-попапов
Anchor link toPushwoosh.push(['onLoad', (api) => { // Выполняется после загрузки веб-попапов и запуска автоматического конвейера отображения для текущей страницы Pushwoosh.addEventHandler('web-popups-ready', () => { console.log('Triggered event: web-popups-ready'); });
// Выполняется, когда веб-попап показывается, автоматически или через webPopups.show() Pushwoosh.addEventHandler('show-web-popup', (payload) => { console.log('Triggered event: show-web-popup', payload.code, payload.trigger); // trigger: 'auto' | 'api' });
// Выполняется, когда веб-попап скрывается Pushwoosh.addEventHandler('hide-web-popup', (payload) => { console.log('Triggered event: 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 для 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: [ // Необязательно: Массив пуш-устройств { 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('Multi-registration successful:', response); }) .catch((error) => { console.error('Multi-registration failed:', 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('success'); } else { console.warn('skipped tags:', skipped); } }) .catch((err) => { console.error('setTags error:', err); });});Увеличить значение тега
Anchor link toЧтобы увеличить значение числового тега, используйте параметр operation со значением ‘increment’ следующим образом:
Pushwoosh.push((api) => { api.setTags({ 'Tag 1': { operation: 'increment', value: 1 } })});Добавить значения тега
Anchor link toЧтобы добавить новые значения к существующему тегу типа List, используйте параметр operation со значением ‘append’ следующим образом:
Pushwoosh.push((api) => { api.setTags({ 'Tag 3': { operation: 'append', value: ['Value3'] } })});Удалить значение тега
Anchor link toЧтобы удалить значение из тега типа List, используйте параметр operation со значением ‘remove’ следующим образом:
Pushwoosh.push((api) =>{ api.setTags({ 'Tag 3': { operation: 'remove', value: ['Value2'] } })});Публичные методы
Anchor link toPushwoosh.subscribe()
Этот метод используется для запроса разрешения пользователя на пуш-уведомления. Если пользователь уже подписан, выполнение метода прекратится.
Если пользователь еще не подписался на пуши:
1. Запрашивается разрешение на пуш-уведомления.

2. Если пользователь разрешает уведомления, срабатывает событие onSubscribe.
Pushwoosh.subscribe() выполняется автоматически, если при инициализации SDK установлено autoSubscribe: true.
Вызовите этот метод, если вы решили вручную предлагать пользователю подписаться на пуши, используя параметр autoSubscribe: false во время инициализации:
<button onclick="Pushwoosh.subscribe()">Подписаться</button><script> Pushwoosh.push(['onSubscribe', (api) => { console.log('User successfully subscribed'); }]);</script>Pushwoosh.unsubscribe()
- Выполняется метод
/unregisterDevice. - Срабатывает событие
onUnsubscribe.
<button onclick="Pushwoosh.unsubscribe()">Отписаться</button><script type="text/javascript"> Pushwoosh.push(['onUnsubscribe', (api) => { console.log('User successfully unsubscribed'); }]);</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 tomessagesWithNoActionPerformedCount(): Promise<number>
Возвращает количество открытых сообщений.
Pushwoosh.pwinbox.messagesWithNoActionPerformedCount() .then((count) => { console.log(`${count} messages opened`); });unreadMessagesCount()
Возвращает количество непрочитанных сообщений.
Pushwoosh.pwinbox.unreadMessagesCount() .then((count) => { console.log(`${count} messages unread`); });messagesCount(): Promise<number>
Возвращает общее количество сообщений.
Pushwoosh.pwinbox.messagesCount() .then((count) => { console.log(`${count} messages`); });loadMessages(): Promise<Array>
Загружает список неудаленных сообщений.
Pushwoosh.pwinbox.loadMessages() .then(() => { console.log('Messages have been loaded'); });readMessagesWithCodes(codes: Array<string>): Promise<void>
Помечает сообщения как прочитанные по Inbox_Ids.
Pushwoosh.pwinbox.readMessagesWithCodes(codes) .then(() => { console.log('Messages have been read'); });performActionForMessageWithCode(code: string): Promise<void>
Выполняет действие, назначенное сообщению, и помечает сообщение как прочитанное.
Pushwoosh.pwinbox.performActionForMessageWithCode(code) .then(() => { console.log('Action has been performed'); });deleteMessagesWithCodes(codes: Array<string>): Promise<void>
Помечает сообщения как удаленные.
Pushwoosh.pwinbox.deleteMessagesWithCodes([code]) .then(() => { console.log('Messages have been deleted'); });syncMessages(): Promise<void>
Синхронизирует сообщения с сервером.
Pushwoosh.pwinbox.syncMessages() .then(() => { console.log('Messages have been synchronized'); });Методы WebPopups
Anchor link toПрограммный API веб-попапов доступен всякий раз, когда загружается виджет, что является поведением по умолчанию (см. выше). Доступ к нему осуществляется через Pushwoosh.moduleRegistry.webPopups после срабатывания события web-popups-ready.
show(code: string): Promise<boolean>
Показывает попап немедленно, обходя все условия отображения (задержка, правила страниц, тип устройства/посетителя, ограничение частоты, тип триггера). Закрывает уже видимый попап, чтобы освободить место. Возвращает false вместо отклонения, когда попап не может быть показан.
Pushwoosh.moduleRegistry.webPopups.show('popup_code') .then((shown) => console.log('Popup shown:', 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
Возвращает снимок состояния веб-попапа: 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 регистрируется, когда это необходимо:
- когда устройство получает пуш-токен (при регистрации устройства или повторной подписке),
- когда пуш-токен удаляется (при удалении устройства из базы пользователей).
Это ускоряет загрузку ваших страниц за счет сокращения количества запросов к серверу.
Браузеры не позволяют регистрировать два разных 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);Таким образом, вы включаете получение и обработку пуш-уведомлений, отправленных через сервисы Pushwoosh, для вашего Service Worker.
Установка через Google Tag Manager
Anchor link toИспользуйте следующий код в вашем Google Tag Manager для инициализации Pushwoosh SDK. Создайте тег Custom 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>