Creazione di un widget di abbonamento con Node.js

Di recente ho sviluppato un widget di abbonamento open source creato utilizzando la libreria API Node.js di SendGrid. Puoi trovare maggiori informazioni sulle motivazioni e le capacità del progetto nella pagina README del repository. Sebbene questa non sia una libreria SendGrid ufficialmente supportata, l'obiettivo era quello di creare un widget flessibile e facilmente implementabile che qualsiasi cliente SendGrid può incorporare in una pagina HTML che raccoglie gli indirizzi e-mail dei clienti esistenti e potenziali e altre informazioni utili da archiviare all'interno delle loro campagne di marketing Contatti . Dopo che i clienti hanno inserito le informazioni nel modulo, ricevono un'e-mail con un collegamento per confermare il loro indirizzo e-mail e, facendo clic sul collegamento, il destinatario verrà aggiunto all'elenco dei contatti del cliente SendGrid fornito.

Oltre a quella funzionalità di base, il widget può anche:

• Aggiungi un utente a un segmento di elenco specifico, se specificato
• Includere campi personalizzati nel modulo, i cui input verranno archiviati con un determinato contatto
• Invia l'e-mail di conferma con un modello di e-mail esistente, se specificato

Questo è stato un progetto interessante perché ha utilizzato una gamma di funzionalità e endpoint API di SendGrid, tra cui:

• API di invio posta
• Contatti API
• Webhook per eventi
• Modelli transazionali

Questo post discuterà il processo di creazione del widget e alcuni dei processi di pensiero che sono andati alla sua implementazione e progettazione.

Panoramica della progettazione del widget

Il widget di abbonamento funziona consentendo ai clienti SendGrid di distribuire un'app su Heroku utilizzando il pulsante di distribuzione di Heroku. Per creare il widget utilizzando il pulsante di implementazione, i clienti SendGrid avranno bisogno di un account Heroku (puoi creare un account gratuito qui). Tuttavia, il widget può teoricamente essere distribuito a qualsiasi provider di hosting. Il cliente SendGrid può quindi modificare l'endpoint a cui il modulo personalizzato invia la sua richiesta POST all'URL dell'app Heroku appena distribuita. Quando un utente invia il modulo, la richiesta verrà quindi elaborata dall'app ospitata su Heroku.

L'app stessa è un'applicazione Node/Express di base con due percorsi che gestiscono il processo di registrazione. Il percorso confirmEmail invia agli utenti un'e-mail con un collegamento per confermare il loro indirizzo e-mail e utilizza un modello transazionale personalizzato (se specificato). Il percorso di registrazione aggiunge un utente all'elenco dei contatti del cliente SendGrid e, se specificato, aggiunge anche l'utente a un segmento di elenco personalizzato. Il percorso di registrazione gestisce anche tutti i campi personalizzati che un cliente SendGrid sceglie di includere nel proprio modulo personalizzato.

ConfermaIndirizzo email

La route confirmEmail è semplicemente una richiesta di post all'endpoint POST v3/mail/send utilizzando la libreria di supporto Node.js di SendGrid. In caso di risposta positiva, l'utente verrà reindirizzato a una pagina in cui gli viene chiesto di controllare la posta in arrivo per l'e-mail di conferma. In caso di risposta non riuscita, l'utente verrà reindirizzato a una pagina che chiede loro di inserire nuovamente il proprio indirizzo e-mail. Ad esempio, ciò può accadere se un utente immette un indirizzo e-mail non valido.

La funzione prepareEmail restituisce un oggetto JSON che fungerà da corpo della richiesta API.

Il processo di creazione dell'oggetto di base è abbastanza semplice. In esso, l'indirizzo email del destinatario viene inserito dall'invio del modulo. Tuttavia, ci sono alcune cose interessanti che accadono nel processo di creazione dell'oggetto.

Argomenti personalizzati di base

Due argomenti personalizzati sono inclusi nelle personalizzazioni: 1) type, che è impostato su 'opt-in', e 2) time_sent, che è impostato sull'ora corrente. Questi argomenti personalizzati vengono passati nell'intestazione dell'e-mail e verranno utilizzati per determinare se un utente deve essere aggiunto a un elenco nel processo di conferma.

ID modello

Dopo la creazione iniziale dell'oggetto, controlliamo se il cliente SendGrid ha scelto di utilizzare un modello personalizzato nel file delle impostazioni e lo aggiungiamo all'oggetto in tal caso (null è il valore predefinito). Un modello personalizzato avrà la priorità sul testo dell'e-mail incluso nel corpo, quindi se l'ID del modello viene lasciato come valore null, il messaggio verrà impostato automaticamente sul testo dell'e-mail fornito.

Inserisci sostituzione collegamento

Includiamo una sostituzione per il termine insert_link . Ciò sarà rilevante solo se il cliente SendGrid sceglie di utilizzare un modello transazionale. In tal caso, il termine insert_link verrà sostituito dal collegamento effettivo utilizzato per confermare l'e-mail di un utente e reindirizzarlo alla pagina di successo appropriata.

