Перейти к содержанию

Пример уведомлений на сайте

Общий принцип работы

  1. Зайти в админ-панель и перейти в раздел "Уведомления" - "SMTP-аккаунты". Добавить SMTP-аккаунт для отправки Email-уведомлений. Это будут отправители Email-уведомлений.

  2. Также перейти в "Уведомления" - "Категории" и создать категорию, которая будет использоваться для отправки писем. Обычно достаточно одной категории. Возможность вносить несколько категорий необходима для разделения на информационные и маркетинговые уведомления.

  3. Зайти в "Уведомления" - "Шаблоны" и создать шаблон на определенное событие (когда вы добавили их в settings.py - см. ниже в настройке).

  4. В коде, где необходимо отработать отправку уведомления, выполняем следующие действия:

from garpix_confirm.settings import CHOICES_NOTIFY_CONFIRM_EVENT
from garpix_notify.models import Notify

# Синтаксис
# Notify.send(<event>, <context>[, <user=None>, <email=None>, <phone=None>, <files=None>, <data_json=None>])
# Т.е. указываем первым параметром идентификатор события, 
# вторым переменные для шаблона,
# третьим - пользователя, которому отправить (необязательно указывать его емейл, номер телефона и т.п.,
# т.к. это будет определено автоматически в зависимости от типа шаблона)

# Пример
user = request.user  # это будет получатель уведомления.

Notify.send(CHOICES_NOTIFY_CONFIRM_EVENT, {
    'confirmation_code': 'abcdef12345',
}, user=user)

# Если у нас нет пользователя в системе, но необходимо отправить емейл, то можем поступить
# следующим образом

Notify.send(CHOICES_NOTIFY_CONFIRM_EVENT, {
    'confirmation_code': 'abcdef12345',
}, email='example@mail.ru')

Настройка:

Уведомления отправляются только по шаблонам. Шаблон - это модель, которая может быть одним из типов (Емейл, СМС или Пуш-уведомление) и содержащая текст, который будет отправлен.

При отправке уведомления (-ий) по шаблону, также можно добавить контекст, который будет применен при отправке сообщения (например, можно при отправке уведомления о регистрации передать имя пользователя в письмо). Шаблоны уведомлений используют контекст через шаблонизатор джанго. Т.е. можно применять переменные {{ variable }}, использовать циклы и условные операторы {% if blabla %}{% endif %} и т.п.

При отправке уведомления (-ий) по шаблону - обязательно передается событие. При этом, если на одно событие висит несколько шаблонов, то будут отправлены они все.

События обязательно должны иметь уникальный числовой идентификатор.

В настройках settings.py указывается словарь, содержащий описание всех (!) событий, на которые можно повесить уведомление. При этом обязательным является только числовой идентификатор события и его заголовок title.

В settings.py необходимо указать следующие настройки:

from garpix_confirm.settings import CHOICES_NOTIFY_CONFIRM_EVENT, NOTIFY_EVENTS_CONFIRM

REGISTRATION_EVENT = 1
FEEDBACK_EVENT = 2

NOTIFY_EVENTS = {
    REGISTRATION_EVENT: {
        'title': 'Регистрация',
        'context_description': 'super reg context description',
        'event_description': 'super event description',
        'test_data': {'ho': 'hey'},
    },
    FEEDBACK_EVENT: {
        'title': 'Обратная связь',
    },
}

# НЕ МЕНЯТЬ!
CHOICES_NOTIFY_EVENT = sorted([(k, v['title']) for k, v in NOTIFY_EVENTS.items()], key=lambda x: x[1])

NOTIFY_USER_WANT_MESSAGE_CHECK = "app.notify_user_want_message.check"  # default: None

,где * NOTIFY_EVENTS - словарь содержащий события с описанием, где:
- title - название события, - context_description - описание переменных шаблона (для отображения в админке), - event_description - описание события, - test_data - словарь, с данными (аналогично реальному контексту) для отладки шаблонов (отправка тестовых сообщений)

  • CHOICES_NOTIFY_EVENT - генерация списка типа события для модели шаблонов.
  • NOTIFY_SMS_URL - URL сервиса отправки смс.
  • NOTIFY_SMS_API_ID - ид для доступа к сервису отправки смс.
  • FCM_DJANGO_SETTINGS - ключ для авторизации FCM SERVER.
  • NOTIFY_USER_WANT_MESSAGE_CHECK - путь к методу, который определяет, отправлять ли пользователю уведомление (может пользователь не хочет их получать, отключил это).

Пример app.notify_user_want_message.check:

def check(notify_event_id, notify_type, user=None):
    if user is None:
        return True
    return user.is_notify_enabled:  # your custom variable

Важно!

  1. В настройках celery проекта необходимо указать следующее: settings.py:
