Crearea unui widget de abonament cu Node.js

Am dezvoltat recent un widget de abonament open source construit folosind biblioteca API Node.js a SendGrid. Puteți găsi mai multe informații despre motivațiile și capacitățile proiectului pe pagina README a depozitului. Deși aceasta nu este o bibliotecă SendGrid acceptată oficial, scopul a fost de a crea un widget ușor de implementat și flexibil pe care orice client SendGrid îl poate încorpora într-o pagină HTML care colectează adresele de e-mail ale clienților existenți și potențiali și alte informații utile pentru a le stoca în campaniile de marketing. . După ce clienții introduc informații în formular, primesc un e-mail cu un link pentru a-și confirma adresa de e-mail, iar după ce fac clic pe link, destinatarul va fi adăugat la lista de contacte a clientului SendGrid dat.

Dincolo de această funcționalitate de bază, widget-ul poate, de asemenea:

• Adăugați un utilizator la un anumit segment de listă, dacă este specificat
• Includeți câmpuri personalizate în formular, ale căror intrări vor fi stocate cu un anumit contact
• Trimiteți e-mailul de confirmare cu un șablon de e-mail existent, dacă este specificat

Acesta a fost un proiect interesant, deoarece a folosit o serie de capabilități și puncte finale API ale SendGrid, inclusiv:

• Mail Send API
• Contacts API
• Webhook pentru evenimente
• Șabloane tranzacționale

Această postare va discuta despre procesul de creare a widget-ului și unele dintre procesele de gândire care au intrat în implementarea și proiectarea acestuia.

Prezentare generală a designului widgetului

Widgetul de abonament funcționează permițând clienților SendGrid să implementeze o aplicație în Heroku folosind butonul de implementare al lui Heroku. Pentru a crea widget-ul folosind butonul de implementare, clienții SendGrid vor avea nevoie de un cont Heroku (puteți crea un cont gratuit aici). Cu toate acestea, widget-ul poate fi, teoretic, implementat oricărui furnizor de găzduire. Clientul SendGrid poate schimba apoi punctul final la care formularul personalizat își face cererea POST la adresa URL a aplicației Heroku nou implementată. Când un utilizator trimite formularul, cererea va fi apoi procesată de aplicația găzduită pe Heroku.

Aplicația în sine este o aplicație de bază Node/Express cu două rute care gestionează procesul de înscriere. Ruta confirmEmail trimite utilizatorilor un e-mail cu un link pentru a le confirma adresa de e-mail și utilizează un șablon tranzacțional personalizat (dacă este specificat unul). Ruta de înscriere adaugă un utilizator la lista de contacte a clientului SendGrid și, dacă este specificat, adaugă și utilizatorul la un segment personalizat de listă. Ruta de înscriere gestionează, de asemenea, orice câmpuri personalizate pe care un client SendGrid alege să includă în formularul personalizat.

Confirmați traseul e-mailului

Ruta confirmEmail este pur și simplu o solicitare de postare către punctul final POST v3/mail/send folosind biblioteca de ajutor Node.js a SendGrid. La un răspuns de succes, utilizatorul va fi redirecționat către o pagină în care îi va cere să verifice căsuța de e-mail pentru e-mailul de confirmare. La un răspuns nereușit, utilizatorul va fi redirecționat către o pagină care îi cere să introducă din nou adresa de e-mail. De exemplu, acest lucru se poate întâmpla dacă un utilizator ar introduce o adresă de e-mail nevalidă.

Funcția prepareEmail returnează un obiect JSON care va servi drept corp al cererii API.

Procesul de bază de creare a obiectelor este destul de simplu. În acesta, adresa de e-mail a destinatarului este inserată de la trimiterea formularului. Cu toate acestea, se întâmplă câteva lucruri interesante în procesul de creare a obiectelor.

Argumente personalizate de bază

Două argumente personalizate sunt incluse în personalizări: 1) type, care este setat la „opt-in” și 2) time_sent, care este setat la ora curentă. Aceste argumente personalizate sunt transmise în antetul e-mailului și vor fi utilizate pentru a determina dacă un utilizator ar trebui adăugat la o listă în procesul de confirmare.

ID șablon

După crearea inițială a obiectului, verificăm dacă clientul SendGrid a ales să utilizeze un șablon personalizat în fișierul de setări și îl adăugăm la obiect dacă acesta este cazul (null este valoarea implicită). Un șablon personalizat va avea prioritate față de textul de e-mail inclus în corp, așa că dacă ID-ul șablonului este lăsat ca valoare nulă, mesajul va fi implicit la textul de e-mail furnizat.

Introduceți înlocuirea linkului

Includem o înlocuire pentru termenul insert_link . Acest lucru va fi relevant doar dacă clientul SendGrid alege să folosească un șablon tranzacțional. Dacă acesta este cazul, termenul insert_link va fi înlocuit cu linkul real care este folosit pentru a confirma e-mailul unui utilizator și a-l redirecționa către pagina de succes corespunzătoare.

