Erstellen eines Abonnement-Widgets mit Node.js

Ich habe kürzlich ein Open-Source-Abonnement-Widget entwickelt, das mit der Node.js-API-Bibliothek von SendGrid erstellt wurde. Weitere Informationen zu den Beweggründen und Möglichkeiten des Projekts finden Sie auf der README-Seite des Repositoriums. Obwohl dies keine offiziell unterstützte SendGrid-Bibliothek ist, war das Ziel, ein einfach bereitzustellendes, flexibles Widget zu erstellen, das jeder SendGrid-Kunde in eine HTML-Seite integrieren kann, die die E-Mail-Adressen bestehender und potenzieller Kunden und andere nützliche Informationen sammelt, um sie in ihren Kontakten für Marketingkampagnen zu speichern . Nachdem Kunden Informationen in das Formular eingegeben haben, erhalten sie eine E-Mail mit einem Link zur Bestätigung ihrer E-Mail-Adresse, und beim Klicken auf den Link wird der Empfänger zur Kontaktliste des angegebenen SendGrid-Kunden hinzugefügt.

Über diese grundlegende Funktionalität hinaus kann das Widget auch:

• Fügen Sie einen Benutzer zu einem bestimmten Listensegment hinzu, falls angegeben
• Fügen Sie benutzerdefinierte Felder in das Formular ein, deren Eingaben mit einem bestimmten Kontakt gespeichert werden
• Senden Sie die Bestätigungs-E-Mail mit einer vorhandenen E-Mail-Vorlage, falls angegeben

Dies war ein interessantes Projekt, da es eine Reihe von Funktionen und API-Endpunkten von SendGrid nutzte, darunter:

• Mail-Versand-API
• Kontakte-API
• Ereignis-Webhook
• Transaktionsvorlagen

In diesem Beitrag werden der Prozess der Erstellung des Widgets und einige der Denkprozesse erörtert, die in seine Implementierung und sein Design eingeflossen sind.

Überblick über das Widget-Design

Das Abonnement-Widget funktioniert, indem es SendGrid-Kunden ermöglicht, eine Anwendung für Heroku bereitzustellen, indem sie die Bereitstellungsschaltfläche von Heroku verwenden. Um das Widget mit der Bereitstellungsschaltfläche zu erstellen, benötigen SendGrid-Kunden ein Heroku-Konto (Sie können hier ein kostenloses Konto erstellen). Das Widget kann jedoch theoretisch bei jedem Hosting-Anbieter bereitgestellt werden. Der SendGrid-Kunde kann dann den Endpunkt, an den das benutzerdefinierte Formular seine POST-Anforderung sendet, in die URL der neu bereitgestellten Heroku-App ändern. Wenn ein Benutzer das Formular absendet, wird die Anfrage von der auf Heroku gehosteten App verarbeitet.

Die App selbst ist eine grundlegende Node/Express-Anwendung mit zwei Routen, die den Anmeldeprozess abwickeln. Die ConfirmEmail- Route sendet Benutzern eine E-Mail mit einem Link zur Bestätigung ihrer E-Mail-Adresse und verwendet eine benutzerdefinierte Transaktionsvorlage (sofern angegeben). Die Anmelderoute fügt einen Benutzer zur Kontaktliste des SendGrid-Kunden hinzu und fügt den Benutzer, falls angegeben, auch zu einem benutzerdefinierten Listensegment hinzu. Die Anmelderoute behandelt auch alle benutzerdefinierten Felder, die ein SendGrid-Kunde in sein benutzerdefiniertes Formular aufnehmen möchte.

E-Mail-Route bestätigen

Die ConfirmEmail- Route ist einfach eine POST-Anfrage an den v3/mail/send POST -Endpunkt unter Verwendung der Node.js-Hilfsbibliothek von SendGrid. Bei einer erfolgreichen Antwort wird der Benutzer auf eine Seite umgeleitet, auf der er aufgefordert wird, in seinem Posteingang nach der Bestätigungs-E-Mail zu suchen. Bei einer erfolglosen Antwort wird der Benutzer auf eine Seite umgeleitet, auf der er aufgefordert wird, seine E-Mail-Adresse erneut einzugeben. Dies kann beispielsweise passieren, wenn ein Benutzer eine ungültige E-Mail-Adresse eingibt.

