# Web push SDK 3.0
## Интеграция
[**Пример интеграции на GitHub**](https://github.com/Pushwoosh/web-push-notifications-sample)
### Получите Pushwoosh Web Push SDK и распакуйте его. У вас должны быть следующие файлы:
* **pushwoosh-service-worker.js**
### Поместите все эти файлы в корневой каталог вашего сайта.
### Инициализируйте SDK:
1. Подключите SDK из нашего CDN _асинхронно_.
```txt
```
2. Инициализируйте Web Push SDK и убедитесь, что инициализация поставлена в очередь до полной загрузки SDK.
```html
```
#### Веб-попапы
Добавьте `webPopups` в ваш объект `init`, чтобы включить [кампании с веб-попапами](/ru/product/messaging-channels/web-popups/#start-working-with-web-popups) на вашем сайте.
```javascript
webPopups: {
enable: true,
},
```
Кампании с веб-попапами отображают оверлеи, которые вы настраиваете в Control Panel, такие как промоакции, объявления или формы для сбора лидов. В отличие от [пользовательского попапа подписки](/ru/developer/pushwoosh-sdk/web-push-notifications/custom-subscription-popup/) (`subscribePopup`), который обрабатывает только согласие на получение веб-пушей, кампании с веб-попапами могут отображать любой настроенный вами контент.
Для настройки в Control Panel см. [Обзор веб-попапов](/ru/product/messaging-channels/web-popups/).
#### Кнопка подписки на пуши
Чтобы предложить пользователям подписаться на push-уведомления, мы рекомендуем реализовать [кнопку подписки на пуши](/ru/developer/pushwoosh-sdk/web-push-notifications/push-subscription-button/) на вашем сайте. Улучшите пользовательский опыт и получите больше подписчиков!
## Конфигурация
Чтобы завершить внедрение push-уведомлений на ваш сайт, вам необходимо настроить веб-платформы в вашей Pushwoosh Control Panel, следуя нашим пошаговым руководствам:
* [Настройка Chrome](/ru/developer/first-steps/connect-messaging-services/chrome-configuration/)
* [Настройка Firefox](/ru/developer/first-steps/connect-messaging-services/chrome-configuration/)
* [Настройка Safari](/ru/developer/first-steps/connect-messaging-services/safari-configuration/)
## Регистрация service worker в другой области
Иногда вы не можете разместить файл service worker в корневом каталоге сайта, а только в подкаталоге.
В этом случае измените конфигурацию (**шаг 4.3**), добавив параметр
`serviceWorkerUrl: “/push-notifications/pushwoosh-service-worker.js”`
где `/push-notifications/pushwoosh-service-worker.js` — это путь к файлу `pushwoosh-service-worker.js`.
## Обработчики событий
В Pushwoosh Web SDK 3.0 вы можете подписываться на определенные события для их отслеживания**,** или отписываться от событий, если отслеживание больше не требуется.
Чтобы отследить загрузку Web SDK 3.0, вызовите событие `onLoad` следующим образом:
```javascript
// Событие загрузки
Pushwoosh.push(['onLoad', (api) => {
console.log('Pushwoosh load!');
}]);
```
Чтобы отследить корректную инициализацию Web SDK, вызовите событие `onReady`:
```javascript
// Событие готовности
Pushwoosh.push((api) => {
console.log('Pushwoosh ready!');
});
```
Чтобы подписаться или отписаться от любого из событий SDK, используйте обработчики после загрузки SDK:
```javascript
Pushwoosh.push(['onLoad', (api) => {
function onEventNameHandler() {
console.log('Triggered event: event-name!');
}
// Чтобы подписаться на событие:
Pushwoosh.addEventHandler('event-name', onEventNameHandler)
// Чтобы отписаться от события:
Pushwoosh.removeEventHandler('event-name', onEventNameHandler)
}]);
```
### События SDK
#### Событие подписки (subscribe)
Выполняется после того, как пользователь соглашается на получение push-уведомлений.
```javascript
Pushwoosh.push(['onLoad', (api) => {
Pushwoosh.addEventHandler('subscribe', (payload) => {
console.log('Triggered event: subscribe');
});
}]);
```
#### Событие отписки (unsubscribe)
Выполняется после отмены регистрации устройства для получения уведомлений.
```javascript
Pushwoosh.push(['onLoad', (api) => {
Pushwoosh.addEventHandler('unsubscribe', (payload) => {
console.log('Triggered event: unsubscribe');
});
}]);
```
#### События виджета подписки
Отслеживание отображения виджета запроса на подписку.
```javascript
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');
});
}]);
```
#### События диалога разрешения уведомлений
Отслеживание отображения нативного диалога подписки.
```javascript
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);
});
}]);
```
#### События разрешений
Проверка статуса разрешения на push-уведомления при инициализации SDK; отслеживание обновления этого статуса при его изменении.
```javascript
Pushwoosh.push(['onLoad', (api) => {
// Выполняется во время инициализации SDK, если 'autoSubscribe: false' и/или если пользователь игнорирует запрос на push-уведомления.
Pushwoosh.addEventHandler('permission-default', (payload) => {
console.log('Triggered event: permission-default');
});
// Выполняется во время инициализации SDK, если уведомления заблокированы, или как только пользователь блокирует push-уведомления.
Pushwoosh.addEventHandler('permission-denied', (payload) => {
console.log('Triggered event: permission-denied');
});
// Выполняется во время инициализации SDK, если уведомления разрешены, или как только пользователь разрешает push-уведомления.
Pushwoosh.addEventHandler('permission-granted', (payload) => {
console.log('Triggered event: permission-granted');
});
}]);
```
#### Событие получения пуша (receive-push)
Отслеживание доставки пуша на устройство.
```javascript
Pushwoosh.push(['onLoad', (api) => {
// Выполняется при отображении push-уведомления.
Pushwoosh.addEventHandler('receive-push', (payload) => {
console.log('Triggered event: receive-push', payload.notification);
});
}]);
```
#### События уведомлений
Отслеживание, открыто или закрыто push-уведомление пользователем.
```javascript
Pushwoosh.push(['onLoad', (api) => {
// Выполняется, когда пользователь нажимает на уведомление.
Pushwoosh.addEventHandler('open-notification', (payload) => {
console.log('Triggered event: open-notification', payload.notification);
});
// Выполняется, когда пользователь закрывает push-уведомление.
Pushwoosh.addEventHandler('hide-notification', (payload) => {
console.log('Triggered event: hide-notification', payload.notification);
});
}]);
```
#### События Inbox
Отслеживание уведомлений, отправленных в Inbox.
```javascript
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);
});
}]);
```
#### События кастомного попапа подписки
Для получения подробной информации об обработке событий кастомного попапа подписки, пожалуйста, обратитесь к [Руководству по событиям кастомного попапа подписки](/ru/developer/pushwoosh-sdk/web-push-notifications/custom-subscription-popup/#custom-subscription-popup-events).
## API
После инициализации Web Push SDK вы можете делать следующие вызовы в Pushwoosh API. Все методы возвращают объекты [**Promise**](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global\_Objects/Promise).
```javascript
Pushwoosh.push((api) => {
// Установить теги для пользователя
api.setTags({
'Tag Name 1': 'value1',
'Tag Name 2': 'value2'
});
// Получить теги для пользователя с сервера
api.getTags();
// Зарегистрировать User ID
api.registerUser('user123');
// Зарегистрировать email пользователя
api.registerEmail('user@example.com');
// Зарегистрировать номер SMS
api.registerSmsNumber('+15551234567');
// Зарегистрировать номер WhatsApp
api.registerWhatsappNumber('+1234567890');
// Отправить Event
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
Усовершенствованный метод регистрации, который позволяет регистрировать профиль пользователя с несколькими устройствами и каналами обмена сообщениями в одном вызове API. Этот метод особенно полезен для кросс-платформенных приложений или при реализации омниканальных стратегий обмена сообщениями.
```javascript
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('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:
```javascript
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);
});
});
```
### Увеличение значения тега
Чтобы **увеличить значение** числового тега (Number Tag), используйте параметр `operation` со значением ‘increment’ следующим образом:
```javascript
Pushwoosh.push((api) => {
api.setTags({
'Tag 1': {
operation: 'increment',
value: 1
}
})
});
```
### Добавление значений тега
Чтобы **добавить новые значения** к существующему тегу-списку (List Tag), используйте параметр `operation` со значением ‘append’ следующим образом:
```javascript
Pushwoosh.push((api) => {
api.setTags({
'Tag 3': {
operation: 'append',
value: ['Value3']
}
})
});
```
### Удаление значения тега
Чтобы **удалить значение** из тега-списка (List Tag), используйте параметр `operation` со значением ‘remove’ следующим образом:
```javascript
Pushwoosh.push((api) =>{
api.setTags({
'Tag 3': {
operation: 'remove',
value: ['Value2']
}
})
});
```
## Публичные методы
**Pushwoosh.subscribe()**
Этот метод используется для запроса разрешения пользователя на push-уведомления. Если пользователь уже подписан, выполнение метода прекратится.
Если пользователь еще не подписан на пуши:
1\. Запрашивается разрешение на push-уведомления.
2\. Если пользователь разрешает уведомления, срабатывает событие `onSubscribe`.
`Pushwoosh.subscribe()` выполняется автоматически, если при инициализации SDK установлено `autoSubscribe: true`.
Вызовите этот метод, если вы выбрали ручной запрос на подписку, используя параметр `autoSubscribe: false` при инициализации:
```html
```
**Pushwoosh.unsubscribe()**
1. Выполняется метод `/unregisterDevice`.
2. Срабатывает событие `onUnsubscribe`.
```html
```
**Pushwoosh.isSubscribed()**
Проверяет, подписан ли пользователь, и возвращает флаг true/false.
```javascript
Pushwoosh.isSubscribed().then((isSubscribed) => {
console.log('isSubscribed', isSubscribed);
});
```
**Pushwoosh.getHWID()**
Возвращает Pushwoosh HWID.
```javascript
Pushwoosh.getHWID().then((hwid) => {
console.log('hwid:', hwid);
});
```
**Pushwoosh.getPushToken()**
Возвращает push-токен, если он доступен.
```javascript
Pushwoosh.getPushToken().then((pushToken) => {
console.log('pushToken:', pushToken);
});
```
**Pushwoosh.getUserId()**
Возвращает [**User ID**](/ru/developer/pushwoosh-knowledge-hub/users-userids/users-userids/), если он доступен.
```javascript
Pushwoosh.getUserId().then((userId) => {
console.log('userId:', userId);
});
```
**Pushwoosh.getParams()**
Возвращает список следующих параметров:
```javascript
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
**messagesWithNoActionPerformedCount(): Promise\**
Возвращает количество открытых сообщений.
```javascript
Pushwoosh.pwinbox.messagesWithNoActionPerformedCount()
.then((count) => {
console.log(`${count} messages opened`);
});
```
**unreadMessagesCount()**
Возвращает количество непрочитанных сообщений.
```javascript
Pushwoosh.pwinbox.unreadMessagesCount()
.then((count) => {
console.log(`${count} messages unread`);
});
```
**messagesCount(): Promise\**
Возвращает общее количество сообщений.
```javascript
Pushwoosh.pwinbox.messagesCount()
.then((count) => {
console.log(`${count} messages`);
});
```
**loadMessages(): Promise\**
Загружает список неудаленных сообщений.
```javascript
Pushwoosh.pwinbox.loadMessages()
.then(() => {
console.log('Messages have been loaded');
});
```
**readMessagesWithCodes(codes: Array\): Promise\**
Помечает сообщения как прочитанные по Inbox_Id.
```javascript
Pushwoosh.pwinbox.readMessagesWithCodes(codes)
.then(() => {
console.log('Messages have been read');
});
```
**performActionForMessageWithCode(code: string): Promise\**
Выполняет действие, назначенное сообщению, и помечает сообщение как прочитанное.
```javascript
Pushwoosh.pwinbox.performActionForMessageWithCode(code)
.then(() => {
console.log('Action has been performed');
});
```
**deleteMessagesWithCodes(codes: Array\): Promise\**
Помечает сообщения как удаленные.
```javascript
Pushwoosh.pwinbox.deleteMessagesWithCodes([code])
.then(() => {
console.log('Messages have been deleted');
});
```
**syncMessages(): Promise\**
Синхронизирует сообщения с сервером.
```javascript
Pushwoosh.pwinbox.syncMessages()
.then(() => {
console.log('Messages have been synchronized');
});
```
## Поддержка Progressive Web App
Чтобы интегрировать Pushwoosh в ваше Progressive Web Application (PWA), выполните описанные ниже шаги.
**1**. Скопируйте путь к вашему файлу Service Worker:
```javascript
if ('serviceWorker' in navigator) {
window.addEventListener('load', () => {
navigator.serviceWorker.register('/service-worker.js') // <- URL вашего service worker
});
}
```
Затем используйте параметр serviceWorkerUrl при инициализации WebSDK следующим образом:
```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',
serviceWorkerUrl: '/service-worker.js', // <- URL вашего service worker
}]);
```
WebSDK не регистрирует новый Service Worker немедленно; Service Worker регистрируется, когда это необходимо:
* когда устройство получает push-токен (при регистрации устройства или повторной подписке),
* когда push-токен удаляется (при удалении устройства из базы пользователей).
Это ускоряет загрузку ваших страниц за счет сокращения количества запросов к серверу.
Браузеры не позволяют регистрировать два разных Service Worker одновременно (подробнее: [https://github.com/w3c/ServiceWorker/issues/921](https://github.com/w3c/ServiceWorker/issues/921)), поэтому, чтобы ваше PWA работало корректно, для вашей кодовой базы и кодовой базы Pushwoosh должен быть зарегистрирован общий Service Worker.
**2**. Добавьте следующую строку в ваш Service Worker (в начало или в конец, это не имеет значения):
```javascript
importScripts('https://cdn.pushwoosh.com/webpush/v3/pushwoosh-service-worker.js' + self.location.search);
```
Таким образом, вы включаете получение и обработку push-уведомлений, отправленных через сервисы Pushwoosh, для вашего Service Worker.
## Установка через Google Tag Manager
Используйте следующий код в вашем **Google Tag Manager** для инициализации Pushwoosh SDK. Создайте пользовательский HTML-тег и вставьте код ниже. Обязательно измените ваш Pushwoosh Application Code, Safari Website ID и URL изображения уведомления по умолчанию.\
Также установите высокий приоритет **срабатывания тега** (например, 100) и настройте его запуск на **Всех страницах**. См. скриншот ниже.Скопировать
```html
```
2\. Если пользователь разрешает уведомления, срабатывает событие `onSubscribe`.
`Pushwoosh.subscribe()` выполняется автоматически, если при инициализации SDK установлено `autoSubscribe: true`.
Вызовите этот метод, если вы выбрали ручной запрос на подписку, используя параметр `autoSubscribe: false` при инициализации:
```html
```
**Pushwoosh.unsubscribe()**
1. Выполняется метод `/unregisterDevice`.
2. Срабатывает событие `onUnsubscribe`.
```html
```
**Pushwoosh.isSubscribed()**
Проверяет, подписан ли пользователь, и возвращает флаг true/false.
```javascript
Pushwoosh.isSubscribed().then((isSubscribed) => {
console.log('isSubscribed', isSubscribed);
});
```
**Pushwoosh.getHWID()**
Возвращает Pushwoosh HWID.
```javascript
Pushwoosh.getHWID().then((hwid) => {
console.log('hwid:', hwid);
});
```
**Pushwoosh.getPushToken()**
Возвращает push-токен, если он доступен.
```javascript
Pushwoosh.getPushToken().then((pushToken) => {
console.log('pushToken:', pushToken);
});
```
**Pushwoosh.getUserId()**
Возвращает [**User ID**](/ru/developer/pushwoosh-knowledge-hub/users-userids/users-userids/), если он доступен.
```javascript
Pushwoosh.getUserId().then((userId) => {
console.log('userId:', userId);
});
```
**Pushwoosh.getParams()**
Возвращает список следующих параметров:
```javascript
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
**messagesWithNoActionPerformedCount(): Promise\