Trimiterea intrărilor de formular ca argumente personalizate

În cele din urmă, adăugăm valorile pe care utilizatorul final le-a trimis în corpul e-mailului ca argumente personalizate. Trimiterea utilizatorului final este transmisă în ruta inițială confirmEmail ca corp de solicitare, pe care apoi o trecem în funcția prepareEmail ca parametru. Corpul cererii conține un obiect cu un set de chei, perechi valori reprezentând numele intrării și valoarea trimisă de utilizator. Apoi parcurgem cheile obiectului adăugând un argument personalizat la e-mail pentru fiecare pereche de cheie, valoare. Aceste valori vor fi adăugate la informațiile de contact ale utilizatorului final în procesul de creare a contactului.

Traseu de înscriere

Ruta de înscriere este declanșată de un webhook de eveniment care face o solicitare POST de fiecare dată când un utilizator face clic pe linkul furnizat în e-mailul de confirmare pe care îl primește. Această rută trebuie să aibă grijă de câteva elemente în procesul de creare a contactului. Trebuie să facem următoarele:

• Verificați dacă formularul conținea câmpuri personalizate
• Verificați dacă câmpurile personalizate există în contul clientului SendGrid și creați-le dacă câmpurile nu există
• Asigurați-vă că acesta este un e -mail de înscriere, așa cum este specificat de tipul din procesul de creare a e-mailului
• Asigurați-vă că ați făcut clic pe link în 24 de ore
• Creați contactul în contul clientului SendGrid
• Adăugați noul contact la un anumit segment de listă, dacă a fost furnizat unul

Gestionarea câmpurilor personalizate

Ruta de înscriere apelează funcția addUserToList . Această funcție este apelată în cadrul rutei, astfel încât să putem trimite starea după finalizarea procesului în interiorul unui apel invers. Primul lucru pe care îl facem în interiorul acestei funcții este să creăm un obiect care să conțină toate câmpurile personalizate pe care le conține formularul și o matrice care conține câmpurile personalizate care nu sunt furnizate implicit pentru toate persoanele de contact (e-mail, prenume, nume).

O solicitare POST declanșată de webhook-uri de eveniment conține toate informațiile legate de e-mail, inclusiv anteturile, subiectul, textul etc. ale e-mailului. Tot ce ne pasă sunt argumentele personalizate care au fost furnizate, care sunt conținute ca obiect în primul element. a organului de cerere. Cu toate acestea, obiectul conține și o varietate de câmpuri de care nu avem nevoie pentru procesul de gestionare a câmpurilor personalizate, pe care le plasăm într-o matrice numită ignoreFields .

Apoi parcurgem argumentele personalizate pentru a crea obiectul și matricea cu câmpurile personalizate menționate mai devreme. Vom trece obiectul câmpuri personalizate complet în corp în procesul de creare a contactului, dar nu până când vom adăuga câmpuri personalizate, după cum este necesar, într-un pas anterior.

Apoi apelăm funcția checkAndAddCustomFields cu doi parametri, matricea de câmp personalizat și un apel invers, care este locul în care ne vom ocupa de crearea contactului. Este important să verificați și să adăugați mai întâi orice câmpuri personalizate, deoarece punctul final va genera o eroare dacă încercați să creați un contact cu un câmp personalizat care nu există.

Funcția checkAndAddCustomFields face mai întâi o solicitare GET către punctul final /v3/contactdb/custom_fields pentru a prelua câmpurile existente ale bazei de date de contacte. Apoi compară lista câmpurilor personalizate existente cu lista câmpurilor trimise care au fost transmise ca parametru și, dacă există câmpuri trimise care nu sunt incluse în lista câmpurilor personalizate existente, acele câmpuri noi sunt adăugate la matricea fieldsToCreate . Dacă nu există câmpuri de creat, se apelează funcția de apel invers. Cu toate acestea, dacă există câmpuri de creat, facem o solicitare POST către punctul final /v3/contactdb/custom_fields pentru fiecare câmp personalizat nou care va fi creat.

Crearea noului contact

Odată ce câmpurile personalizate au fost create, creăm o nouă persoană de contact făcând o solicitare POST către punctul final /v3/contactdb/recipients , trecând câmpurile personalizate ca corp cererii. Verificăm apoi dacă clientul SendGrid a ales să adauge utilizatori la un anumit segment de listă și să îi adauge la segmentul dat, dacă acesta este cazul. Răspunsul la solicitarea API de creare a contactului include ID-urile de contact ale contactelor nou create ca o matrice numită persisted_recipients . Folosind ID-ul de contact furnizat în răspunsul și ID-ul listei furnizate de clientul SendGrid, facem apoi o solicitare POST către punctul final /v3/contactdb/lists/{listId}/recipients/{contactID} .