Tworzenie widżetu subskrypcji za pomocą Node.js

Niedawno opracowałem widżet subskrypcji open source zbudowany przy użyciu biblioteki API Node.js SendGrid. Więcej informacji o motywacjach i możliwościach projektu znajdziesz na stronie README repozytorium. Chociaż nie jest to oficjalnie obsługiwana biblioteka SendGrid, celem było stworzenie łatwego do wdrożenia, elastycznego widżetu, który każdy klient SendGrid może włączyć do strony HTML, która zbiera adresy e-mail istniejących i potencjalnych klientów oraz inne przydatne informacje do przechowywania w kontaktach kampanii marketingowych . Po wprowadzeniu informacji do formularza klienci otrzymują wiadomość e-mail z linkiem potwierdzającym ich adres e-mail, a po kliknięciu w link odbiorca zostanie dodany do danej listy kontaktów klienta SendGrid.

Poza tą podstawową funkcjonalnością widżet może również:

• Dodaj użytkownika do określonego segmentu listy, jeśli jest określony
• Uwzględnij w formularzu pola niestandardowe, których dane wejściowe zostaną zapisane z danym kontaktem
• Wyślij wiadomość e-mail z potwierdzeniem z istniejącym szablonem wiadomości e-mail, jeśli jest określony

Był to interesujący projekt, ponieważ wykorzystywał szereg możliwości SendGrid i punktów końcowych API, w tym:

• API wysyłania poczty
• Kontakty API
• Webhook wydarzenia
• Szablony transakcyjne

W tym poście omówimy proces tworzenia widżetu i niektóre procesy myślowe, które zaszły w jego implementacji i projektowaniu.

Przegląd projektowania widżetów

Widżet subskrypcji działa, umożliwiając klientom SendGrid wdrożenie aplikacji w Heroku za pomocą przycisku wdrażania Heroku. Aby utworzyć widżet za pomocą przycisku wdrażania, klienci SendGrid będą potrzebować konta Heroku (tutaj możesz utworzyć bezpłatne konto). Widget można jednak teoretycznie wdrożyć u dowolnego dostawcy hostingu. Klient SendGrid może następnie zmienić punkt końcowy, do którego niestandardowy formularz wysyła żądanie POST na adres URL nowo wdrożonej aplikacji Heroku. Gdy użytkownik prześle formularz, żądanie zostanie przetworzone przez aplikację hostowaną w Heroku.

Sama aplikacja jest podstawową aplikacją typu Node/Express z dwiema trasami obsługującymi proces rejestracji. Trasa ConfirmEmail wysyła użytkownikom wiadomość e-mail z łączem do potwierdzenia ich adresu e-mail i używa niestandardowego szablonu transakcyjnego (jeśli jest określony). Trasa rejestracji dodaje użytkownika do listy kontaktów klienta SendGrid i, jeśli określono, dodaje użytkownika do niestandardowego segmentu listy. Trasa rejestracji obsługuje również wszelkie pola niestandardowe, które klient SendGrid zdecyduje się uwzględnić w swoim formularzu niestandardowym.

Potwierdź trasę e-mail

Trasa ConfirmEmail jest po prostu żądaniem pocztowym do punktu końcowego v3/mail/send POST przy użyciu biblioteki pomocniczej Node.js SendGrid. Po pomyślnej odpowiedzi użytkownik zostanie przekierowany na stronę z prośbą o sprawdzenie swojej skrzynki odbiorczej pod kątem wiadomości e-mail z potwierdzeniem. W przypadku nieudanej odpowiedzi użytkownik zostanie przekierowany na stronę z prośbą o ponowne wprowadzenie adresu e-mail. Na przykład może się to zdarzyć, jeśli użytkownik wprowadzi nieprawidłowy adres e-mail.

Funkcja PrepareEmail zwraca obiekt JSON, który będzie służył jako treść żądania API.

Podstawowy proces tworzenia obiektów jest dość prosty. W nim adres e-mail odbiorcy jest wstawiany z przesłania formularza. Jednak w procesie tworzenia obiektu dzieje się kilka ciekawych rzeczy.

Podstawowe argumenty niestandardowe

W personalizacjach znajdują się dwa niestandardowe argumenty: 1) type, który jest ustawiony na „opt-in” i 2) time_sent, który jest ustawiony na bieżący czas. Te niestandardowe argumenty są przekazywane w nagłówku wiadomości e-mail i zostaną wykorzystane do określenia, czy użytkownik powinien zostać dodany do listy w procesie potwierdzania.

Identyfikator szablonu

Po początkowym utworzeniu obiektu sprawdzamy, czy klient SendGrid wybrał użycie niestandardowego szablonu w pliku ustawień i jeśli tak jest, dodajemy go do obiektu (wartość domyślna to null). Szablon niestandardowy będzie miał priorytet nad tekstem e-maila zawartym w treści, więc jeśli identyfikator szablonu zostanie pozostawiony jako wartość null, wiadomość domyślnie będzie zawierać podany tekst e-maila.

Wstaw zastępowanie linków

Wstawiamy podstawienie terminu insert_link . Będzie to miało znaczenie tylko wtedy, gdy klient SendGrid zdecyduje się użyć szablonu transakcyjnego. W takim przypadku termin insert_link zostanie zastąpiony faktycznym linkiem używanym do potwierdzania adresu e-mail użytkownika i przekierowywania go na odpowiednią stronę sukcesu.

