Top.Mail.Ru
  • CMS «ГИРВАС»

    Гибкая и бесплатная система управления содержимым, позволяющая создать сайт любого направления.

    С нами проще!

  • Абсолютно бесплатно

    Хватит использовать старые и платные системы управления! Настала эпоха новых решений - выбирайте «GIRVAS»!

  • Карельское решение

    «ГИРВАС» разработана в Республике Карелия, а также внесена в Реестр российского программного обеспечения Министерством цифрового развития Российской Федерации (реестровая запись №25012 от 27.11.2024).

Установка и настройка модуля TargetSMS для CMS «ГИРВАС»: полное руководство

Модуль TargetSMS предназначен для интеграции сайта, работающего под управлением CMS «ГИРВАС», с популярным SMS-шлюзом TargetSMS. Он позволяет администраторам отправлять SMS-сообщения из Админ-Центра, вести журнал и отслеживать статусы доставки, управлять базами номеров, стоп-листами, шаблонами и реестром отправителей. Кроме того, модуль предоставляет пользователям сайта возможность подтвердить свой номер телефона через SMS-код на специальной странице /phone.

В этом подробном руководстве мы рассмотрим все аспекты работы с модулем: от требований к серверу и установки до тонкой настройки параметров и решения возможных проблем. Статья будет полезна как администраторам сайтов, так и веб-разработчикам, занимающимся поддержкой проектов на CMS «ГИРВАС».

Требования к серверу и окружению

Перед началом установки убедитесь, что ваш сервер соответствует следующим требованиям:

  • CMS «ГИРВАС» версии 0.4.1 или новее.
  • PHP 8.1+ с расширениями curl, dom, libxml, mbstring, json.
  • PostgreSQL или MySQL/MariaDB (используется база данных CMS).
  • Аккаунт TargetSMS: вам понадобятся логин и пароль от личного кабинета TargetSMS. Токен (API Key) из личного кабинета модулю не нужен, так как XML API шлюза принимает только логин и пароль.
  • Для уведомлений о статусах (опционально): сайт должен быть открыт по HTTPS.
  • Права на запись в директорию cache/modules/targetsms/. В ней будут храниться настройки, кеш ответов шлюза, результаты действий и ограничитель частоты.

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

Установка модуля

Установка модуля TargetSMS в CMS «ГИРВАС» выполняется стандартным способом и не вызывает сложностей.

  1. Загрузка модуля: Перейдите в Админ-Центр → «Модули» → загрузите архив TargetSMS_1.0.4.zip (в архиве находится папка targetsms/). Альтернативный вариант — распаковать папку targetsms в директорию modules/ вручную.
  2. Активация: Нажмите «Активация». Таблицы модуля создаются автоматически при первом открытии раздела. Если при установке возникла ошибка, связанная с правами базы данных (например, ошибка MySQL 1142 «REFERENCES command denied»), модуль всё равно сможет работать: таблицы создаются без внешних ключей, а связь кода подтверждения с записью журнала поддерживает сам модуль. Недостающая таблица будет создана при следующем открытии раздела.
  3. Переход к разделу: На странице модуля появится кнопка «Перейти к разделу TargetSMS». После этого вы сможете приступить к настройке интеграции.

Первоначальная настройка

После установки модуля необходимо настроить основные параметры. Для этого перейдите в раздел TargetSMS и откройте вкладку «Настройки».

Аккаунт

В блоке «Аккаунт» укажите логин и пароль от личного кабинета TargetSMS. Пароль хранится в настройках сайта в зашифрованном виде и не показывается. Если вы не хотите менять текущий пароль, оставьте поле пустым. Для удаления сохранённого пароля предусмотрена отдельная кнопка.

Важно: модуль не использует API SMS-авторизации TargetSMS (apiagent.ru), так как он работает по незащищённому протоколу HTTP. Вместо этого все запросы к шлюзу выполняются через основной XML API по HTTPS.

Отправка

В блоке «Отправка» настраиваются параметры по умолчанию для исходящих SMS:

  • Отправитель по умолчанию: выберите подтверждённое имя отправителя из списка, который загружается из вашего аккаунта TargetSMS. Имя должно содержать до 11 латинских букв и цифр или до 15 цифр.
  • Транслитерация: при включении этой опции кириллица автоматически заменяется латиницей. Это позволяет вместить больше символов в одно SMS-сообщение.

