Создание виджета подписки с помощью Node.js

Недавно я разработал виджет подписки с открытым исходным кодом, созданный с использованием библиотеки API Node.js компании SendGrid. Вы можете найти больше информации о мотивах и возможностях проекта на странице README репозитория. Хотя это не официально поддерживаемая библиотека SendGrid, цель состояла в том, чтобы сделать легко развертываемый гибкий виджет, который любой клиент SendGrid может включить в HTML-страницу, которая собирает адреса электронной почты существующих и потенциальных клиентов и другую полезную информацию для хранения в своих контактах маркетинговых кампаний. . После того, как клиенты введут информацию в форму, они получат электронное письмо со ссылкой для подтверждения своего адреса электронной почты, и после нажатия на ссылку получатель будет добавлен в список контактов данного клиента SendGrid.

Помимо этой базовой функциональности, виджет также может:

• Добавить пользователя в определенный сегмент списка, если он указан
• Включить настраиваемые поля в форму, вводы которых будут храниться с заданным контактом
• Отправьте электронное письмо с подтверждением с существующим шаблоном электронной почты, если он указан

Это был интересный проект, потому что он использовал ряд возможностей SendGrid и конечных точек API, в том числе:

• API отправки почты
• API контактов
• Веб-перехватчик событий
• Транзакционные шаблоны

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

Обзор дизайна виджета

Виджет подписки функционирует, позволяя клиентам SendGrid развертывать приложение в Heroku с помощью кнопки развертывания Heroku. Чтобы создать виджет с помощью кнопки развертывания, клиентам SendGrid потребуется учетная запись Heroku (вы можете создать бесплатную учетную запись здесь). Однако теоретически виджет можно развернуть на любом хостинг-провайдере. Затем клиент SendGrid может изменить конечную точку, к которой настраиваемая форма отправляет запрос POST, на URL-адрес недавно развернутого приложения Heroku. Когда пользователь отправляет форму, запрос будет обработан приложением, размещенным на Heroku.

Само приложение представляет собой базовое приложение Node/Express с двумя маршрутами, обрабатывающими процесс регистрации. Маршрут confirmEmail отправляет пользователям электронное письмо со ссылкой для подтверждения их адреса электронной почты и использует настраиваемый шаблон транзакции (если он указан). Маршрут регистрации добавляет пользователя в список контактов клиента SendGrid и, если он указан, также добавляет пользователя в настраиваемый сегмент списка. Маршрут регистрации также обрабатывает любые настраиваемые поля, которые клиент SendGrid выбирает для включения в свою настраиваемую форму.

Подтвердить маршрут электронной почты

Маршрут confirmEmail — это просто почтовый запрос к конечной точке POST v3/mail/send с использованием вспомогательной библиотеки Node.js SendGrid. При успешном ответе пользователь будет перенаправлен на страницу с просьбой проверить свой почтовый ящик на наличие письма с подтверждением. В случае неудачного ответа пользователь будет перенаправлен на страницу с просьбой повторно ввести свой адрес электронной почты. Например, это может произойти, если пользователь введет неверный адрес электронной почты.

Функция prepareEmail возвращает объект JSON, который будет служить телом запроса API.

Основной процесс создания объекта довольно прост. В него вставляется адрес электронной почты получателя из отправки формы. Однако в процессе создания объекта происходит несколько интересных вещей.

Основные пользовательские аргументы

В персонализации включены два настраиваемых аргумента: 1) тип, для которого установлено значение «согласие», и 2) time_sent, для которого установлено текущее время. Эти настраиваемые аргументы передаются в заголовке электронной почты и будут использоваться при определении необходимости добавления пользователя в список в процессе подтверждения.

Идентификатор шаблона

После первоначального создания объекта мы проверяем, выбрал ли клиент SendGrid использование пользовательского шаблона в файле настроек, и добавляем его к объекту, если это так (значение по умолчанию — null). Пользовательский шаблон будет иметь приоритет над текстом сообщения, включенным в тело сообщения, поэтому, если идентификатор шаблона оставить в виде нулевого значения, сообщение по умолчанию будет содержать предоставленный текст сообщения.

Вставить замену ссылки

Мы включаем замену для термина insert_link . Это будет иметь значение только в том случае, если клиент SendGrid решит использовать транзакционный шаблон. В этом случае термин insert_link будет заменен фактической ссылкой, которая используется для подтверждения электронной почты пользователя и перенаправления его на соответствующую страницу успеха.

