База знаний GetMyBot

Пуш в браузере (Web Push)

Как включить уведомления в браузере посетителя и отправить тест. Разрешение пользователя, файл на сайте и ключи VAPID.

На этой странице

Web Push показывает уведомление средствами браузера. Сначала посетитель вашего сайта с виджетом должен разрешить такие уведомления. Это отдельная возможность от колокольчика и уведомлений оператору в кабинете.

Шаг 1. Установите сервис-воркер на своём домене

Попросите администратора сайта разместить файл mybot-sw.js. Без него браузер не сможет принять и показать уведомление.

Сервис-воркер представляет собой небольшой скрипт, который браузер использует для получения уведомлений. Он должен находиться на вашем сайте: скрипт с домена GetMyBot не может управлять уведомлениями вашего домена. Адрес сайта с протоколом, но без пути к странице называется origin, например https://example.com.

  1. Откройте в кабинете «Виджет» → Web Push и скачайте файл mybot-sw.js.

  2. Разместите его так, чтобы он отдавался из корня каждого origin, где работает виджет, ровно по такому пути:

    https://example.com/mybot-sw.js
    https://shop.example.com/mybot-sw.js
    

    В настройках Web Push перечислены ожидаемые адреса для каждой разрешённой ссылки уведомления, так что их можно открыть в браузере и убедиться, что скрипт отдаётся.

  3. Откройте адрес файла в браузере. Он должен отдавать JavaScript по HTTPS, а не страницу сайта. Если вместо файла открывается страница, ответ 404 или перенаправление на другой адрес, подписка не заработает. На одностраничных сайтах и сайтах с CDN отдельно проверьте, что по этому пути не возвращается index.html.

  4. После обновления платформы перезалейте файл так же, как любой другой статический ресурс. Переустанавливать его после изменения настроек Web Push или ротации ключей не нужно.

Путь важен: виджет регистрирует или переиспользует только воркер по пути /mybot-sw.js. Два публичных параметра маршрутизации (mb_key, mb_api) он подставляет сам, добавлять их вручную не нужно.

Если вы регистрируете воркер сами

Когда нужно управлять регистрацией самостоятельно или ограничить адреса, которые может открыть клик по уведомлению, зарегистрируйте файл своим кодом:

navigator.serviceWorker.register("/mybot-sw.js?nav=https://shop.example.com");

В параметре nav можно перечислить через запятую не более 8 точных HTTPS-origin. Воркер проверяет цель клика по своему списку и по собственному origin независимо от серверного списка из шага 2. Найдя такую регистрацию, виджет сохранит ваше значение nav, а не заменит его.

Если на сайте уже есть свой сервис-воркер

Виджет никогда не заменяет чужой сервис-воркер: замена сломала бы ваш сайт, а подписка через чужой воркер не установила бы обработчики пуша и клика. Если страницей уже управляет другой воркер, попытка подписки просто завершится как «недоступно». Разместите mybot-sw.js на сайте, где своего воркера в корневой области нет, или напишите в поддержку, прежде чем совмещать два воркера.

Шаг 2. Включите Web Push для бота

Web Push настраивается на экране «Виджет», рядом с остальным веб-каналом. Обязательных поля два:

  • Контакт VAPID: адрес mailto: или HTTPS-ссылка, по которым пуш-сервисы сообщат вам о проблемах с доставкой, например mailto:help@example.com.
  • Разрешённые ссылки уведомлений: по одному HTTPS-origin в строке. Клик по уведомлению может открыть только относительный адрес на вашем сайте или один из этих точных origin. Это обязательный ввод, а не необязательная мера защиты: уведомление со ссылкой куда-то ещё отклоняется до отправки.

При первом сохранении сервер генерирует пару ключей VAPID. В настройках виден публичный ключ, который получает браузер. Приватный ключ никогда не покидает сервер и не возвращается ни одним методом API.

Тихие часы (см. ниже) есть в API, но поля на этом экране пока нет.

Шаг 3. Соберите согласия посетителей

Посетитель должен сам разрешить уведомления. Простая загрузка страницы не подписывает его:

  • Запрос разрешения браузера открывается только после явного клика посетителя по кнопке уведомлений в виджете.
  • Тот, кто ни разу не нажимал, не увидит ошибку: если браузер не поддерживает пуш или разрешение уже отклонено, элемент просто скрыт до первой попытки.
  • Загрузка виджета лишь обновляет уже выданное согласие. Она не может ни показать запрос, ни установить воркер, ни создать новую подписку.
  • Отказ сохраняется надолго и переживает перезагрузку страницы, даже если браузер держит свой объект подписки живым.

Оба действия доступны и вашему коду на странице после загрузки виджета:

await window.mybot.push.subscribe();   // покажет запрос и зарегистрирует подписку
await window.mybot.push.unsubscribe(); // отзовёт её на сервере и отпишет браузер

У подписки есть статус: subscribed (активна), revoked (посетитель отписался) или expired (адрес для доставки больше не работает). В кабинете и API видны тип браузера, язык, часовой пояс, статус и даты. Адрес для доставки и ключи шифрования хранятся на сервере зашифрованными. После записи они не показываются владельцу и не возвращаются через API или MCP.

Отправка

Раздел тестового уведомления отправляет одно сообщение в браузер, который подписался последним. Для этого нужны сразу три вещи:

  • включённый Web Push для бота;
  • хотя бы одна подписка в статусе subscribed;
  • один опубликованный документ типа Push в Контент-студии. Тестовая отправка ссылается на конкретную опубликованную версию: так же, как поп-ап или кампания.

После запуска теста кабинет сразу получает номер сообщения, а доставка продолжается в фоне. Выбор аудитории, расписание и остановка отправки пока не доступны ни на одном экране.

