================================================================================
  WEB PUSH УВЕДОМЛЕНИЯ для NGCMS
================================================================================
Версия: 1.0.7
Автор: NGCMS Team
Требования: PHP 8.0+, HTTPS (библиотека встроена)
================================================================================
  ОПИСАНИЕ
================================================================================
Плагин позволяет посетителям сайта подписаться на push-уведомления и получать
оповещения о новых материалах прямо в браузере. Использует стандарт Web Push
API и протокол VAPID для безопасной доставки уведомлений.
Возможности:
  ✓ Подписка/отписка одним кликом
  ✓ Автоматические уведомления при публикации новостей
  ✓ Интеграция с плагином mailing (дублирование по email)
  ✓ Ручная отправка уведомлений через API
  ✓ Шаблонизация через Twig
  ✓ Поддержка всех современных браузеров
  ✓ Отслеживание неактивных подписок
================================================================================
  УСТАНОВКА
================================================================================
1. АКТИВАЦИЯ ПЛАГИНА:
   - Войдите в админ-панель NGCMS
   - Перейдите в раздел "Плагины"
   - Найдите "Web Push Уведомления" и активируйте
   - При установке автоматически создастся таблица webpush_subscriptions
2. НАСТРОЙКА SERVICE WORKER:
  Файл webpush-sw.js автоматически копируется в корень сайта при установке/обновлении.
  Если по какой-то причине он отсутствует, создайте вручную:
  - Windows (PowerShell): copy engine/plugins/webpush/sw/webpush-sw.js webpush-sw.js
  - Linux/macOS:         cp engine/plugins/webpush/sw/webpush-sw.js webpush-sw.js
3. ДОБАВЛЕНИЕ КНОПКИ В ШАБЛОН:
   Откройте templates/ваш_шаблон/main.tpl
   Добавьте перед закрывающим </body>:
   {% if webpush is defined %}{{ webpush|raw }}{% endif %}

4. ГЕНЕРАЦИЯ VAPID КЛЮЧЕЙ:
   Откройте настройки плагина в админ-панели:
   Плагины -> Web Push Уведомления -> Настройки

   В разделе "VAPID настройки" нажмите кнопку:
   🔑 Сгенерировать VAPID ключи

   Ключи автоматически заполнятся в поля выше.
   Не забудьте нажать "СОХРАНИТЬ ИЗМЕНЕНИЯ" внизу страницы!
================================================================================
  ИСПОЛЬЗОВАНИЕ
================================================================================
АВТОМАТИЧЕСКАЯ ОТПРАВКА:
  При публикации новости с главной страницей автоматически отправляется
  уведомление всем подписчикам. Заголовок берётся из названия новости,
  текст - из короткого описания.
РУЧНАЯ ОТПРАВКА:
  GET-запрос:
  https://сайт.ru/engine/plugins/webpush/send.php?secret=КЛЮЧ&title=Заголовок&body=Текст&url=/link
  POST-запрос (JSON):
  {
    "secret": "ВАШ_СЕКРЕТ",
    "title": "Заголовок уведомления",
    "body": "Текст уведомления",
    "url": "/news/123",
    "icon": "/uploads/icon.png",
    "badge": "/uploads/badge.png"
  }
  Параметры:
    - secret   (обязательно) - секретный ключ из настроек
    - title    (опционально) - заголовок, по умолчанию "Уведомление"
    - body     (опционально) - текст уведомления
    - url      (опционально) - ссылка при клике, по умолчанию "/"
    - icon     (опционально) - URL иконки
    - badge    (опционально) - URL значка
ИНТЕГРАЦИЯ В КОД:
  <?php
  $secret = extra_get_param('webpush', 'send_secret');
  $url = "https://сайт.ru/engine/plugins/webpush/send.php";
  $data = [
    'secret' => $secret,
    'title' => 'Новая статья',
    'body' => 'Опубликован новый материал',
    'url' => '/news/' . $newsId
  ];
  $ch = curl_init($url);
  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  $result = curl_exec($ch);
  curl_close($ch);
  ?>
================================================================================
  НАСТРОЙКИ ПЛАГИНА
================================================================================
Доступны в админ-панели -> Плагины -> Web Push Уведомления -> Настройки:
  • Включить плагин - активация/деактивация
  • Показывать кнопку подписки - отображение кнопки на сайте
  • Автоотправка при публикации новости - автоматическое уведомление
  • Интеграция с плагином Mailing - дублирование по email (v1.0.7+)
  • VAPID Subject - mailto: адрес администратора
  • VAPID Public Key - публичный ключ (генерируется кнопкой)
  • VAPID Private Key - приватный ключ (генерируется кнопкой)
  • Иконка по умолчанию - путь к PNG иконке (192x192 минимум)
  • Значок по умолчанию - путь к PNG значку (96x96)

ИНТЕГРАЦИЯ С MAILING (v1.0.7+):
  При включенной опции "Интеграция с плагином Mailing":
  1. При публикации новости отправляется:
     - Push-уведомление всем подписчикам webpush
     - Email-уведомление всем подписчикам mailing
  2. Плагин mailing должен быть активен
  3. В настройках отображается статус плагина mailing
  4. Результаты интеграции логируются
  • Текст кнопки - текст на кнопке подписки
  • Показывать кнопку - включение/отключение кнопки
  • Секретный ключ - ключ для API отправки (генерируется автоматически)
================================================================================
  СТРУКТУРА ФАЙЛОВ
