Перейти к основному содержимому

Интеграция Web-Push в веб-приложение

Обновлено: 30 октября 2025

Шаг 1. Подготовка к интеграции​

Перед подключением виджета подготовьте следующие данные и файлы.

Домен сайта appPackage​

Доменное имя сайта, к которому подключается виджет, без протокола.

Например, example.com.

VAPID-ключи​

Для работы виджета необходима пара VAPID-ключей. Публичный ключ используется при инициализации виджета, приватный хранится на платформе.

подсказка

Чтобы завести новое веб-приложение на Push-платформе, обратитесь в службу поддержки edna. Укажите в письме значения параметров appPackage, а также тип среды — тестовая или производственная.

Если у вас есть доступ к консоли Управление Push, зарегистрируйте приложение и сгенерируйте VAPID-ключи самостоятельно.

File IconНастройка приложения в консоли edna

Идентификатор providerUid​

Параметр providerUid генерируется виджетом автоматически. Задавать его вручную не требуется.

Сборки виджета и сервис-воркера​

Выберите сборку в зависимости от используемой Push-платформы:

к сведению

Сборки в каталоге push-web-widget предназначены для производственной Push-платформы, в каталоге push-web-widget-demo — для тестовой. Выберите сборку 2.4 с наибольшим номером версии.

Шаг 2. Подключение виджета и сервис-воркера​

Разместите файлы виджета и сервис-воркера в проекте. Подключите виджет с помощью скрипта:

<script defer src="edna-web-widget.js"></script>

Если сервис-воркер размещён не в корневом каталоге сайта, укажите путь к нему в параметре ednaWorkerPath в localStorage.

Шаг 3. Настройка параметров виджета​

Перед инициализацией виджета задайте в localStorage следующие параметры:

ПараметрОписание
appVersionВерсия сборки сайта, используемая для анализа доставки сообщений на стороне edna.
appPackageДомен сайта, к которому подключается виджет, без протокола. Например, example.com.
vapid_keyПубличный VAPID-ключ, полученный при регистрации веб-приложения.

Шаг 4. Запрос разрешения на уведомления​

warning

Перед инициализацией виджета необходимо получить разрешение пользователя на показ push-уведомлений.

Если пользователь запретил уведомления, инициализация без разрешения приводит к ошибке PUSH_PERMISSION_DENIED. В этом случае покажите пользователю инструкцию по включению уведомлений.

Пример запроса разрешения в Chrome на десктопном (слева) и мобильном (справа) устройствах:

alt text

Рекомендуется предварительно показывать всплывающее окно с описанием цели запроса и кнопками подтверждения и отклонения. Это поможет объяснить пользователю пользу уведомлений. Пример такого окна:

alt text

Если пользователь ранее запретил уведомления, повторный запрос разрешения блокируется. Вместо него виджет показывает инструкцию по включению уведомлений.

  • На десктопе: откройте настройки сайта, нажав на значок слева от адресной строки браузера.
  • На мобильном устройстве: перейдите в настройки браузера и разрешите уведомления для сайта.

Пример настройки уведомлений на десктопном устройстве:

alt text

Сценарий запроса разрешения можно создать самостоятельно или использовать метод checkPermitAndAsk().

(Опционально) Настройка всплывающих окон​

По умолчанию виджет использует собственные всплывающие окна:

  • showAskingPopup() — для запроса разрешения и объяснения его цели;
  • showPermissionDeniedPopup() — для отображения инструкции, если пользователь ранее запретил уведомления.

Можно изменить внешний вид окон, переопределив эти методы в отдельном JS-файле.

