Отчёты на почту

Stats3x может присылать отчёт о посещаемости на почту: каждый день, раз в неделю или раз в месяц. Письма отправляет компонент Вестник (Vestnik) - его нужно установить отдельно.

Как это устроено

Stats3x сам письма не отправляет. Он считает цифры и передаёт их Вестнику, а письмо по своему шаблону собирает, ставит в очередь и отправляет Вестник. Без Вестника остальная статистика работает, просто отчёты не уходят. По шагам:

1. Раз в час задача cron Stats3x «Отчёт на почту через Вестник» проверяет, пора ли отправлять: отправка включена, получатели указаны, период закончился, уже 7:00 или позже и отчёт за этот период ещё не отправлялся.
2. Если пора, Stats3x считает цифры за прошедший период и за такой же период перед ним (для сравнения), готовит таблицы страниц, источников и целей и вызывает событие Вестника stats3x.report - по одному разу на каждый адрес из настройки stats3x.vestnik_recipients.
3. Вестник находит правило с ключом события stats3x.report, берёт привязанный к нему шаблон, подставляет данные в плейсхолдеры и кладёт готовое письмо в очередь (Пакеты → Vestnik → вкладка «Очередь»). Письмо собирается в этот момент: если потом изменить шаблон, письма, которые уже в очереди, не изменятся.
4. Cron Вестника - отдельное задание cron - раз в минуту отправляет письма из очереди через почту MODX: по SMTP, если он включён в системных настройках, иначе функцией mail() сервера.
5. Итог каждой отправки - во вкладке «Журнал» Вестника: «Отправлено» или «Ошибка» с текстом ошибки. Неудачная отправка повторяется при следующих запусках cron Вестника, после vestnik_max_attempts попыток (по умолчанию 3) письмо уходит в журнал с ошибкой.

Настройка по шагам

1. Установите компонент Вестник (Vestnik) через Установщик пакетов. Пока его нет, на вкладке «Состояние» в карточке «Отчёты на почту» написано, что Вестник не установлен.
2. Проверьте, что сайт умеет отправлять почту. Письма отправляет MODX: для SMTP заполните системные настройки mail_use_smtp, mail_smtp_hosts, mail_smtp_port, mail_smtp_prefix (ssl или tls), mail_smtp_auth, mail_smtp_user и mail_smtp_pass. Адрес отправителя - настройка Вестника vestnik_from_email (пусто - emailsender), имя - vestnik_from_name (пусто - site_name). Отправитель должен быть на домене сайта, иначе письма попадут в спам.
3. Добавьте cron Вестника - он отправляет письма из очереди. Это второе задание, в дополнение к cron Stats3x:

   * * * * * php /путь/к/сайту/core/components/vestnik/cron.php > /dev/null 2>&1

4. В системных настройках (пространство имён stats3x, раздел «Отчёты на почту (Вестник)») укажите получателей в stats3x.vestnik_recipients - адреса через запятую или с новой строки - и выберите в stats3x.vestnik_period, как часто отправлять: daily, weekly или monthly.
5. Проверьте отправку: вкладка «Состояние» → карточка «Отчёты на почту» → кнопка «Отправить отчёт сейчас». При первом нажатии Stats3x сам создаёт в Вестнике шаблон и правило (см. ниже). Под кнопкой появится, сколько писем встало в очередь. Через минуту cron Вестника их отправит; чтобы не ждать - Пакеты → Vestnik → «Очередь» → «Разобрать очередь». Результат - во вкладке «Журнал».
6. Когда тестовое письмо пришло, включите расписание: stats3x.vestnik_enabled = Да. Кнопка работает и при выключенной настройке, поэтому отчёт можно проверить и оформить заранее.

Что Stats3x создаёт в Вестнике

При первой отправке (кнопкой или по расписанию), если их ещё нет:

