Виджет подписки

Виджет подписки — это запрос и колокольчик-лаунчер, которые приглашают посетителей сайта подписаться на push-уведомления. Они настраиваются вместе в subscriptionWidget, но включаются независимо: только запрос, только колокольчик или оба сразу. Включение любого из них заменяет кнопку подписки на push-уведомления, настраиваемое всплывающее окно подписки и виджеты запроса подписки: пока включена хотя бы одна часть, ни один из этих трех старых виджетов не загружается на странице.

Посетитель, который еще не принял решение, видит приглашение запроса. Посетитель, который уже заблокировал уведомления, вместо этого видит объяснение, как их разблокировать.

Предварительные требования

Убедитесь, что на вашем сайте внедрен Pushwoosh Web SDK 3.0. Для этого следуйте нашему руководству по интеграции.

1. Включение запроса и колокольчика

Добавьте параметр subscriptionWidget в инициализацию WebSDK и установите prompt.enabled и/или launcher.enabled в значение true:

Pushwoosh.push(['init', {
  //...
  subscriptionWidget: {
    prompt: { enabled: true },
    launcher: { enabled: true },
  }
}]);

Каждое поле ниже необязательно. Если оно не указано, используется значение по умолчанию. В init-сниппете число вне допустимого диапазона молча округляется до ближайшей границы, а недопустимое значение перечисления молча заменяется значением по умолчанию — без предупреждения в консоли. Формы в Control Panel, описанные ниже, проверяют каждое поле и отказываются сохранять недопустимое значение.

2. Настройка запроса и колокольчика

Pushwoosh.push(['init', {
  //...
  subscriptionWidget: {
    prompt: {
      enabled: true,
      layout: 'card',       // 'card' | 'bar' | 'modal'
      position: 'bottom-right',
      iconUrl: 'https://url-image.png',
      borderRadius: 12,     // 0–32
      overlay: false,
    },
    launcher: {
      enabled: true,
      position: 'bottom-right', // 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
      offset: 20,           // 0–100
      width: 48,             // 16–200
      height: 48,            // 16–200
      imageUrl: 'https://url-image.png',
      background: '#4285f4',
      iconColor: '#ffffff',
    },
    display: {
      trigger: 'auto',      // 'auto' | 'launcher' | 'manual'
      delay: 5,             // seconds, 0–3600
      cappingCount: 3,      // auto-shows per visitor, 0–100, 0 = unlimited
      cappingInterval: 24,  // hours between auto-shows, 0–8760
    },
    texts: {
      title: 'Stay in the loop',
      message: 'Get notified about news and updates.',
      acceptText: 'Allow',
      declineText: 'Not now',
      closeText: 'Close',
      blockedTitle: 'Notifications are blocked',
      blockedMessage: 'Enable notifications in your browser settings to stay updated.',
      launcherLabel: 'Subscribe to notifications',
      launcherBlockedLabel: 'Notifications are blocked',
    },
    colors: {
      background: '#ffffff',
      accent: '#4285f4',
      text: '#000000',
      textSecondary: '#666666',
    },
  }
}]);

Макет и положение

prompt.layout задает форму запроса:

card — компактная карточка, закрепленная у края или угла. prompt.position принимает значения top, bottom, top-left, top-right, bottom-left или bottom-right.
bar — полоса на всю ширину страницы. prompt.position принимает только top или bottom.
modal — окно, центрированное на странице. prompt.position всегда равно center.

Перед выбором положения сверьтесь со списком выше, чтобы понять, какой макет вы установили. В init-сниппете положение, не поддерживаемое текущим макетом, молча заменяется значением по умолчанию для этого макета. Форма в Control Panel вместо этого отклоняет такую комбинацию.

Когда показывать запрос

display.trigger определяет, что открывает запрос:

auto — открывается автоматически через display.delay секунд после загрузки страницы, затем снова каждые display.cappingInterval часов, если посетитель не принял решение, до display.cappingCount раз в общей сложности (0 означает без ограничений).
launcher — никогда не открывается по таймеру. Задайте его вместе с launcher.enabled: true, чтобы запрос можно было открыть нажатием на колокольчик. Ручной API открывает запрос независимо от этой настройки и от того, включен ли колокольчик.
manual — открывается только через Pushwoosh.moduleRegistry.subscriptionWidget, описанный ниже.

display.delay, display.cappingCount и display.cappingInterval применяются только к триггеру auto.

Колокольчик-лаунчер

launcher.enabled показывает плавающий колокольчик посетителю, который еще может отреагировать на приглашение (не подписан или заблокировал уведомления), независимо от запроса и от display.trigger. Пока запрос открыт, колокольчик остается на экране. launcher.position размещает его в одном из четырех углов. launcher.offset задает отступ от краев в пикселях.