Ограничения содержимого уведомления

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

ПолеОграничение
titleобязательно, 1-120 символов
bodyобязательно, 1-512 символов
tagнеобязательно, ≤128 символов
actionsне более 2; идентификатор и подпись каждого действия 1-64 символа, без повторов
icon_url, image_urlтолько HTTPS, без userinfo и якоря
navigationотносительный путь, начинающийся с /, либо один из точно разрешённых origin
dataтолько ключи action, campaign_id, content_id, experiment_id, message_id; каждое значение ≤256 символов
собранная полезная нагрузкане более 3 КиБ целиком

Значение data отклоняется, если содержит bearer , secret, password, token= или знак @. Так в уведомление нельзя передать значение профиля или токен доступа. Полезная нагрузка с собственной receipt_signature тоже отклоняется: служебное значение подставляет сервер в момент доставки.

И сервер, и воркер считают ссылки вида //host/path и ссылки с обратным слэшем чужим origin, а не относительным путём.

Тихие часы

Тихие часы задают повторяющиеся локальные интервалы, в которые доставка откладывается, а не отменяется. Сообщение уйдёт в первый разрешённый момент. Время считается по часовому поясу получателя, записанному вместе с подпиской; запасной вариант: часовой пояс бота. Если конец интервала раньше начала, интервал продолжается через полночь. Момент, попавший в «дыру» перевода часов, сдвигается вперёд до существующего времени.

Тихие часы входят в конфигурацию Web Push и задаются через REST API (поле quiet_hours), но редактора в кабинете для них пока нет.

Доставка, повторы и квитанции

  • Сообщение забирает фоновый обработчик, берёт его в аренду на время доставки и повторяет попытки не более 8 раз и не дольше 24 часов: что наступит раньше.
  • Ответ 429 от пуш-сервиса повторяется по его Retry-After с потолком в 24 часа. Таймауты и ответы 5xx повторяются с разбросом задержки. Любой другой ответ 4xx терминальный.
  • Ответ 404 или 410 означает, что подписка браузера исчезла: она помечается как expired и больше не повторяется.
  • Сервис-воркер возвращает две квитанции: click, когда посетитель открыл уведомление, и close, когда он его закрыл. Каждая подписана и привязана к одному сообщению и одной подписке, поэтому её нельзя подделать или переиспользовать для другого сообщения.
  • Отчёт на экране настроек считает подписки по статусам и открытия уведомлений. Внутри фиксируются факты accepted, sent, failed, expired, clicked и closed; они же попадают в ленту событий клиента в разделе «Люди».

Тела ответов пуш-сервиса не сохраняются: у неудачной доставки остаётся только код причины из закрытого списка.

Ротация ключей VAPID

Смена ключей VAPID отключает все текущие подписки. Поэтому кабинет отдельно покажет число затронутых браузеров и попросит подтвердить действие. Технически первый запрос возвращает 409 с числом активных подписок. После подтверждения создаётся новая пара ключей, а старые подписки становятся недействительными. Каждому посетителю придётся разрешить уведомления заново: подписка браузера привязана к прежнему ключу.

Виджет это тоже учитывает: подписку, созданную со старым ключом, он выбрасывает и создаёт заново при следующем явном согласии посетителя, а не хранит как мёртвый груз.

Границы безопасности

Пригодится, когда спросит служба безопасности:

  • MyBot отправляет только на публичный HTTPS-адрес на порту 443. Loopback, приватные, link-local, multicast и адреса CGNAT отклоняются, а если имя резолвится в несколько адресов, публичными должны быть все.
  • Доменное имя проверяется заново при каждой доставке, а соединение устанавливается только с проверенным адресом. Перенаправления не выполняются, размер ответа ограничен.
  • Повторные адреса подписок распознаются по отпечатку в пределах аккаунта. Поэтому один бот не может узнать, подписан ли браузер на другого бота.
  • Браузерные маршруты живут вне поверхности /api, в зоне доверия виджета: каждый заново проверяет подписанный ключ виджета, сессию виджета и точный origin страницы и расходует общий с виджетом лимит запросов.

Данные и хранение

Браузерные подписки и сообщения относятся к категории хранения push со сроком по умолчанию 180 дней. Они участвуют в объединении подписчиков, выгрузке и удалении персональных данных наравне с остальными клиентскими данными.

Поддержка браузеров и диагностика

Поддержку определяет браузер: одновременно нужны уведомления, сервис-воркеры и Push API. Актуальные версии Chrome, Edge и Firefox на компьютере и на Android подходят. В iOS Safari даёт веб-пуш только сайту, который посетитель добавил на домашний экран.

Если ничего не приходит:

  1. Откройте https://ваш-сайт/mybot-sw.js в браузере и убедитесь, что отдаётся скрипт, а не 404, редирект или HTML-страница.
  2. Проверьте, что origin страницы сохранён в разрешённых origin виджета, а ссылка уведомления ведёт на разрешённую ссылку.
  3. Убедитесь, что браузер посетителя действительно выдал разрешение и что страницей не управляет другой сервис-воркер.
  4. Перепроверьте после ротации ключей: подписаться заново должны все.
  5. Если тестовая отправка недоступна, не хватает либо подписанного браузера, либо опубликованного документа типа Push.

API и MCP

Маршруты управления доступны по личному токену: см. REST API и токены. Для чтения нужны скоуп web_push:read и право web_push.read на бота. Для изменения нужны скоуп web_push:write и право web_push.write; включение дополнительно требует integrations.secrets. В MCP доступны четыре инструмента только на чтение, включая список подписок: см. MCP.

Что дальше