Membuat Widget Berlangganan dengan Node.js

Saya baru-baru ini mengembangkan widget berlangganan sumber terbuka yang dibuat menggunakan perpustakaan API Node.js SendGrid. Anda dapat menemukan informasi lebih lanjut tentang motivasi dan kemampuan proyek di halaman README repositori. Meskipun ini bukan perpustakaan SendGrid yang didukung secara resmi, tujuannya adalah untuk membuat widget fleksibel yang mudah diterapkan dan dapat digunakan oleh setiap pelanggan SendGrid ke dalam halaman HTML yang mengumpulkan alamat email pelanggan yang sudah ada dan calon pelanggan serta informasi berguna lainnya untuk disimpan dalam Kontak Kampanye Pemasaran mereka . Setelah pelanggan memasukkan informasi ke dalam formulir, mereka menerima email dengan tautan untuk mengonfirmasi alamat email mereka, dan setelah mengklik tautan, penerima akan ditambahkan ke daftar kontak pelanggan SendGrid yang diberikan.

Di luar fungsi dasar itu, widget juga dapat:

• Tambahkan pengguna ke segmen daftar tertentu, jika ditentukan
• Sertakan bidang khusus dalam formulir, yang inputnya akan disimpan dengan kontak yang diberikan
• Kirim email konfirmasi dengan template email yang ada, jika ditentukan

Ini adalah proyek yang menarik karena menggunakan berbagai kemampuan SendGrid dan titik akhir API, termasuk:

• API Pengiriman Surat
• API Kontak
• Webhook Acara
• Template Transaksional

Posting ini akan membahas proses pembuatan widget dan beberapa proses pemikiran yang masuk ke dalam implementasi dan desainnya.

Ikhtisar Desain Widget

Widget berlangganan berfungsi dengan memungkinkan pelanggan SendGrid untuk menyebarkan aplikasi ke Heroku menggunakan tombol penyebaran Heroku. Untuk membuat widget menggunakan tombol deploy, pelanggan SendGrid memerlukan akun Heroku (Anda dapat membuat akun gratis di sini). Namun, widget secara teoritis dapat digunakan ke penyedia hosting mana pun. Pelanggan SendGrid kemudian dapat mengubah titik akhir tempat formulir kustom membuat permintaan POST-nya ke URL aplikasi Heroku yang baru digunakan. Saat pengguna mengirimkan formulir, permintaan tersebut kemudian akan diproses oleh aplikasi yang dihosting di Heroku.

Aplikasi itu sendiri adalah aplikasi Node/Express dasar dengan dua rute yang menangani proses pendaftaran. Rute confirmEmail mengirimkan email kepada pengguna dengan tautan untuk mengonfirmasi alamat email mereka dan menggunakan templat transaksional khusus (jika ada). Rute pendaftaran menambahkan pengguna ke daftar kontak pelanggan SendGrid dan, jika ditentukan, juga menambahkan pengguna ke segmen daftar kustom. Rute pendaftaran juga menangani bidang kustom apa pun yang dipilih pelanggan SendGrid untuk disertakan dalam formulir kustom mereka.

Konfirmasi Rute Email

Rute confirmEmail hanyalah permintaan posting ke titik akhir v3/mail/send POST menggunakan pustaka pembantu Node.js SendGrid. Pada respons yang berhasil, pengguna akan diarahkan ke halaman yang meminta mereka untuk memeriksa kotak masuk mereka untuk email konfirmasi. Pada tanggapan yang gagal, pengguna akan diarahkan ke halaman yang meminta mereka untuk memasukkan kembali alamat email mereka. Misalnya, ini mungkin terjadi jika pengguna memasukkan alamat email yang tidak valid.

Fungsi prepareEmail mengembalikan objek JSON yang akan berfungsi sebagai badan permintaan API.

Proses pembuatan objek dasar cukup sederhana. Di dalamnya, alamat email penerima disisipkan dari pengiriman formulir. Namun, ada beberapa hal menarik yang terjadi dalam proses pembuatan objek tersebut.

Argumen Kustom Dasar

Dua argumen khusus disertakan dalam personalisasi: 1) jenis, yang disetel ke 'keikutsertaan', dan 2) time_sent, yang disetel ke waktu saat ini. Argumen khusus ini diteruskan di header email dan akan digunakan dalam menentukan apakah pengguna harus ditambahkan ke daftar dalam proses konfirmasi.

ID Template

Setelah pembuatan objek awal, kami memeriksa apakah pelanggan SendGrid memilih untuk menggunakan templat kustom dalam file pengaturan dan menambahkannya ke objek jika demikian (null adalah nilai default). Template kustom akan diprioritaskan daripada teks email yang disertakan dalam isi, jadi jika ID template dibiarkan sebagai nilai nol, pesan akan default ke teks email yang disediakan.

Masukkan Substitusi Tautan

Kami menyertakan substitusi untuk istilah insert_link . Ini hanya akan relevan jika pelanggan SendGrid memilih untuk menggunakan template transaksional. Jika demikian, istilah insert_link akan diganti dengan tautan sebenarnya yang digunakan untuk mengonfirmasi email pengguna dan mengarahkan mereka ke halaman sukses yang sesuai.

