Créer un widget d'abonnement avec Node.js

J'ai récemment développé un widget d'abonnement open source construit à l'aide de la bibliothèque d'API Node.js de SendGrid. Vous pouvez trouver plus d'informations sur les motivations et les capacités du projet sur la page README du référentiel. Bien qu'il ne s'agisse pas d'une bibliothèque SendGrid officiellement prise en charge, l'objectif était de créer un widget flexible et facilement déployable que tout client SendGrid peut incorporer dans une page HTML qui collecte les adresses e-mail des clients existants et potentiels et d'autres informations utiles à stocker dans leurs campagnes marketing Contacts . Une fois que les clients ont entré des informations dans le formulaire, ils reçoivent un e-mail avec un lien pour confirmer leur adresse e-mail, et en cliquant sur le lien, le destinataire sera ajouté à la liste de contacts du client SendGrid donné.

Au-delà de cette fonctionnalité de base, le widget peut également :

• Ajouter un utilisateur à un segment de liste spécifique, si spécifié
• Inclure des champs personnalisés dans le formulaire, dont les entrées seront stockées avec un contact donné
• Envoyer l'e-mail de confirmation avec un modèle d'e-mail existant, si spécifié

Il s'agissait d'un projet intéressant car il utilisait une gamme de fonctionnalités et de points de terminaison API de SendGrid, notamment :

• API d'envoi de courrier
• API de contacts
• Webhook d'événement
• Modèles transactionnels

Cet article discutera du processus de création du widget et de certains des processus de réflexion qui ont contribué à sa mise en œuvre et à sa conception.

Aperçu de la conception des widgets

Le widget d'abonnement fonctionne en permettant aux clients SendGrid de déployer une application sur Heroku à l'aide du bouton de déploiement de Heroku. Pour créer le widget à l'aide du bouton de déploiement, les clients SendGrid auront besoin d'un compte Heroku (vous pouvez créer un compte gratuit ici). Cependant, le widget peut théoriquement être déployé sur n'importe quel fournisseur d'hébergement. Le client SendGrid peut ensuite modifier le point de terminaison auquel le formulaire personnalisé envoie sa demande POST à ​​l'URL de l'application Heroku nouvellement déployée. Lorsqu'un utilisateur soumet le formulaire, la demande est alors traitée par l'application hébergée sur Heroku.

L'application elle-même est une application Node/Express de base avec deux itinéraires gérant le processus d'inscription. La route confirmEmail envoie aux utilisateurs un e-mail avec un lien pour confirmer leur adresse e-mail et utilise un modèle transactionnel personnalisé (le cas échéant). La route d' inscription ajoute un utilisateur à la liste de contacts du client SendGrid et, si spécifié, ajoute également l'utilisateur à un segment de liste personnalisé. La route d' inscription gère également tous les champs personnalisés qu'un client SendGrid choisit d'inclure dans son formulaire personnalisé.

Confirmer l'itinéraire de l'e-mail

La route confirmEmail est simplement une demande de publication au point de terminaison v3/mail/send POST à ​​l'aide de la bibliothèque d'assistance Node.js de SendGrid. En cas de réponse positive, l'utilisateur sera redirigé vers une page lui demandant de vérifier sa boîte de réception pour l'e-mail de confirmation. En cas de réponse infructueuse, l'utilisateur sera redirigé vers une page lui demandant de saisir à nouveau son adresse e-mail. Par exemple, cela peut se produire si un utilisateur saisit une adresse e-mail invalide.

La fonction prepareEmail renvoie un objet JSON qui servira de corps de la requête API.

Le processus de création d'objet de base est assez simple. Dans celui-ci, l'adresse e-mail du destinataire est insérée à partir de la soumission du formulaire. Cependant, il se passe quelques choses intéressantes dans le processus de création d'objet.

Arguments personnalisés de base

Deux arguments personnalisés sont inclus dans les personnalisations : 1) type, qui est défini sur "opt-in", et 2) time_sent, qui est défini sur l'heure actuelle. Ces arguments personnalisés sont transmis dans l'en-tête de l'e-mail et seront utilisés pour déterminer si un utilisateur doit être ajouté à une liste lors du processus de confirmation.

ID de modèle

Après la création initiale de l'objet, nous vérifions si le client SendGrid a choisi d'utiliser un modèle personnalisé dans le fichier de paramètres et l'ajoutons à l'objet si tel est le cas (null est la valeur par défaut). Un modèle personnalisé aura priorité sur le texte de l'e-mail inclus dans le corps, donc si l'ID du modèle est laissé comme valeur nulle, le message utilisera par défaut le texte de l'e-mail fourni.

Insérer une substitution de lien

Nous incluons une substitution pour le terme insert_link . Cela ne sera pertinent que si le client SendGrid choisit d'utiliser un modèle transactionnel. Si tel est le cas, le terme insert_link sera remplacé par le lien réel utilisé pour confirmer l'e-mail d'un utilisateur et le rediriger vers la page de réussite appropriée.