Wysyłanie danych wejściowych formularza jako niestandardowych argumentów

Na koniec dodajemy wartości, które użytkownik końcowy przesłał do treści wiadomości e-mail jako argumenty niestandardowe. Zgłoszenie użytkownika końcowego jest przekazywane do początkowej trasy ConfirmEmail jako treść żądania, którą następnie przekazujemy do funkcji PrepareEmail jako parametr. Treść żądania zawiera obiekt z zestawem kluczy, par wartości reprezentujących nazwę wejścia oraz wartość przesłaną przez użytkownika. Następnie przechodzimy przez klucze obiektów w pętli, dodając do wiadomości e-mail niestandardowy argument dla każdego klucza i pary wartości. Te wartości zostaną dodane do informacji kontaktowych użytkownika końcowego w procesie tworzenia kontaktu.

Trasa rejestracji

Trasa rejestracji jest wyzwalana przez webhook zdarzenia, który wysyła żądanie POST za każdym razem, gdy użytkownik kliknie link podany w otrzymanej wiadomości e-mail z potwierdzeniem. Ta trasa musi zająć się kilkoma elementami w procesie tworzenia kontaktu. Musimy wykonać następujące czynności:

• Sprawdź, czy formularz zawiera jakieś pola niestandardowe
• Sprawdź, czy pola niestandardowe istnieją na koncie klienta SendGrid i utwórz je, jeśli pola nie istnieją
• Upewnij się, że jest to e-mail opt-in określony przez typ w procesie tworzenia wiadomości e-mail
• Upewnij się, że link został kliknięty w ciągu 24 godzin
• Utwórz kontakt na koncie klienta SendGrid
• Dodaj nowy kontakt do określonego segmentu listy, jeśli taki został podany

Obsługa pól niestandardowych

Trasa rejestracji wywołuje funkcję addUserToList . Ta funkcja jest wywoływana w ramach trasy, dzięki czemu możemy wysłać status po zakończeniu procesu w wywołaniu zwrotnym. Pierwszą rzeczą, jaką robimy wewnątrz tej funkcji, jest utworzenie obiektu zawierającego wszystkie pola niestandardowe zawarte w formularzu oraz tablicę zawierającą pola niestandardowe, które nie są domyślnie udostępniane dla wszystkich kontaktów (e-mail, imię, nazwisko).

Żądanie POST wyzwalane przez elementy webhook zdarzenia zawiera wszystkie informacje związane z wiadomościami e-mail, w tym nagłówki, temat, tekst itp. wiadomości e-mail. Wszystko, na czym nam zależy, to dostarczone argumenty niestandardowe, które są zawarte jako obiekt w pierwszym elemencie treści żądania. Jednak obiekt zawiera również różne pola, których nie potrzebujemy w procesie obsługi pól niestandardowych, które umieszczamy w tablicy o nazwie ignoreFields .

Następnie przechodzimy w pętli przez niestandardowe argumenty, aby utworzyć obiekt i tablicę ze wspomnianymi wcześniej niestandardowymi polami. Przekażemy pełny obiekt pól niestandardowych do treści w procesie tworzenia kontaktu, ale nie dopóki nie dodamy pól niestandardowych, jeśli to konieczne, w poprzednim kroku.

Następnie wywołujemy funkcję checkAndAddCustomFields z dwoma parametrami, tablicą pól niestandardowych i wywołaniem zwrotnym, w którym zajmiemy się utworzeniem kontaktu. Ważne jest, aby najpierw sprawdzić i dodać dowolne pola niestandardowe, ponieważ punkt końcowy zgłosi błąd, jeśli spróbujesz utworzyć kontakt z niestandardowym polem, które nie istnieje.

Funkcja checkAndAddCustomFields najpierw wysyła żądanie GET do punktu końcowego /v3/contactdb/custom_fields w celu pobrania istniejących pól bazy danych kontaktów. Następnie porównuje listę istniejących pól niestandardowych z listą przesłanych pól, które zostały przekazane jako parametr, a jeśli istnieją jakieś przesłane pola, których nie ma na liście istniejących pól niestandardowych, te nowe pola są dodawane do tablicy fieldsToCreate . Jeśli nie ma żadnych pól do utworzenia, wywoływana jest funkcja wywołania zwrotnego. Jeśli jednak są jakieś pola do utworzenia, wysyłamy żądanie POST do punktu końcowego /v3/contactdb/custom_fields dla każdego nowego niestandardowego pola, które zostanie utworzone.

Tworzenie nowego kontaktu

Po utworzeniu pól niestandardowych tworzymy nowy kontakt, wysyłając żądanie POST do punktu końcowego /v3/contactdb/recipients , przekazując pola niestandardowe jako treść żądania. Następnie sprawdzamy, czy klient SendGrid zdecydował się dodać użytkowników do danego segmentu listy i dodać ich do danego segmentu, jeśli tak jest. Odpowiedź na żądanie interfejsu API tworzenia kontaktów zawiera identyfikatory kontaktów nowo utworzonych kontaktów w postaci tablicy o nazwie persisted_recipients . Korzystając z identyfikatora kontaktu podanego w odpowiedzi i identyfikatora listy dostarczonego przez klienta SendGrid, wykonujemy żądanie POST do punktu końcowego /v3/contactdb/lists/{listId}/recipients/{contactID} .