Перейти к содержанию

Web push SDK 3.0

Интеграция

Anchor link to

Пример интеграции на GitHub

Получите Pushwoosh Web Push SDK и распакуйте его. У вас должны быть следующие файлы:

Anchor link to
  • pushwoosh-service-worker.js

Разместите все эти файлы в корневой директории вашего сайта.

Anchor link to

Инициализируйте SDK:

Anchor link to
  1. Подключите SDK из нашего CDN асинхронно.
<script type="text/javascript" src="//cdn.pushwoosh.com/webpush/v3/pushwoosh-web-notifications.js" async></script>
  1. Инициализируйте 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 to
Pushwoosh.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): Платформа 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 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 to

Pushwoosh.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()

  1. Выполняется метод /unregisterDevice.
  2. Срабатывает событие 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 to

messagesWithNoActionPerformedCount(): 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>