Помимо этого, модуль имеет жёстко заданный параметр name_delivery (название рассылки), который всегда равен cms_girvas. Это значение задано в коде модуля и не подлежит настройке через интерфейс.

Подтверждение телефона

Одной из ключевых возможностей модуля является подтверждение номера телефона пользователями сайта. Для этого используется страница /phone, на которой пользователь указывает свой номер, получает SMS с кодом и вводит его для подтверждения. Другие модули CMS могут узнать подтверждённый номер через класс PublicTargetSMS (подробности смотрите в файле DEVELOPMENT.md).

В блоке «Подтверждение телефона» доступны следующие настройки:

  • Включить подтверждение телефона: глобальный переключатель функции.
  • Текст SMS: шаблон сообщения, в котором #CODE# заменяется на код подтверждения. Текст может содержать до 300 символов и должен быть одной строкой.
  • Цифр в коде: количество цифр в коде подтверждения (по умолчанию 4).
  • Срок действия кода, минут: время, в течение которого код считается действительным (по умолчанию 10 минут).
  • Попыток ввода кода: максимальное количество попыток ввода кода (по умолчанию 5).
  • Пауза перед повторной отправкой, секунд: интервал, через который пользователь может запросить новый код (по умолчанию 60 секунд).
  • Кодов в сутки на пользователя: лимит запросов кода в сутки (по умолчанию 5).

После включения функции рекомендуется разместить ссылку на страницу /phone в меню сайта или в профиле пользователя. Для удобства можно добавить параметр ?return=/profile, чтобы после подтверждения отображалась кнопка «Вернуться» на указанную страницу.

Уведомления о статусах

Шлюз TargetSMS может самостоятельно присылать статусы доставки SMS на адрес вашего сайта. Для этого в настройках модуля предусмотрен блок «Уведомления о статусах».

  • Адрес уведомлений: уникальный URL вида https://ваш-сайт.ru/handler/module-targetsms/state/секретный_код. Этот адрес содержит секретный код, который не следует публиковать.
  • Включить уведомления: при активации этой опции модуль сохраняет адрес сайта в шлюзе TargetSMS.

Важно: для работы уведомлений сайт должен быть открыт по HTTPS. Если вы не используете уведомления, статусы доставки можно обновлять вручную с помощью кнопки «Обновить статусы» в журнале сообщений.

Журнал и очистка

В блоке «Журнал» настраивается срок хранения записей (по умолчанию 180 дней). Записи журнала старше указанного срока, а также старые коды подтверждения и номера удалённых пользователей удаляются автоматически. Очистка выполняется раз в час при открытии раздела модуля или вручную с помощью кнопки «Выполнить очистку».

Удаление данных модуля

Если вы решите отказаться от использования модуля, в настройках предусмотрена функция полного удаления данных. Для подтверждения операции необходимо ввести слово targetsms. При этом удаляются таблицы модуля (журнал, подтверждённые номера, коды), настройки и служебные файлы. Данные в вашем аккаунте TargetSMS не затрагиваются.

Внимание: удаление данных необратимо. После выполнения операции модуль необходимо деактивировать и удалить в разделе «Модули».

Права доступа

Модуль TargetSMS не добавляет собственные права в ядро CMS, а использует стандартные права групп пользователей:

Возможность Право группы
Обзор, журнал, запланированные, входящие, статистика, отправители (просмотр), сведения о номерах «Управление модулями» или «Просмотр журналов»
Отправка SMS, удаление запланированных «Управление модулями»
Базы номеров, стоп-лист, шаблоны «Управление модулями» или «Управление пользователями»
Настройки, реестр отправителей, уведомления, очистка, удаление данных «Управление модулями»
Регистрация клиентов TargetSMS только суперпользователь

Пункты меню, на которые у группы нет прав, не отображаются. При переходе по адресу /admin/targetsms открывается первый доступный раздел.

Обзор возможностей модуля

Модуль TargetSMS предоставляет широкий набор инструментов для работы с SMS-рассылками. Рассмотрим основные разделы Админ-Центра.

Обзор