• Шаблон «Stats3x: отчёт о посещаемости» (вкладка «Шаблоны»): тема «Статистика [[+site_name]] за [[+period]]», тело - готовое HTML-письмо из файла core/components/stats3x/elements/email/report.язык.tpl. Язык - язык менеджера в момент создания (ru, en, de, es, pt, для остальных - en).
• Правило «Stats3x: отчёт на почту» (вкладка «Правила»): ключ события stats3x.report, источник «Событие компонента», стратегия получателя «Пользователь события», значение получателя пустое, канал email, шаблон - тот, что выше.

Стратегия «Пользователь события» означает, что адрес берётся из данных события: Stats3x вызывает событие отдельно для каждого получателя и передаёт его адрес в поле email. Поэтому получатели меняются только в настройке stats3x.vestnik_recipients. Не меняйте стратегию правила на «Явный адрес», «Администратор» или «Группа пользователей» и не создавайте второе правило на stats3x.report: каждый вызов события отправит письмо всем адресам такого правила, и получатели получат по несколько копий.

Stats3x не перезаписывает шаблон и правило - их можно менять как угодно. Чтобы вернуть исходный шаблон, удалите его в Вестнике: при следующей отправке Stats3x создаст его заново и привяжет к правилу (если удалить и правило, создадутся оба). Шаблон на другом языке: скопируйте в него тело из файла report.en.tpl (de, es, pt, ru) или удалите шаблон, переключите язык менеджера и нажмите «Отправить отчёт сейчас». Выключенные правило или шаблон останавливают отчёты: Вестник не ставит письма в очередь, кнопка сообщает об этом, а задача cron повторяет попытку каждый час.

Плейсхолдеры шаблона

Эти данные Stats3x передаёт в событие, их можно использовать в теме и теле шаблона Вестника. Числа уже отформатированы. Всё, что пришло от посетителей (заголовки страниц, сайты, UTM-метки), уже экранировано - добавлять :htmlent не нужно.

Плейсхолдеры *_html и *_delta - готовый HTML со встроенными стилями (почтовые программы не понимают внешний CSS). Вставляйте их в шаблон как есть.

Пример: свой шаблон письма

Откройте Пакеты → Vestnik → вкладка «Шаблоны» → «Stats3x: отчёт о посещаемости», поменяйте тему и тело письма и сохраните. Например, короткое письмо вместо стандартного:

<h2 style="margin:0">[[+site_name]]</h2>
<p style="color:#64748b">Статистика за [[+period]]</p>
<p>
  Посетители: <b>[[+visitors]]</b> [[+visitors_delta]]<br>
  Визиты: <b>[[+visits]]</b> [[+visits_delta]]<br>
  Просмотры: <b>[[+hits]]</b> [[+hits_delta]]<br>
  Отказы: <b>[[+bounce_rate]]</b> [[+bounce_rate_delta]]
</p>
<h3>Популярные страницы</h3>
[[+pages_html]]
[[+goals_html:notempty=`<h3>Цели</h3>[[+goals_html]]`]]
<p><a href="[[+report_url]]">Открыть статистику</a></p>

Тема письма - тоже шаблон, например:

[[+site_name]]: [[+visitors]] посетителей за [[+period]]

• Блок с условием: [[+goals_html:notempty=`...`]] выводится, только если плейсхолдер не пустой.
• Отправитель этого письма - поля «Отправитель (email)» и «Отправитель (имя)» в шаблоне; если они пусты, берутся настройки Вестника.
• Стандартный шаблон на всех языках лежит в core/components/stats3x/elements/email/ - его удобно взять за основу.

Важно: «Отправить тест» в редакторе шаблона Вестника подставляет свои примерные данные (имя, email, номер заказа) - цифр статистики там нет, и плейсхолдеры отчёта в тестовом письме будут пустыми. Чтобы увидеть письмо с настоящими цифрами, нажмите «Отправить отчёт сейчас» на вкладке «Состояние» Stats3x и откройте письмо в Вестнике: «Очередь» → «Просмотр письма» (пока оно не отправлено) или «Журнал» → «Просмотр» (после отправки).