Envoi des entrées de formulaire en tant qu'arguments personnalisés

Enfin, nous ajoutons les valeurs que l'utilisateur final a soumises au corps de l'e-mail en tant qu'arguments personnalisés. La soumission de l'utilisateur final est transmise à la route confirmEmail initiale en tant que corps de la demande, que nous transmettons ensuite à la fonction prepareEmail en tant que paramètre. Le corps de la requête contient un objet avec un ensemble de paires de clés et de valeurs représentant le nom de l'entrée et la valeur soumise par l'utilisateur. Nous parcourons ensuite les clés d'objet en ajoutant un argument personnalisé à l'e-mail pour chaque clé, paire de valeurs. Ces valeurs seront ajoutées aux informations de contact de l'utilisateur final lors du processus de création de contact.

Itinéraire d'inscription

La route d'inscription est déclenchée par un webhook d'événement qui effectue une demande POST chaque fois qu'un utilisateur clique sur le lien fourni dans l'e-mail de confirmation qu'il reçoit. Cette route doit prendre en charge quelques éléments dans le processus de création de contact. Nous devons faire ce qui suit :

• Vérifiez si le formulaire contient des champs personnalisés
• Vérifiez si les champs personnalisés existent dans le compte du client SendGrid et créez-les si les champs n'existent pas
• Assurez-vous qu'il s'agit d'un e-mail opt-in tel que spécifié par le type dans le processus de création d'e-mail
• Assurez-vous que le lien a été cliqué dans les 24 heures
• Créer le contact dans le compte client SendGrid
• Ajouter le nouveau contact à un segment de liste spécifique si celui-ci a été fourni

Gestion des champs personnalisés

La route d' inscription appelle la fonction addUserToList . Cette fonction est appelée dans la route afin que nous puissions envoyer le statut une fois le processus terminé à l'intérieur d'un rappel. La première chose que nous faisons à l'intérieur de cette fonction est de créer un objet contenant tous les champs personnalisés que contient le formulaire et un tableau contenant les champs personnalisés qui ne sont pas fournis par défaut pour tous les contacts (email, first_name, last_name).

Une requête POST déclenchée par des webhooks d'événement contient toutes les informations relatives à l'e-mail, y compris les en-têtes, l'objet, le texte, etc. de l'e-mail. Tout ce qui nous intéresse, ce sont les arguments personnalisés qui ont été fournis, qui sont contenus en tant qu'objet dans le premier élément du corps de la requête. Cependant, l'objet contient également une variété de champs dont nous n'avons pas besoin pour le processus de gestion des champs personnalisés, que nous plaçons dans un tableau appelé ignoreFields .

Nous parcourons ensuite les arguments personnalisés pour créer l'objet et le tableau avec les champs personnalisés mentionnés précédemment. Nous transmettrons l'objet complet des champs personnalisés dans le corps du processus de création de contact, mais pas avant d'avoir ajouté des champs personnalisés, si nécessaire, lors d'une étape précédente.

Nous appelons ensuite la fonction checkAndAddCustomFields avec deux paramètres, le tableau de champs personnalisés et un rappel, c'est là que nous nous occuperons de créer le contact. Il est important de vérifier et d'ajouter d'abord tous les champs personnalisés, car le point de terminaison générera une erreur si vous essayez de créer un contact avec un champ personnalisé qui n'existe pas.

La fonction checkAndAddCustomFields envoie d' abord une requête GET au point de terminaison /v3/contactdb/custom_fields pour récupérer les champs existants de la base de données de contacts. Il compare ensuite la liste des champs personnalisés existants avec la liste des champs soumis qui ont été passés en tant que paramètre, et s'il y a des champs soumis qui ne sont pas inclus dans la liste des champs personnalisés existants, ces nouveaux champs sont ajoutés au tableau fieldsToCreate . S'il n'y a pas de champs à créer, la fonction de rappel est appelée. Cependant, s'il y a des champs à créer, nous faisons une requête POST au point de terminaison /v3/contactdb/custom_fields pour chaque nouveau champ personnalisé qui sera créé.

Création du nouveau contact

Une fois les champs personnalisés créés, nous créons un nouveau contact en faisant une requête POST au point de terminaison /v3/contactdb/recipients , en transmettant les champs personnalisés comme corps de la requête. Nous vérifions ensuite si le client SendGrid a choisi d'ajouter des utilisateurs à un segment de liste donné et de les ajouter au segment donné, si tel est le cas. La réponse à la demande d'API de création de contact inclut le ou les ID de contact du ou des contacts nouvellement créés sous la forme d'un tableau appelé persisted_recipients . À l'aide de l'ID de contact fourni dans la réponse et de l'ID de liste fourni par le client SendGrid, nous envoyons ensuite une requête POST au point de terminaison /v3/contactdb/lists/{listId}/recipients/{contactID} .