Раздел «Обзор» отображает ключевую информацию о вашем аккаунте TargetSMS: баланс и пакеты SMS, время аккаунта, имена отправителя, состояние уведомлений, а также статистику сообщений сайта за последние 30 дней с разбивкой по статусам. Для получения этих данных используются методы API balance.php, time.php, originator.php, get_state.php.

Отправка SMS

Раздел «Отправка» позволяет отправлять SMS на список номеров (до 5000 номеров за раз). В форме доступны следующие поля:

  • Номера: список номеров, разделённых запятой, точкой с запятой или новой строкой. Повторы удаляются автоматически.
  • Текст сообщения: счётчик символов и частей SMS обновляется в реальном времени. Длинные тексты отправляются несколькими частями, каждая из которых оплачивается отдельно.
  • Отправитель по умолчанию: можно выбрать имя отправителя.
  • Время отправки: позволяет запланировать отправку на определённое время (по часовому поясу аккаунта).
  • Срок жизни: время, в течение которого шлюз будет пытаться доставить сообщение.
  • Транслитерация: замена кириллицы латиницей.

Результат отправки отображается по каждому номеру.

Журнал сообщений

В журнале отображаются все сообщения, отправленные с сайта. Доступны фильтры по статусу, источнику и номеру. Кнопка «Обновить статусы» позволяет вручную запросить актуальные статусы доставки из шлюза.

Запланированные SMS

Раздел «Запланированные» показывает SMS, которые шлюз отправит позже. Отмеченные сообщения можно удалить. Используются методы API list_scheduled.php и scheduled.php.

Входящие SMS

Раздел «Входящие» отображает входящие SMS за выбранный период (метод incoming.php).

Статистика

Раздел «Статистика» предоставляет доступ ко всем SMS аккаунта за период до трёх месяцев. Доступны фильтры по дате, статусу, отправителю, номеру, оператору и времени. Итоги и стоимость отображаются в таблице. Используется метод stats.php.

Обратите внимание: статистика ограничена шлюзом тремя месяцами, а в таблице показываются первые 1000 строк.

Базы номеров

Раздел «Базы номеров» позволяет управлять базами номеров, создавать поздравления ко дню рождения, добавлять, изменять и удалять абонентов, а также загружать списки до 1000 строк. Используются методы list_bases.php, bases.php, list_phones.php, phones.php.

Стоп-лист

В стоп-листе хранятся номера, на которые шлюз не отправляет SMS. Вы можете просматривать и добавлять номера. Используются методы list_stop.php и stop.php.

Шаблоны

Раздел «Шаблоны» предназначен для управления шаблонами сообщений аккаунта. Используются методы list_patterns.php и patterns.php.

Отправители

Раздел «Отправители» позволяет управлять именами отправителя аккаунта и реестром отправителей у операторов МТС, МегаФон и Tele2. Доступен просмотр, подача заявок и удаление. Используются методы originator.php, list_registry_originator.php, registry_originator.php.

Сведения о номерах

Раздел «Сведения о номерах» позволяет получить информацию об операторе, регионе и часовом поясе для списка до 500 номеров. Используется метод def.php.

Регистрация клиентов

Раздел «Регистрация клиентов» доступен только суперпользователю и позволяет зарегистрировать клиента TargetSMS по партнёрской программе. Используется метод registrationusertarget.php.

Подтверждение номера телефона пользователями

Страница /phone предназначена для подтверждения номера телефона пользователями сайта. Процесс выглядит следующим образом:

  1. Пользователь указывает свой номер телефона на странице /phone.
  2. Сайт создаёт код подтверждения и отправляет его через TargetSMS.
  3. Пользователь вводит полученный код на странице.
  4. После успешного подтверждения номер сохраняется в базе сайта.
  5. Подтверждённый номер можно сменить или удалить.

Другие модули CMS могут получить подтверждённый номер пользователя через класс PublicTargetSMS. Подробная документация по использованию этого класса приведена в файле DEVELOPMENT.md.

Безопасность: коды подтверждения не записываются в журнал в открытом виде (вместо кода используются точки). В базе данных хранится только HMAC-хэш кода, что исключает его компрометацию при утечке данных.

Уведомления о статусах доставки

