Creación de un widget de suscripción con Node.js

Recientemente desarrollé un widget de suscripción de código abierto creado con la biblioteca API Node.js de SendGrid. Puede encontrar más información sobre las motivaciones y capacidades del proyecto en la página README del repositorio. Si bien esta no es una biblioteca de SendGrid compatible oficialmente, el objetivo era crear un widget flexible y de fácil implementación que cualquier cliente de SendGrid pueda incorporar en una página HTML que recopile direcciones de correo electrónico de clientes existentes y potenciales y otra información útil para almacenar en sus contactos de campañas de marketing. . Después de que los clientes ingresan la información en el formulario, reciben un correo electrónico con un enlace para confirmar su dirección de correo electrónico y, al hacer clic en el enlace, el destinatario se agregará a la lista de contactos del cliente de SendGrid.

Más allá de esa funcionalidad básica, el widget también puede:

• Agregar un usuario a un segmento de lista específico, si se especifica
• Incluya campos personalizados en el formulario, cuyas entradas se almacenarán con un contacto dado
• Envíe el correo electrónico de confirmación con una plantilla de correo electrónico existente, si se especifica

Este fue un proyecto interesante porque utilizó una variedad de capacidades de SendGrid y puntos finales de API, que incluyen:

• API de envío de correo
• API de contactos
• Webhook de evento
• Plantillas transaccionales

Esta publicación discutirá el proceso de creación del widget y algunos de los procesos de pensamiento que intervinieron en su implementación y diseño.

Descripción general del diseño de widgets

El widget de suscripción funciona al permitir que los clientes de SendGrid implementen una aplicación en Heroku usando el botón de implementación de Heroku. Para crear el widget con el botón de implementación, los clientes de SendGrid necesitarán una cuenta de Heroku (puede crear una cuenta gratuita aquí). Sin embargo, en teoría, el widget se puede implementar en cualquier proveedor de alojamiento. El cliente de SendGrid puede cambiar el punto final al que el formulario personalizado realiza su solicitud POST a la URL de la aplicación Heroku recién implementada. Cuando un usuario envía el formulario, la solicitud será procesada por la aplicación alojada en Heroku.

La aplicación en sí es una aplicación Node/Express básica con dos rutas que manejan el proceso de registro. La ruta confirmEmail envía a los usuarios un correo electrónico con un enlace para confirmar su dirección de correo electrónico y utiliza una plantilla transaccional personalizada (si se especifica una). La ruta de registro agrega un usuario a la lista de contactos del cliente de SendGrid y, si se especifica, también agrega al usuario a un segmento de lista personalizado. La ruta de registro también maneja cualquier campo personalizado que un cliente de SendGrid elija incluir en su formulario personalizado.

Confirmar ruta de correo electrónico

La ruta confirmEmail es simplemente una solicitud posterior al extremo POST v3/mail/send utilizando la biblioteca de ayuda Node.js de SendGrid. En una respuesta exitosa, el usuario será redirigido a una página que le pedirá que revise su bandeja de entrada para ver el correo electrónico de confirmación. En una respuesta fallida, el usuario será redirigido a una página que le pedirá que vuelva a ingresar su dirección de correo electrónico. Por ejemplo, esto puede suceder si un usuario ingresara una dirección de correo electrónico no válida.

La función prepareEmail devuelve un objeto JSON que servirá como cuerpo de la solicitud de API.

El proceso básico de creación de objetos es bastante simple. En él, se inserta la dirección de correo electrónico del destinatario desde el envío del formulario. Sin embargo, hay algunas cosas interesantes que suceden en el proceso de creación de objetos.

Argumentos personalizados básicos

Se incluyen dos argumentos personalizados dentro de las personalizaciones: 1) tipo, que se establece en 'opt-in', y 2) time_sent, que se establece en la hora actual. Estos argumentos personalizados se pasan en el encabezado del correo electrónico y se utilizarán para determinar si un usuario debe agregarse a una lista en el proceso de confirmación.

ID de plantilla

Después de la creación inicial del objeto, verificamos si el cliente de SendGrid eligió utilizar una plantilla personalizada en el archivo de configuración y la agregamos al objeto si ese es el caso (null es el valor predeterminado). Una plantilla personalizada tendrá prioridad sobre el texto del correo incluido en el cuerpo, por lo que si la ID de la plantilla se deja como un valor nulo, el mensaje tendrá el texto del correo proporcionado de manera predeterminada.

Insertar sustitución de enlace

Incluimos una sustitución del término insert_link . Esto solo será relevante si el cliente de SendGrid elige usar una plantilla transaccional. Si ese es el caso, el término insert_link se reemplazará por el enlace real que se utiliza para confirmar el correo electrónico de un usuario y redirigirlo a la página de éxito adecuada.