Mengirim Input Formulir sebagai Argumen Kustom

Terakhir, kami menambahkan nilai yang dikirimkan pengguna akhir ke badan email sebagai argumen khusus. Pengajuan pengguna akhir diteruskan ke rute confirmEmail awal sebagai badan permintaan, yang kemudian kami teruskan ke fungsi prepareEmail sebagai parameter. Badan permintaan berisi objek dengan satu set kunci, pasangan nilai yang mewakili nama input dan nilai yang dikirimkan pengguna. Kami kemudian mengulang kunci objek menambahkan argumen khusus ke email untuk setiap kunci, pasangan nilai. Nilai-nilai ini akan ditambahkan ke informasi kontak pengguna akhir dalam proses pembuatan kontak.

Rute Pendaftaran

Rute pendaftaran dipicu oleh webhook peristiwa yang membuat permintaan POST setiap kali pengguna mengklik tautan yang disediakan dalam email konfirmasi yang mereka terima. Rute ini perlu mengurus beberapa item dalam proses pembuatan kontak. Kita harus melakukan hal berikut:

• Periksa apakah formulir berisi bidang khusus
• Periksa apakah bidang khusus ada di akun pelanggan SendGrid dan buat jika bidang tidak ada
• Pastikan ini adalah email keikutsertaan sebagaimana ditentukan oleh jenis dalam proses pembuatan email
• Pastikan tautan diklik dalam waktu 24 jam
• Buat kontak di akun pelanggan SendGrid
• Tambahkan kontak baru ke segmen daftar tertentu jika telah disediakan

Menangani Bidang Kustom

Rute pendaftaran memanggil fungsi addUserToList . Fungsi ini dipanggil di dalam rute sehingga kami dapat mengirim status setelah proses selesai di dalam panggilan balik. Hal pertama yang kita lakukan di dalam fungsi ini adalah membuat objek yang berisi semua bidang khusus yang berisi formulir dan larik yang berisi bidang khusus yang tidak disediakan secara default untuk semua kontak (email, first_name, last_name).

Permintaan POST yang dipicu oleh webhook acara berisi semua informasi terkait email, termasuk header email, subjek, teks, dll. Yang kami pedulikan hanyalah argumen khusus yang telah disediakan, yang dimuat sebagai objek dalam elemen pertama dari badan permintaan. Namun, objek juga berisi berbagai bidang yang tidak kita perlukan untuk proses penanganan bidang khusus, yang kita tempatkan dalam larik yang disebut abaikanFields .

Kami kemudian mengulang argumen khusus untuk membuat objek dan larik dengan bidang khusus yang disebutkan sebelumnya. Kami akan meneruskan objek bidang khusus penuh ke dalam badan dalam proses pembuatan kontak, tetapi tidak sampai kami menambahkan bidang khusus, sebagaimana diperlukan, pada langkah sebelumnya.

Kami kemudian memanggil fungsi checkAndAddCustomFields dengan dua parameter, larik bidang khusus dan panggilan balik, di mana kami akan menangani pembuatan kontak. Penting untuk terlebih dahulu memeriksa dan menambahkan bidang khusus apa pun karena titik akhir akan menimbulkan kesalahan jika Anda mencoba membuat kontak dengan bidang khusus yang tidak ada.

Fungsi checkAndAddCustomFields pertama-tama membuat permintaan GET ke titik akhir /v3/contactdb/custom_fields untuk mengambil bidang database kontak yang ada. Kemudian membandingkan daftar bidang khusus yang ada dengan daftar bidang yang dikirimkan yang diteruskan sebagai parameter, dan jika ada bidang yang dikirim yang tidak disertakan dalam daftar bidang khusus yang ada, bidang baru tersebut ditambahkan ke larik fieldToCreate . Jika tidak ada bidang untuk dibuat, fungsi panggilan balik dipanggil. Namun, jika ada bidang yang harus dibuat, kami membuat permintaan POST ke titik akhir /v3/contactdb/custom_fields untuk setiap bidang khusus baru yang akan dibuat.

Membuat Kontak Baru

Setelah bidang khusus dibuat, kami membuat kontak baru dengan membuat permintaan POST ke titik akhir /v3/contactdb/recipients , meneruskan bidang khusus sebagai isi permintaan. Kami kemudian memeriksa apakah pelanggan SendGrid memilih untuk menambahkan pengguna ke segmen daftar tertentu dan menambahkan mereka ke segmen yang diberikan, jika itu masalahnya. Respons terhadap permintaan API pembuatan kontak menyertakan ID kontak dari kontak yang baru dibuat sebagai larik yang disebut persistent_recipients . Menggunakan ID kontak yang disediakan dalam respons dan ID daftar yang disediakan oleh pelanggan SendGrid, kami kemudian membuat permintaan POST ke titik akhir /v3/contactdb/lists/{listId}/recipients/{contactID} .