Когда приходит отчёт

• daily - каждый день, за вчера.
• weekly (по умолчанию) - по понедельникам, за прошлую неделю с понедельника по воскресенье.
• monthly - 1-го числа, за прошлый месяц.

Отчёт встаёт в очередь при первом запуске задачи после 7:00 по часовому поясу сайта (date_timezone): к этому времени итоги прошлого дня уже пересчитаны. Задача запускается раз в час, поэтому письмо приходит между 7:00 и 8:00. Отчёт за каждый период отправляется один раз; если в нужный день cron не работал, отчёт уйдёт при первом запуске позже, пока не закончится следующий период. Цифры сравниваются с таким же числом дней непосредственно перед периодом: неделя - с позапрошлой неделей, вчера - с позавчера.

Кнопка «Отправить отчёт сейчас» отправляет отчёт за последний закончившийся период сразу, в любое время и сколько угодно раз. На расписание она не влияет: плановый отчёт за этот период всё равно придёт.

Запустить задачу из консоли - с теми же проверками, что и по расписанию (не раньше 7:00 и не повторно):

php /путь/к/сайту/core/components/stats3x/cron.php -v --task=vestnik

Если отчёт не пришёл

Сначала откройте вкладку «Состояние»: в карточке «Отчёты на почту» видно, включена ли отправка, кто получатели и когда ушёл последний отчёт, а в таблице «Задачи cron» у задачи «Отчёт на почту через Вестник» - итог последнего запуска. Дальше - по признакам:

• «Компонент Вестник не установлен» - установите Вестник.
• Нет кнопки «Отправить отчёт сейчас» - не заполнена stats3x.vestnik_recipients или у вас нет права stats3x_save.
• «Отправка отчётов выключена» в итоге задачи - включите stats3x.vestnik_enabled.
• «Отчёт отправится после 7:00» или «Отчёт за ... уже отправлен» - всё в порядке, задача ждёт своего времени.
• «Вестник не поставил ни одного письма в очередь» - выключено правило «Stats3x: отчёт на почту» или его шаблон либо у правила изменён ключ события. Включите их в Вестнике на вкладках «Правила» и «Шаблоны».
• Письма стоят во вкладке «Очередь» Вестника - не работает cron Вестника. Добавьте задание (шаг 3 настройки) или нажмите «Разобрать очередь».
• В «Журнале» статус «Ошибка» - причина в колонке «Ошибка». Обычно это настройки почты MODX (SMTP-сервер, порт, логин, пароль) или отправитель не с домена сайта.
• Все письма приходят на один адрес - в Вестнике включён отладочный режим vestnik_debug_mode: письма уходят на vestnik_debug_email.
• В «Журнале» «Отправлено», но письма нет - проверьте папку «Спам», настройте для домена отправителя SPF и DKIM.
• В письме нули - за период нет данных: проверьте, что работает cron Stats3x и сниппет стоит на страницах.

Подробно, что Вестник делает с каждым событием (сколько правил совпало, почему письмо не встало в очередь), он пишет в журнал ошибок MODX при включённой настройке vestnik_debug_mode. Включайте её только на время проверки: в этом режиме все письма уходят на vestnik_debug_email.

Для разработчиков: отчёт из своего кода

Данные письма за любой период готовит класс Stats3x\EmailReport. Например, отправить отчёт за прошлый месяц на отдельный адрес из своего сниппета или плагина:

$modx->lexicon->load('stats3x:default');
$report = new \Stats3x\EmailReport($modx);
[$from, $to] = \Stats3x\EmailReport::lastPeriod('monthly');
$data = $report->data($from, $to);

$modx->services->get('Vestnik')->trigger(
    'stats3x.report',
    ['email' => 'director@example.com'] + $data,
    'component'
);

Для письма другого вида заведите в Вестнике своё событие (например, my.report.director), правило к нему со стратегией «Явный адрес» и свой шаблон и вызывайте trigger() с этим ключом - плейсхолдеры будут те же.