Die PrepareEmail- Funktion gibt ein JSON-Objekt zurück, das als Hauptteil der API-Anforderung dient.

Der grundlegende Objekterstellungsprozess ist ziemlich einfach. Darin wird die E-Mail-Adresse des Empfängers aus der Formularübermittlung eingefügt. Es passieren jedoch einige interessante Dinge im Objekterstellungsprozess.

Grundlegende benutzerdefinierte Argumente

Zwei benutzerdefinierte Argumente sind in Personalisierungen enthalten: 1) type, das auf „opt-in“ gesetzt ist, und 2) time_sent, das auf die aktuelle Zeit gesetzt ist. Diese benutzerdefinierten Argumente werden im E-Mail-Header übergeben und werden verwendet, um zu bestimmen, ob ein Benutzer im Bestätigungsprozess zu einer Liste hinzugefügt werden soll.

Vorlagen-ID

Nach der anfänglichen Objekterstellung prüfen wir, ob der SendGrid-Kunde sich entschieden hat, eine benutzerdefinierte Vorlage in der Einstellungsdatei zu verwenden, und fügen sie dem Objekt hinzu, wenn dies der Fall ist (Null ist der Standardwert). Eine benutzerdefinierte Vorlage hat Vorrang vor dem im Text enthaltenen E-Mail-Text. Wenn also die Vorlagen-ID als Nullwert belassen wird, wird die Nachricht standardmäßig den bereitgestellten E-Mail-Text verwenden.

Linkersetzung einfügen

Wir fügen eine Ersetzung für den Begriff insert_link ein . Dies ist nur relevant, wenn der SendGrid-Kunde sich für die Verwendung einer Transaktionsvorlage entscheidet. Wenn dies der Fall ist, wird der Begriff insert_link durch den tatsächlichen Link ersetzt, der verwendet wird, um die E-Mail eines Benutzers zu bestätigen und ihn auf die entsprechende Erfolgsseite umzuleiten.

Senden der Formulareingaben als benutzerdefinierte Argumente

Schließlich fügen wir die Werte hinzu, die der Endbenutzer als benutzerdefinierte Argumente an den E-Mail-Text gesendet hat. Die Übermittlung des Endbenutzers wird als Anforderungstext an die anfängliche ConfirmEmail- Route übergeben, die wir dann als Parameter an die PrepareEmail- Funktion übergeben. Der Anforderungstext enthält ein Objekt mit einer Reihe von Schlüssel-Wert-Paaren, die den Namen der Eingabe und den vom Benutzer übermittelten Wert darstellen. Wir durchlaufen dann die Objektschlüssel und fügen der E-Mail für jedes Schlüssel-Wert-Paar ein benutzerdefiniertes Argument hinzu. Diese Werte werden den Kontaktinformationen des Endbenutzers im Kontakterstellungsprozess hinzugefügt.

Anmelderoute

Die Anmelderoute wird durch einen Ereignis-Webhook ausgelöst, der jedes Mal eine POST-Anfrage stellt, wenn ein Benutzer auf den Link in der erhaltenen Bestätigungs-E-Mail klickt. Diese Route muss sich um einige Punkte im Kontakterstellungsprozess kümmern. Wir müssen Folgendes tun:

• Überprüfen Sie, ob das Formular benutzerdefinierte Felder enthielt
• Überprüfen Sie, ob die benutzerdefinierten Felder im Konto des SendGrid-Kunden vorhanden sind, und erstellen Sie sie, wenn die Felder nicht vorhanden sind
• Stellen Sie sicher, dass es sich um eine Opt-in- E-Mail handelt, wie durch den Typ im E-Mail-Erstellungsprozess angegeben
• Stellen Sie sicher, dass der Link innerhalb von 24 Stunden angeklickt wurde
• Erstellen Sie den Kontakt im Konto des SendGrid-Kunden
• Fügen Sie den neuen Kontakt zu einem bestimmten Listensegment hinzu, falls eines bereitgestellt wurde

