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

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', // уникальная строка обратного домена, полученная на вашем портале разработчика 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 to
Pushwoosh.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): Платформа 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('успешно');
}
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()

Этот метод используется для запроса разрешения пользователя на 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()

  1. Выполняется метод /unregisterDevice.
  2. Срабатывает событие 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 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('Сообщения были синхронизированы');
});

Методы 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>