CELERY_ENABLE_UTC = False
DJANGO_CELERY_BEAT_TZ_AWARE = False

settings.py:

from django.utils import timezone
app.now = timezone.now

Необходимость настроек обусловлена тем что celery неоднозначно преобразовывает время выполнения задач если в системе/проекте указана timezone отличная от UTC.

  1. В отдельной командной строке ввести:
celery -A app worker --loglevel=info -B

"celery" должен быть запущен параллельно с "runserver"

Обобщенный принцип работы

  1. Создаем события, попутно определяя контекст события.

  2. Создаем категории уведомлений. Причем категория:

    • с точки зрения шаблона является аналогом base.html для страниц проекта.
    • сточки зрения SMTP аккаунта - определяет с каких сервисов (аккаунтов ***@***.***) будут оптравлятся события.
  3. Создаем шаблоны уведомлений. При указании соответствующих данных в settings.NOTIFY_EVENTS.event_id['test_data'] в админке возможна отправка тестовых уведомлений для отладки.
  4. В соответствующих участках кода проекта создаем уведомления согласно примерам ниже с указанием соответствующего события.

Использование:

Шаблоны

Для отправки писем по шаблонам, необходимо вызвать метод send модели Notify

Notify.send(<event>, <context>[, <user=None>, <email=None>, <phone=None>, <files=None>, <data_json=None>])

,где

  • event - событие, весь перечень указан в settings.notify.CHOICES_NOTIFY_EVENT
  • context - контекст, необходимый для рендеринга уведомления
  • user - пользователь, который будет указан, если он не указан в модели шаблона
  • email - email для отправки почты, который будет указан, если он не указан в модели шаблона
  • phone - телефон, который будет указан, если он не указан в модели шаблона
  • files - массив файлов, который будет автоматически сохранен и добавлен ко всем письмам
  • data_json - словарь данных, который будет автоматически сохранен и отправлен как data к пушам

Команда использует шаблоны notify.models.NotifyTemplate, которые можно заполнить в админке Уведомления -> Шаблоны. Команда автоматически пробегает по всем созданным шаблонам, соответствующим указанному событию и создает по ним уведомления, предварительно отрендерив поля текст и html, с указанным контекстом

Telegram

Зарегистрируйте своего бота https://t.me/BotFather

Зайдите в конфигурацию http://localhost:8000/admin/garpix_notify/notifyconfig/ и заполните раздел "Telegram" (API ключ и Имя бота).

Запустите демона:

python3 backend/manage.py garpix_notify_telegram

Напишите вашему боту в Telegram команду /start

Также, можете дополнить ваш файл user/admin.py следующим содержимым и увидите инструкции по привязке пользователя Telegram к пользователю вашей системы:

from django.contrib import admin
from .models import User
from django.contrib.auth.admin import UserAdmin


@admin.register(User)
class UserAdmin(UserAdmin):
    fieldsets = (
        ('Telegram', {
            'fields': ('telegram_chat_id', 'telegram_secret', 'get_telegram_connect_user_help'),
        })
    ) + UserAdmin.fieldsets
    readonly_fields = ['telegram_secret', 'get_telegram_connect_user_help'] + list(UserAdmin.readonly_fields)

Viber

  • Регистрация бота
    • Бота зарегистрировать тут https://partners.viber.com/ и получить токен \ токен = viber_api_key

  • Настройки бота

    • Указать токен в админке Уведомления -> Настройки
    • Можно изменить имя и аватар бота
    • Можно изменить ответы бота на различные события
    • Бот работает только на https, для локальной разработки можно использовать ngrok
    • Документация от вайбера https://developers.viber.com/docs/api/

  • Web hook

    • Для установки вебхука нужно перейти по ссылке https://yourdomain/garpix_notify/send_webhook
    • Для снятия вебхука нужно отправить POST запрос на адрес https://chatapi.viber.com/pa/set_webhook headers X-Viber-Auth-Token: <ваш токен> \ body { "url":"" }
  • Получить id пользователя
    • Пользователь должен первым начать диалог с ботом
    • Чтобы пользователь получал рассылку от бота, он должен отправить боту viber_secret_key
    • viber_secret_key указывается в настройка юзера в админке. поле Ключ подключения Viber
    • Если сообщение пользователя совпадает с viber_secret_key, то viber_chat_id заполняется
    • id юзера привязывается к конкретному боту, то есть, для разных ботов у юзера будет разный id
  • Отправка сообщений
    • Создаем шаблон и заполняем в нем все обязательные поля, Тип должен быть Viber
    • Для отправки сообщений группе пользователй создаем Список пользователей
    • Можно отправлять сообщения через код, для этого в методе send нужно указать viber_chat_id
Notify.send(settings.YOUR_EVENT, {
  'some_context': blabla
}, viber_chat_id='')