Umgang mit benutzerdefinierten Feldern

Die Anmelderoute ruft die Funktion addUserToList auf . Diese Funktion wird innerhalb der Route aufgerufen, damit wir den Status nach Abschluss des Vorgangs innerhalb eines Callbacks senden können. Als Erstes erstellen wir innerhalb dieser Funktion ein Objekt, das alle benutzerdefinierten Felder enthält, die das Formular enthält, und ein Array, das die benutzerdefinierten Felder enthält, die nicht standardmäßig für alle Kontakte bereitgestellt werden (E-Mail, Vorname, Nachname).

Eine von Ereignis-Webhooks ausgelöste POST-Anforderung enthält alle E-Mail-bezogenen Informationen, einschließlich der E-Mail-Kopfzeilen, des Betreffs, des Textes usw. Uns interessieren nur die bereitgestellten benutzerdefinierten Argumente, die als Objekt im ersten Element enthalten sind des Anfragetextes. Das Objekt enthält jedoch auch eine Vielzahl von Feldern, die wir für den Prozess der Handhabung benutzerdefinierter Felder nicht benötigen, die wir in einem Array namensignoreFields platzieren .

Wir durchlaufen dann die benutzerdefinierten Argumente, um das Objekt und das Array mit den zuvor erwähnten benutzerdefinierten Feldern zu erstellen. Wir werden das vollständige benutzerdefinierte Feldobjekt im Kontakterstellungsprozess an den Textkörper übergeben, aber erst, wenn wir in einem vorherigen Schritt benutzerdefinierte Felder nach Bedarf hinzufügen.

Wir rufen dann die Funktion checkAndAddCustomFields mit zwei Parametern auf, dem benutzerdefinierten Feldarray und einem Callback, wo wir uns um die Erstellung des Kontakts kümmern. Es ist wichtig, zuerst alle benutzerdefinierten Felder zu überprüfen und hinzuzufügen, da der Endpunkt einen Fehler ausgibt, wenn Sie versuchen, einen Kontakt mit einem benutzerdefinierten Feld zu erstellen, das nicht vorhanden ist.

Die Funktion checkAndAddCustomFields sendet zuerst eine GET-Anforderung an den Endpunkt /v3/contactdb/custom_fields , um die vorhandenen Felder der Kontaktdatenbank abzurufen. Anschließend vergleicht es die Liste der vorhandenen benutzerdefinierten Felder mit der Liste der übermittelten Felder, die als Parameter übergeben wurden, und wenn es übermittelte Felder gibt, die nicht in der Liste der vorhandenen benutzerdefinierten Felder enthalten sind, werden diese neuen Felder dem Array fieldsToCreate hinzugefügt . Wenn keine Felder zu erstellen sind, wird die Callback-Funktion aufgerufen. Wenn jedoch Felder erstellt werden müssen, stellen wir für jedes neue benutzerdefinierte Feld, das erstellt wird, eine POST-Anforderung an den Endpunkt /v3/contactdb/custom_fields .

Erstellen des neuen Kontakts

Nachdem die benutzerdefinierten Felder erstellt wurden, erstellen wir einen neuen Kontakt, indem wir eine POST-Anforderung an den Endpunkt /v3/contactdb/recipients stellen und die benutzerdefinierten Felder als Text der Anforderung übergeben. Wir prüfen dann, ob der SendGrid-Kunde Benutzer zu einem bestimmten Listensegment hinzugefügt hat, und fügen sie gegebenenfalls dem angegebenen Segment hinzu. Die Antwort auf die Kontakterstellungs-API-Anfrage enthält die Kontakt-ID(s) von neu erstellten Kontakten als ein Array namens persisted_recipients . Unter Verwendung der in der Antwort bereitgestellten Kontakt-ID und der vom SendGrid-Kunden bereitgestellten Listen-ID stellen wir dann eine POST-Anforderung an den Endpunkt /v3/contactdb/lists/{listId}/recipients/{contactID} .