Для получения уведомлений о статусах доставки SMS шлюз TargetSMS отправляет HTTP-запросы на адрес вашего сайта. Модуль обрабатывает эти запросы и возвращает список принятых идентификаторов сообщений (id_sms).

Адрес обработчика имеет вид: https://ваш-сайт.ru/handler/module-targetsms/state/.

Рекомендации:

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

Кеширование и обработка ошибок

Модуль TargetSMS оптимизирован для работы с внешним шлюзом, который может быть недоступен. Для повышения отказоустойчивости реализованы следующие механизмы:

  • Кеширование: ответы шлюза для обзора, отправителей, шаблонов, баз и стоп-листа кешируются на 1–10 минут. Кнопка «Обновить данные шлюза» запрашивает их заново.
  • Сохранение последних данных: если шлюз не ответил, страница показывает последние полученные данные (не старше 7 дней) с датой получения.
  • Задержка запросов: страницы Админ-Центра в течение 30 секунд не обращаются к шлюзу после первого сбоя, чтобы не ждать его ответа на каждой странице. Кнопка «Обновить данные шлюза» снимает эту паузу.
  • Повторные запросы: запросы, которые только читают данные, при быстром обрыве связи повторяются один раз.
  • Единое соединение: запросы одной страницы идут по одному соединению.
  • Логирование ошибок: причина сбоя связи (код и текст ошибки cURL, время запроса, IP-адрес шлюза) записывается в журнал ошибок PHP строкой [targetsms] …. Логин и пароль в лог не попадают.

Персональные данные и соответствие 152-ФЗ

Модуль хранит в базе данных сайта номера телефонов: журнал отправленных SMS (номер, текст, статус) и подтверждённые номера пользователей. Эти номера передаются оператору TargetSMS для доставки SMS.

В соответствии с Федеральным законом № 152-ФЗ «О персональных данных» необходимо указать факт обработки номеров телефонов в политике конфиденциальности сайта.

Записи журнала старше срока хранения, старые коды и номера удалённых пользователей удаляются автоматически (раз в час при открытии раздела) или вручную с помощью кнопки в настройках. Коды подтверждения в журнал не пишутся (вместо кода — точки), в базе хранится только их HMAC.

Ограничения и известные особенности

Перед использованием модуля в production-окружении ознакомьтесь с ограничениями:

  • Работа с настоящим шлюзом TargetSMS не проверялась: все проверки выполнены на эмуляторе шлюза, написанном по документации API. Перед рассылками обязательно проверьте отправку на свой номер.
  • Проверено только на PostgreSQL: на MySQL/MariaDB модуль не запускался. Запросы построены через построитель запросов CMS и рассчитаны на обе СУБД, но гарантии работоспособности на MySQL нет.
  • API SMS-авторизации TargetSMS (apiagent.ru) не используется: он работает по HTTP без шифрования. Подтверждение телефона сделано через основной XML API по HTTPS — код создаёт и проверяет сам сайт.
  • В ядре CMS нет планировщика: очистка выполняется при открытии раздела модуля (не чаще раза в час) и кнопкой.
  • В статистике и списке запланированных показывается текст SMS так, как его хранит шлюз, — в том числе SMS с кодами подтверждения.
  • Статистика ограничена шлюзом тремя месяцами; в таблице показываются первые 1000 строк.
  • Ответы шлюза для обзора, отправителей, шаблонов, баз и стоп-листа кешируются на 1–10 минут; кнопка «Обновить данные шлюза» запрашивает их заново.

Заключение

Модуль TargetSMS для CMS «ГИРВАС» предоставляет полноценный инструментарий для интеграции сайта с SMS-шлюзом. Он позволяет автоматизировать отправку SMS, вести журнал и отслеживать статусы доставки, управлять базами номеров и шаблонами, а также реализовать подтверждение номеров телефонов пользователями.

При установке и настройке модуля следует учитывать требования к серверу, правам доступа и персональным данным. Рекомендуется тщательно протестировать работу модуля на тестовом окружении, особенно при использовании MySQL/MariaDB и перед первыми массовыми рассылками.

Соблюдение всех инструкций и рекомендаций позволит вам эффективно использовать возможности TargetSMS для коммуникации с пользователями вашего сайта.

Переводы

Комментарии

К этой записи нет комментариев.