Отправка входных данных формы в качестве настраиваемых аргументов

Наконец, мы добавляем значения, которые конечный пользователь отправил в тело электронной почты, в качестве настраиваемых аргументов. Отправка конечного пользователя передается в исходный маршрут confirmEmail в качестве тела запроса, который затем передается в функцию prepareEmail в качестве параметра. Тело запроса содержит объект с набором пар ключей и значений, представляющих имя ввода и значение, отправленное пользователем. Затем мы перебираем ключи объекта, добавляя настраиваемый аргумент в электронное письмо для каждой пары ключ-значение. Эти значения будут добавлены к контактной информации конечного пользователя в процессе создания контакта.

Маршрут регистрации

Маршрут регистрации запускается веб-перехватчиком событий, который отправляет запрос POST каждый раз, когда пользователь щелкает ссылку, указанную в полученном им электронном письме с подтверждением. Этот маршрут должен позаботиться о нескольких элементах в процессе создания контакта. Мы должны сделать следующее:

• Проверьте, содержит ли форма какие-либо настраиваемые поля
• Проверьте, существуют ли настраиваемые поля в учетной записи клиента SendGrid, и создайте их, если поля не существуют.
• Убедитесь, что это электронное письмо с возможностью подписки , как указано типом в процессе создания электронной почты.
• Убедитесь, что ссылка была нажата в течение 24 часов
• Создайте контакт в учетной записи клиента SendGrid.
• Добавить новый контакт в определенный сегмент списка, если он был предоставлен

Обработка настраиваемых полей

Маршрут регистрации вызывает функцию addUserToList . Эта функция вызывается внутри маршрута, чтобы мы могли отправить статус после завершения процесса внутри обратного вызова. Первое, что мы делаем внутри этой функции, — это создаем объект, содержащий все настраиваемые поля, содержащиеся в форме, и массив, содержащий настраиваемые поля, которые не предусмотрены по умолчанию для всех контактов (email, first_name, last_name).

Запрос POST, инициированный веб-перехватчиками событий, содержит всю информацию, связанную с электронной почтой, включая заголовки, тему, текст и т. д. Все, о чем мы заботимся, — это предоставленные настраиваемые аргументы, которые содержатся в виде объекта в первом элементе. тела запроса. Однако объект также содержит множество полей, которые нам не нужны для процесса обработки настраиваемых полей, которые мы помещаем в массив с именем ignoreFields .

Затем мы перебираем пользовательские аргументы, чтобы создать объект и массив с пользовательскими полями, упомянутыми ранее. Мы передадим полный объект настраиваемых полей в тело в процессе создания контакта, но только после того, как мы добавим настраиваемые поля по мере необходимости на предыдущем шаге.

Затем мы вызываем функцию checkAndAddCustomFields с двумя параметрами, массивом настраиваемых полей и обратным вызовом, где мы позаботимся о создании контакта. Важно сначала проверить и добавить любые настраиваемые поля, потому что конечная точка выдаст ошибку, если вы попытаетесь создать контакт с несуществующим настраиваемым полем.

Функция checkAndAddCustomFields сначала отправляет запрос GET к конечной точке /v3/contactdb/custom_fields для получения существующих полей базы данных контактов. Затем он сравнивает список существующих настраиваемых полей со списком отправленных полей, которые были переданы в качестве параметра, и, если есть какие-либо отправленные поля, не включенные в список существующих настраиваемых полей, эти новые поля добавляются в массив fieldsToCreate. . Если полей для создания нет, вызывается функция обратного вызова. Однако, если есть какие-либо поля для создания, мы делаем запрос POST к конечной точке /v3/contactdb/custom_fields для каждого нового настраиваемого поля, которое будет создано.

Создание нового контакта

После создания настраиваемых полей мы создаем новый контакт, отправляя запрос POST к конечной точке /v3/contactdb/recipients , передавая настраиваемые поля в качестве тела запроса. Затем мы проверяем, решил ли клиент SendGrid добавить пользователей в данный сегмент списка, и добавляем их в данный сегмент, если это так. Ответ на запрос API создания контакта включает идентификаторы вновь созданных контактов в виде массива с именем persisted_recipients . Используя идентификатор контакта, предоставленный в ответе, и идентификатор списка, предоставленный клиентом SendGrid, мы затем делаем запрос POST к конечной точке /v3/contactdb/lists/{listId}/recipients/{contactID} .