# Виджет подписки **Виджет подписки** — это колокольчик-лаунчер и запрос, приглашающий посетителей сайта подписаться на push-уведомления. Он заменяет собой [кнопку подписки на push-уведомления](/ru/developer/pushwoosh-sdk/web-push-notifications/push-subscription-button/), [настраиваемое всплывающее окно подписки](/ru/developer/pushwoosh-sdk/web-push-notifications/custom-subscription-popup/) и виджеты [запроса подписки](/ru/developer/guides/messaging-channels/subscription-prompt/) — все в одном компоненте. Пока он включен, ни один из этих трех виджетов не загружается на странице, поэтому посетители никогда не видят два конкурирующих запроса одновременно. Посетитель, который еще не принял решение, видит запрос. Посетитель, который уже заблокировал уведомления, вместо этого видит объяснение, как их разблокировать. ## Предварительные требования Убедитесь, что на вашем сайте внедрен Pushwoosh Web SDK 3.0. Для этого следуйте нашему [руководству по интеграции](/ru/developer/pushwoosh-sdk/web-push-notifications/web-push-sdk-30/#integration). ## 1. Включение виджета Добавьте параметр `subscriptionWidget` в инициализацию WebSDK и установите `enable` в значение `true`: ```javascript Pushwoosh.push(['init', { //... subscriptionWidget: { enable: true, } }]); ``` Каждое поле ниже необязательно. Если поле не указано, используется значение по умолчанию. В init-сниппете число вне допустимого диапазона молча округляется до ближайшей границы, а недопустимое значение перечисления молча заменяется значением по умолчанию — без предупреждения в консоли. Форма в Control Panel, описанная ниже, напротив, полностью отклоняет недопустимое значение и отказывается его сохранять. ## 2. Настройка запроса ```javascript Pushwoosh.push(['init', { //... subscriptionWidget: { enable: true, prompt: { 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 size: 48, // 32–80 }, 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`** — открывается только когда посетитель нажимает на колокольчик. - **`manual`** — открывается только через `Pushwoosh.moduleRegistry.subscriptionWidget`, описанный ниже. `display.delay`, `display.cappingCount` и `display.cappingInterval` применяются только к триггеру `auto`. ### Колокольчик-лаунчер `launcher.enabled` показывает плавающий колокольчик, пока посетитель не подписан, независимо от `display.trigger` — даже при `trigger: 'auto'` колокольчик остается видимым, чтобы посетитель мог снова открыть запрос после его закрытия. `launcher.position` размещает его в одном из четырех углов. `launcher.offset` (отступ от краев в пикселях) и `launcher.size` (диаметр колокольчика в пикселях) точно настраивают расположение. ### Тексты и цвета `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 проверяет каждое поле именно так, до 64 символов. Init-сниппет принимает для этих полей любую непустую строку без проверки формата или длины. ## Управление в Control Panel В приложении, управляемом через панель, перейдите в **Settings → Configure platforms → Web** и откройте карточку **Subscription widget**. Значок на карточке показывает, включен виджет (**On**) или выключен (**Off**). Нажмите **Configure**, чтобы редактировать те же поля, что описаны выше, сгруппированные как **Prompt**, **When to show**, **Bell**, **Texts** и **Colors**, рядом с живым предпросмотром, показывающим состояние как для не принявшего решение, так и для заблокировавшего посетителя. Сохранение заменяет копию конфигурации виджета в панели. Init-сниппет WebSDK на вашем сайте при этом не затрагивается. Пока приложение управляется через панель, значения, сохраненные в этой карточке, переопределяют те же ключи в init-сниппете сайта. Перевод сайта на конфигурацию через панель — это переключатель в панели, не требующий изменений кода на сайте. ## 3. Управление виджетом из кода После загрузки бандла виджета он публикует API по адресу `Pushwoosh.moduleRegistry.subscriptionWidget`: ```javascript 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()` не имеет эффекта для посетителя, который уже подписан. Открытие запроса вызывает событие `show-subscription-widget`. Его закрытие вызывает событие `hide-subscription-widget`: ```javascript 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.enable` не установлен или равен `false`. Установка значения `true` останавливает загрузку всех трех виджетов — как для приложения с настройкой через сниппет, так и для приложения, управляемого через панель.