================================================================================
engine/plugins/webpush/
├── version               # Описание плагина
├── readme.txt           # Этот файл
├── install.php          # Скрипт установки
├── uninstall.php        # Скрипт удаления
├── config.php           # Админ-панель настроек
├── webpush.php          # Основная логика плагина
├── endpoint.php         # API для подписок (публичный)
├── send.php            # API для отправки (защищенный)
├── composer.json       # Composer конфигурация
├── lang/               # Переводы
│   └── russian/
│       └── main.ini
├── tpl/                # Twig шаблоны
│   └── webpush.tpl
├── js/                 # JavaScript
│   └── webpush.js
├── sw/                 # Service Worker
│   └── webpush-sw.js
└── lib/                # Библиотеки
    └── vendor/         # Composer пакеты (создаётся при установке)
================================================================================
  БАЗА ДАННЫХ
================================================================================
Таблица: prefix_webpush_subscriptions
Поля:
  - id          INT AUTO_INCREMENT - ID записи
  - hash        VARCHAR(64)        - SHA256 хеш endpoint (уникальный)
  - endpoint    TEXT              - URL для отправки уведомлений
  - p256dh      VARCHAR(255)      - Публичный ключ клиента
  - auth        VARCHAR(255)      - Токен аутентификации
  - user_agent  VARCHAR(255)      - User-Agent браузера
  - ip          VARCHAR(45)       - IP адрес подписчика
  - created     INT              - Timestamp создания
  - updated     INT              - Timestamp обновления
================================================================================
  ТРЕБОВАНИЯ
================================================================================
Сервер:
  • PHP 8.0 или выше
  • HTTPS (обязательно для Web Push API)
  • MySQL/MariaDB
  • Библиотека minishlink/web-push встроена в плагин (lib/vendor/)
Браузеры (поддержка):
  • Chrome 42+
  • Firefox 44+
  • Edge 17+
  • Safari 16+
  • Opera 37+
Зависимости:
  • minishlink/web-push ^8.0 (встроена в плагин)
  • NGCMS Build 23b3116+
================================================================================
  УСТРАНЕНИЕ НЕПОЛАДОК
================================================================================
Проблема: "Web Push library not found"
Решение: Убедитесь, что папка engine/plugins/webpush/lib/vendor/ существует и содержит библиотеку
Проблема: "ServiceWorker не регистрируется"
Решение: Проверьте, что webpush-sw.js доступен в корне сайта и сайт работает по HTTPS
Проблема: "VAPID keys are empty"
Решение: В настройках плагина нажмите кнопку "🔑 Сгенерировать VAPID ключи" и сохраните изменения
Проблема: "Кнопка генерации не работает"
Решение: Откройте консоль браузера (F12) и проверьте ошибки JavaScript. Очистите кеш: engine/cache/
Проблема: "Уведомления не приходят"
Решение:
  - Проверьте, что браузер выдал разрешение на уведомления
  - Убедитесь, что есть активные подписки в таблице
  - Проверьте, что VAPID ключи сгенерированы
  - Убедитесь, что секретный ключ правильный
Проблема: "Call to undefined method NGLegacyDB::get_array()"
Решение: Обновите NGCMS до последней версии или используйте версию плагина 1.0.1+
================================================================================
  БЕЗОПАСНОСТЬ
================================================================================
  • Секретный ключ хранится в конфигурации - НЕ публикуйте его
  • API отправки защищен проверкой секретного ключа
  • Подписки хранятся с хешем endpoint для предотвращения дубликатов
  • Service Worker работает только по HTTPS
  • Автоматическое удаление неактивных подписок
================================================================================
  ПОДДЕРЖКА
================================================================================
Сайт: https://ngcms.org
Форум: https://forum.ngcms.org
GitHub: https://github.com/vpngen/ngcms
================================================================================
  ЛИЦЕНЗИЯ
================================================================================
MIT License - свободное использование с сохранением копирайта
Copyright (c) 2025 NGCMS Team
================================================================================
  CHANGELOG
================================================================================
v1.0.7 (2026-01-17)
  • Добавлена интеграция с плагином mailing
  • Опция дублирования уведомлений по email
  • Динамическая проверка активности плагина mailing
  • Логирование результатов интеграции

v1.0.6 (2026-01-17)
  • Добавлена автоматическая отправка уведомлений при публикации
  • Новая опция "Автоотправка при публикации новости"
  • Фильтр WebPushNewsFilter для обработки новых новостей
  • Проверка временного окна публикации (5 минут)

v1.0.5 (2026-01-17)
  • Добавлена кнопка генерации VAPID ключей в настройках
  • Автоматическое заполнение полей ключей одним кликом
  • Toast-уведомления о результате генерации
  • Библиотека полностью встроена в плагин (lib/vendor/)
  • Убрана зависимость от глобального Composer
v1.0.4 (2026-01-17)
  • Публичный ключ передается через data-атрибут в HTML
  • Исправлены синтаксические ошибки в endpoint.php
  • Добавлен скрипт диагностики check_config.php
  • Улучшено логирование операций
v1.0.3 (2026-01-17)
  • Переход на Twig вместо устаревшего $tpl
  • Использование pluginGetVariable() вместо extra_get_param()
  • Интеграция с ng-helpers (logger, get_ip, is_mobile)
  • Добавлен вывод {{ webpush|raw }} в main.tpl
v1.0.2 (2026-01-04)
  • Автокопирование/обновление webpush-sw.js при установке/обновлении
  • Удаление webpush-sw.js при деинсталляции
v1.0.1 (2025-12-16)
  • Исправлена работа с NGLegacyDB
  • Прямое подключение PDO в endpoint.php и send.php
  • Оптимизация загрузки без core.php
  • Поддержка PHP 8.3+
v1.0.0 (2025-12-16)
  • Первый релиз
  • Базовая функциональность Web Push
  • Интеграция с NGCMS
  • Поддержка Twig
  • VAPID протокол
================================================================================