Enviar las entradas del formulario como argumentos personalizados

Finalmente, agregamos los valores que el usuario final envió al cuerpo del correo electrónico como argumentos personalizados. El envío del usuario final se pasa a la ruta inicial confirmEmail como el cuerpo de la solicitud, que luego pasamos a la función prepareEmail como parámetro. El cuerpo de la solicitud contiene un objeto con un conjunto de claves, pares de valores que representan el nombre de la entrada y el valor que envió el usuario. Luego recorremos las claves de objeto agregando un argumento personalizado al correo electrónico para cada par de clave y valor. Estos valores se agregarán a la información de contacto del usuario final en el proceso de creación de contactos.

Ruta de registro

La ruta de registro se activa mediante un webhook de eventos que realiza una solicitud POST cada vez que un usuario hace clic en el enlace proporcionado en el correo electrónico de confirmación que recibe. Esta ruta debe encargarse de algunos elementos en el proceso de creación de contactos. Debemos hacer lo siguiente:

• Compruebe si el formulario contenía campos personalizados
• Verifique si los campos personalizados existen en la cuenta del cliente de SendGrid y créelos si los campos no existen
• Asegúrese de que este sea un correo electrónico de suscripción según lo especificado por el tipo en el proceso de creación de correo electrónico
• Asegúrese de que se haya hecho clic en el enlace dentro de las 24 horas
• Crear el contacto en la cuenta del cliente de SendGrid
• Agregue el nuevo contacto a un segmento de lista específico si se ha proporcionado uno

Manejo de campos personalizados

La ruta de registro llama a la función addUserToList . Esta función se llama dentro de la ruta para que podamos enviar el estado después de que el proceso se complete dentro de una devolución de llamada. Lo primero que hacemos dentro de esta función es crear un objeto que contenga todos los campos personalizados que contiene el formulario y una matriz que contenga los campos personalizados que no se proporcionan de forma predeterminada para todos los contactos (correo electrónico, nombre, apellido).

Una solicitud POST desencadenada por webhooks de eventos contiene toda la información relacionada con el correo electrónico, incluidos los encabezados, el asunto, el texto, etc. del correo electrónico. Lo único que nos importa son los argumentos personalizados que se han proporcionado, que están contenidos como un objeto dentro del primer elemento. del cuerpo de la solicitud. Sin embargo, el objeto también contiene una variedad de campos que no necesitamos para el proceso de manejo de campos personalizados, que colocamos en una matriz llamada ignoreFields .

Luego recorremos los argumentos personalizados para crear el objeto y la matriz con los campos personalizados mencionados anteriormente. Pasaremos el objeto de campos personalizados completo al cuerpo en el proceso de creación de contactos, pero no hasta que agreguemos campos personalizados, según sea necesario, en un paso anterior.

Luego llamamos a la función checkAndAddCustomFields con dos parámetros, la matriz de campos personalizados y una devolución de llamada, que es donde nos encargaremos de crear el contacto. Es importante verificar primero y agregar cualquier campo personalizado porque el punto final generará un error si intenta crear un contacto con un campo personalizado que no existe.

La función checkAndAddCustomFields primero realiza una solicitud GET al extremo /v3/contactdb/custom_fields para recuperar los campos existentes de la base de datos de contactos. Luego compara la lista de campos personalizados existentes con la lista de campos enviados que se pasaron como parámetro, y si hay campos enviados que no están incluidos en la lista de campos personalizados existentes, esos nuevos campos se agregan a la matriz de campos para crear. . Si no hay ningún campo para crear, se llama a la función de devolución de llamada. Sin embargo, si hay campos para crear, hacemos una solicitud POST al punto final /v3/contactdb/custom_fields para cada nuevo campo personalizado que se creará.

Creación del nuevo contacto

Una vez que se han creado los campos personalizados, creamos un nuevo contacto haciendo una solicitud POST al punto final /v3/contactdb/recipients , pasando los campos personalizados como el cuerpo de la solicitud. Luego verificamos si el cliente de SendGrid eligió agregar usuarios a un segmento de lista determinado y agregarlos al segmento dado, si ese es el caso. La respuesta a la solicitud de la API de creación de contactos incluye los ID de contacto de los contactos recién creados como una matriz llamada persisted_recipients . Usando el ID de contacto proporcionado en la respuesta y el ID de lista proporcionado por el cliente de SendGrid, luego hacemos una solicitud POST al punto final /v3/contactdb/lists/{listId}/recipients/{contactID} .