Invio degli input del modulo come argomenti personalizzati

Infine, aggiungiamo i valori che l'utente finale ha inviato al corpo dell'e-mail come argomenti personalizzati. L'invio dell'utente finale viene passato al percorso confirmEmail iniziale come corpo della richiesta, che viene quindi passato alla funzione prepareEmail come parametro. Il corpo della richiesta contiene un oggetto con un insieme di chiavi, coppie di valori che rappresentano il nome dell'input e il valore inviato dall'utente. Quindi eseguiamo il ciclo delle chiavi dell'oggetto aggiungendo un argomento personalizzato all'e-mail per ciascuna chiave, coppia di valori. Questi valori verranno aggiunti alle informazioni di contatto dell'utente finale nel processo di creazione del contatto.

Percorso di iscrizione

Il percorso di registrazione viene attivato da un webhook di eventi che effettua una richiesta POST ogni volta che un utente fa clic sul collegamento fornito nell'e-mail di conferma che riceve. Questo percorso deve occuparsi di alcuni elementi nel processo di creazione del contatto. Dobbiamo fare quanto segue:

• Controlla se il modulo conteneva campi personalizzati
• Verifica se i campi personalizzati esistono nell'account del cliente SendGrid e creali se i campi non esistono
• Assicurati che si tratti di un'e - mail di attivazione come specificato dal tipo nel processo di creazione dell'e-mail
• Assicurati che il link sia stato cliccato entro 24 ore
• Crea il contatto nell'account del cliente SendGrid
• Aggiungi il nuovo contatto a un segmento di elenco specifico, se ne è stato fornito uno

Gestione dei campi personalizzati

Il percorso di registrazione chiama la funzione addUserToList . Questa funzione viene chiamata all'interno del percorso in modo da poter inviare lo stato al termine del processo all'interno di una richiamata. La prima cosa che facciamo all'interno di questa funzione è creare un oggetto contenente tutti i campi personalizzati contenuti nel modulo e un array contenente i campi personalizzati che non sono forniti di default per tutti i contatti (email, nome, cognome).

Una richiesta POST attivata da webhook di eventi contiene tutte le informazioni relative all'e-mail, comprese le intestazioni dell'e-mail, l'oggetto, il testo, ecc. Tutto ciò che ci interessa sono gli argomenti personalizzati che sono stati forniti, che sono contenuti come oggetto all'interno del primo elemento dell'organismo di richiesta. Tuttavia, l'oggetto contiene anche una varietà di campi non necessari per il processo di gestione dei campi personalizzati, che posizioniamo in un array chiamato ignoreFields .

Quindi scorrere gli argomenti personalizzati per creare l'oggetto e l'array con i campi personalizzati menzionati in precedenza. Passeremo l'oggetto completo dei campi personalizzati nel corpo nel processo di creazione del contatto, ma non finché non avremo aggiunto i campi personalizzati, se necessario, in un passaggio precedente.

Chiamiamo quindi la funzione checkAndAddCustomFields con due parametri, l'array del campo personalizzato e un callback, che è dove ci occuperemo della creazione del contatto. È importante prima controllare e aggiungere eventuali campi personalizzati perché l'endpoint genererà un errore se si tenta di creare un contatto con un campo personalizzato che non esiste.

La funzione checkAndAddCustomFields effettua prima una richiesta GET all'endpoint /v3/contactdb/custom_fields per recuperare i campi esistenti del database dei contatti. Quindi confronta l'elenco dei campi personalizzati esistenti con l'elenco dei campi inviati che sono stati passati come parametro e, se sono presenti campi inviati che non sono inclusi nell'elenco dei campi personalizzati esistenti, quei nuovi campi vengono aggiunti all'array fieldsToCreate . Se non ci sono campi da creare, viene chiamata la funzione di callback. Tuttavia, se ci sono dei campi da creare, facciamo una richiesta POST all'endpoint /v3/contactdb/custom_fields per ogni nuovo campo personalizzato che verrà creato.

Creazione del nuovo contatto

Una volta creati i campi personalizzati, creiamo un nuovo contatto effettuando una richiesta POST all'endpoint /v3/contactdb/recipients , passando i campi personalizzati come corpo della richiesta. Verifichiamo quindi se il cliente SendGrid ha scelto di aggiungere utenti a un determinato segmento di elenco e di aggiungerli al segmento specificato, in tal caso. La risposta alla richiesta dell'API di creazione del contatto include gli ID contatto dei contatti appena creati come un array chiamato persistented_recipients . Utilizzando l'ID contatto fornito nella risposta e l'ID elenco forniti dal cliente SendGrid, effettuiamo quindi una richiesta POST all'endpoint /v3/contactdb/lists/{listId}/recipients/{contactID} .