Эффект нажатия на колокольчик зависит от запроса. Если prompt.enabled равен true, нажатие переключает запрос: открывает его или закрывает, если он уже открыт. Если запрос выключен, нажатие напрямую запрашивает разрешение у браузера, так же как Pushwoosh.subscribe(), — если только посетитель уже не заблокировал уведомления: тогда нажатие ничего не делает.

launcher.width и launcher.height задают размер колокольчика в пикселях (16–200, по умолчанию 48 для каждого). launcher.imageUrl отображает картинку вместо круглой кнопки-колокольчика. launcher.background и launcher.iconColor задают заливку круглой кнопки и цвет значка. Если launcher.background не задан, по умолчанию используется акцентный цвет палитры, а launcher.iconColor — цвет значка, рассчитанный для контраста с ним.

Тексты и цвета

texts.blockedTitle, texts.blockedMessage и texts.closeText показываются вместо запроса, как только браузер сообщает, что посетитель заблокировал уведомления — texts.acceptText и texts.declineText в этом состоянии никогда не появляются. texts.launcherLabel и texts.launcherBlockedLabel — это подсказка колокольчика в каждом из состояний. Каждое текстовое поле принимает до 300 символов.

colors.accent, colors.background, colors.text и colors.textSecondary принимают hex-значение или название цвета CSS. Формы в Control Panel проверяют каждое из них, а также launcher.background и launcher.iconColor, именно так, до 64 символов. Init-сниппет принимает для colors.* любую непустую строку без проверки формата или длины. Для launcher.background и launcher.iconColor он не проверяет формат, но молча обрезает значение до 64 символов.

Управление в Control Panel

В приложении, управляемом через панель, перейдите в Settings → Configure platforms → Web. Запрос и колокольчик — это две отдельные карточки, у каждой свой значок On/Off и кнопка Configure:

Subscription invitation редактирует запрос: Invitation (макет, положение, значок), When to show (триггер, задержка, ограничение частоты), Texts и Colors.
Subscription bell редактирует лаунчер: положение, URL изображения, ширину/высоту, цвет фона и значка, а также собственные тексты подсказок.

Кнопка Configure в каждой карточке открывает живой предпросмотр рядом с формой. Пока собственный переключатель карточки выключен, предпросмотр ничего не рисует. После включения выпадающий список над предпросмотром переключает его между приглашением для не принявшего решение посетителя и объяснением для заблокировавшего. Сохранение карточки заменяет только свою половину копии конфигурации виджета в панели — настройки другой карточки и init-сниппет WebSDK на вашем сайте не затрагиваются.

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

3. Управление запросом из кода

После загрузки бандла виджета он публикует API по адресу Pushwoosh.moduleRegistry.subscriptionWidget:

Pushwoosh.moduleRegistry.subscriptionWidget.show();          // Opens the prompt
Pushwoosh.moduleRegistry.subscriptionWidget.hide();          // Closes the prompt
Pushwoosh.moduleRegistry.subscriptionWidget.toggle();        // Toggles the current state
Pushwoosh.moduleRegistry.subscriptionWidget.toggle(true);    // Opens the prompt
Pushwoosh.moduleRegistry.subscriptionWidget.isVisible();     // Returns whether the prompt is open

show() и toggle() не имеют эффекта, пока prompt.enabled равен false, а также для посетителя, который уже подписан. Открытие запроса вызывает событие show-subscription-widget. Его закрытие вызывает событие hide-subscription-widget:

Pushwoosh.addEventHandler('show-subscription-widget', function() {
  console.log('Triggered event: show-subscription-widget');
});

Pushwoosh.addEventHandler('hide-subscription-widget', function() {
  console.log('Triggered event: hide-subscription-widget');
});

Переход со старых виджетов

Кнопка подписки на push-уведомления, настраиваемое всплывающее окно подписки и запрос подписки продолжают работать так, как описано на их собственных страницах, пока subscriptionWidget.prompt.enabled и subscriptionWidget.launcher.enabled на сайте оба не установлены или равны false. Включение любого из них останавливает загрузку всех трех виджетов — как для приложения с настройкой через сниппет, так и для приложения, управляемого через панель.

Ранняя версия виджета использовала единый переключатель верхнего уровня subscriptionWidget.enable вместо отдельных prompt.enabled/launcher.enabled. Такой формат больше не читается. Сниппет, который по-прежнему задает только enable: true, теперь полностью выключает виджет: ни запрос, ни колокольчик ничего не рисуют, WebSDK выводит в консоль подсказку с названиями двух полей, которые нужно задать вместо него, а три старых виджета загружаются так, как если бы subscriptionWidget не был задан. Переключение приложения, управляемого через панель, на новый виджет также не переносит настройки того старого виджета, который он заменяет, — каждая карточка стартует со своих собственных значений по умолчанию.