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 в административной панели CMS «ГИРВАС»
Раздел обзора модуля TargetSMS в административной панели CMS «ГИРВАС»

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

Отправка SMS

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

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

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

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

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

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

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

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

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

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

Входящие SMS

Раздел входящих SMS модуля TargetSMS в административной панели CMS «ГИРВАС»
Раздел входящих SMS модуля TargetSMS в административной панели CMS «ГИРВАС»

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

Статистика

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

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

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

Базы номеров

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

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

Стоп-лист

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

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

Шаблоны

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

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

Отправители

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

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

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

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

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

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

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

Раздел «Регистрация клиентов» доступен только суперпользователю и позволяет зарегистрировать клиента 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 для коммуникации с пользователями вашего сайта.

TargetSMS
TargetSMS
TargetSMS — это веб-сервис для отправки SMS-рассылок и уведомлений. Он помогает бизнесу оперативно информировать клиентов и сотрудников: например, сообщать о статусе заказа, отправлять персональные предложения или поздравления.
Переводы

Комментарии

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