Пример переопределения вида всплывающих окон
//Проверьте получение разрешения
const requestNotificationPermission = () => window.Notification.requestPermission();
//Опишите поведение при нажатии на кнопки отказа/согласия получения уведомлений
denyButton.addEventListener('click', () => {
...
window.ednaWidget.Emitter.dispatch('onError', {
errorCode: ERRORS.PUSH_PERMISSION_DENIED,
});
});
applyButton.addEventListener('click', () => {
...
preInit();
});
};
//Опишите поведение при наличии/отсутствии разрешения
const preInit = () => {
requestNotificationPermission().then((permission) => {
if (permission !== 'granted') {
window.ednaWidget.publicMethods.showPermissionDeniedPopup();
window.ednaWidget.Emitter.dispatch('onError', {
errorCode: ERRORS.PUSH_PERMISSION_DENIED,
});
}
});
};
const newshowAskingPopup = () => {
//Новое окно запроса на показ уведомлений
};
const newshowPermissionDeniedPopup = () => {
//Новое информационное окно при отказе от получения уведомлений
};
// Переопределите методы виджета
window.ednaWidget.publicMethods.showAskingPopup = newshowAskingPopup;
window.ednaWidget.publicMethods.showPermissionDeniedPopup =
newshowPermissionDeniedPopup;

Шаг 5. Инициализация виджета​

При вызове метода инициализации виджета в него передается сгенерированный ранее Vapid-ключ.

window.ednaWidget.publicMethods.init(vapidKey: string): void

Виджет выполнит регистрацию в push-облаке и на Push-платформе. В случае успеха будет передано событие onDeviceAddressChanged с адресом мобильного устройства deviceAddress. Тогда станет доступна отправка push-сообщений на это мобильное устройство.

Шаг 6. Обработка событий виджета​

Событие onDeviceAddressChanged вызывается при изменении deviceAddress — уникального идентификатора устройства на push-сервере. По данному идентификатору производится отправка уведомлений через push-сервис edna. Поэтому необходимо передать deviceAddress в шлюз edna Prisma для привязки к пользователю и дальнейшей отправки сообщений.

File IconОписание методов и настроек

Шаг 7. Настройка отображения уведомлений​

Push-уведомление автоматически отображается на устройстве пользователя. Управлять отображением можно с помощью набора дополнительных параметров, передаваемых вместе с уведомлением.

Параметры, обрабатываемые виджетом:

ПараметрОписание
titleЗаголовок уведомления.
iconURL иконки уведомления. Рекомендуемое соотношение сторон — 1:1.
bodyТекст уведомления.
imageURL изображения для расширенного уведомления. Рекомендуемое соотношение сторон — 2:1. На большинстве устройств изображение обрезается, если его пропорции отличаются от рекомендуемых. При использовании кнопок изображение может дополнительно обрезаться по высоте.
actionsСтрока с массивом кнопок уведомления и URL, которые используются при нажатии на кнопки.
deeplinkСсылка, которая открывается при нажатии на уведомление.
fullMessageДополнительное содержимое длинного push-уведомления.
подсказка

Все параметры необязательны. Если параметр не передан, эта возможность уведомления не используется. Доступность отдельных возможностей зависит от браузера и платформы.

File IconПоддержка push-уведомлений в браузерах

Пример передачи параметров сообщения​

{
"title": "Заголовок",
"icon": "https://example.com/logo.png",
"body": "Текст уведомления",
"image": "https://example.com/picture.png",
"deeplink": "https://example.com/deeplink",
"actions": "[{\"title\":\"Кнопка 1\",\"action\":\"https://example.com/btn1\"},{\"title\":\"Кнопка 2\",\"action\":\"https://example.com/btn2\"}]"
}

Ручная регистрация сервис-воркера​

подсказка

По умолчанию виджет самостоятельно регистрирует сервис-воркер. Ручная регистрация нужна только в случаях, когда приложение должно управлять этим процессом самостоятельно.

Параметр isWorkerManualRegistration в localStorage позволяет изменять тип регистрации сервис-воркера. По умолчанию, если isWorkerManualRegistration не указан или имеет значение false — виджет автоматически регистрирует сервис-воркер в ходе инициализации.

Чтобы зарегистрировать сервис-воркер вручную, пропишите параметр isWorkerManualRegistration со значением true. В этом случае нужно зарегистрировать сервис-воркер до инициализации виджета.

При ручной регистрации виджет будет по умолчанию искать активный сервис-воркер в глобальном скоупе (/). Если у вашего сервис-воркера иной скоуп, укажите его в параметре customWorkerScope.