使用 Node.js 創建訂閱小部件

已發表: 2017-01-24

我最近開發了一個使用 SendGrid 的 Node.js API 庫構建的開源訂閱小部件。您可以在存儲庫的 README 頁面上找到有關該項目的動機和功能的更多信息。雖然這不是官方支持的 SendGrid 庫，但其目標是製作一個易於部署、靈活的小部件，任何 SendGrid 客戶都可以將其合併到 HTML 頁面中，該頁面收集現有和潛在客戶的電子郵件地址和其他有用信息以存儲在他們的營銷活動聯繫人中. 客戶在表單中輸入信息後，他們會收到一封電子郵件，其中包含確認其電子郵件地址的鏈接，單擊該鏈接後，收件人將被添加到給定的 SendGrid 客戶的聯繫人列表中。

除了基本功能之外，小部件還可以：

將用戶添加到特定列表段（如果指定）
在表單中包含自定義字段，其輸入將與給定聯繫人一起存儲
使用現有電子郵件模板發送確認電子郵件（如果指定）

這是一個有趣的項目，因為它利用了一系列 SendGrid 的功能和 API 端點，包括：

郵件發送 API
聯繫人 API
事件網絡鉤子
事務模板

這篇文章將討論創建小部件的過程以及進入其實現和設計的一些思考過程。

小部件設計概述

訂閱小部件的功能是允許 SendGrid 客戶使用 Heroku 的部署按鈕將應用程序部署到 Heroku。要使用部署按鈕創建小部件，SendGrid 客戶將需要一個 Heroku 帳戶（您可以在此處創建一個免費帳戶）。但是，理論上可以將小部件部署到任何託管服務提供商。然後，SendGrid 客戶可以將自定義表單發出 POST 請求的端點更改為新部署的 Heroku 應用程序的 URL。當用戶提交表單時，請求將由 Heroku 上託管的應用程序處理。

該應用程序本身是一個基本的 Node/Express 應用程序，有兩條路由處理註冊過程。 confirmEmail路由向用戶發送一封電子郵件，其中包含一個鏈接以確認他們的電子郵件地址，並使用自定義交易模板（如果已指定）。註冊路由將用戶添加到 SendGrid 客戶的聯繫人列表，如果指定，還將用戶添加到自定義列表段。註冊路線還處理 SendGrid 客戶選擇包含在其自定義表單中的任何自定義字段。

確認電子郵件路由

ConfirmEmail路由只是一個使用 SendGrid 的 Node.js 幫助程序庫對v3/mail/send POST端點的發布請求。成功響應後，用戶將被重定向到一個頁面，要求他們檢查收件箱中的確認電子郵件。如果響應不成功，用戶將被重定向到一個頁面，要求他們重新輸入他們的電子郵件地址。例如，如果用戶輸入了無效的電子郵件地址，則可能會發生這種情況。

prepareEmail函數返回一個 JSON 對象，該對象將作為 API 請求的主體。

基本的對象創建過程相當簡單。其中，收件人電子郵件地址是從表單提交中插入的。但是，在對象創建過程中發生了一些有趣的事情。

基本自定義參數

個性化設置中包含兩個自定義參數：1) type，設置為“opt-in”，2) time_sent，設置為當前時間。這些自定義參數在電子郵件標題中傳遞，並將用於確定是否應在確認過程中將用戶添加到列表中。

模板編號

在初始對象創建之後，我們檢查 SendGrid 客戶是否選擇在設置文件中使用自定義模板，如果是這種情況，則將其添加到對像中（默認值為 null）。自定義模板將優先於正文中包含的郵件文本，因此如果模板 ID 保留為空值，則消息將默認為提供的郵件文本。

插入鏈接替換

我們包括對術語insert_link的替代。這僅在 SendGrid 客戶選擇使用事務模板時才相關。如果是這種情況， insert_link術語將替換為用於確認用戶電子郵件並將其重定向到相應成功頁面的實際鏈接。

將表單輸入作為自定義參數發送

最後，我們將最終用戶提交到電子郵件正文的值作為自定義參數添加。最終用戶的提交作為請求正文傳遞到初始的confirmEmail路由，然後我們將其作為參數傳遞給prepareEmail函數。請求正文包含一個對象，該對象具有一組鍵、值對，表示輸入的名稱和用戶提交的值。然後，我們遍歷對象鍵，為每個鍵值對添加一個自定義參數到電子郵件中。這些值將在聯繫人創建過程中添加到最終用戶的聯繫人信息中。

註冊路線

註冊路由由事件 webhook 觸發，每次用戶單擊他們收到的確認電子郵件中提供的鏈接時，該事件 webhook 都會發出 POST 請求。此路由需要處理聯繫人創建過程中的一些項目。我們必須做到以下幾點：

檢查表單是否包含任何自定義字段
檢查 SendGrid 客戶帳戶中是否存在自定義字段，如果字段不存在則創建它們
確保這是電子郵件創建過程中類型指定的選擇加入電子郵件
確保在 24 小時內點擊鏈接
在 SendGrid 客戶的帳戶中創建聯繫人
如果已提供新聯繫人，則將其添加到特定列表段

處理自定義字段

註冊路由調用函數addUserToList 。這個函數在路由中被調用，這樣我們就可以在進程完成後在回調中發送狀態。我們在這個函數中做的第一件事是創建一個包含表單包含的所有自定義字段的對象和一個數組，其中包含默認情況下未為所有聯繫人提供的自定義字段（電子郵件、名字、姓氏）。

由事件 webhook 觸發的 POST 請求包含所有與電子郵件相關的信息，包括電子郵件的標題、主題、文本等。我們關心的是已提供的自定義參數，它們作為對象包含在第一個元素中請求正文。但是，該對像還包含各種我們在處理自定義字段的過程中不需要的字段，我們將它們放在一個名為ignoreFields的數組中。

然後，我們遍歷自定義參數以使用前面提到的自定義字段創建對象和數組。我們將在聯繫人創建過程中將完整的自定義字段對像傳遞到正文中，但直到我們在之前的步驟中根據需要添加自定義字段。

然後，我們使用兩個參數調用函數checkAndAddCustomFields ，自定義字段數組和回調，我們將在其中創建聯繫人。首先檢查並添加任何自定義字段很重要，因為如果您嘗試使用不存在的自定義字段創建聯繫人，端點將引發錯誤。

checkAndAddCustomFields函數首先向/v3/contactdb/custom_fields端點發出 GET 請求，以檢索聯繫人數據庫的現有字段。然後，它將現有自定義字段列表與作為參數傳遞的提交字段列表進行比較，如果現有自定義字段列表中未包含任何提交字段，則將這些新字段添加到fieldsToCreate數組. 如果沒有要創建的字段，則調用回調函數。但是，如果有任何要創建的字段，我們會針對將要創建的每個新自定義字段向/v3/contactdb/custom_fields端點發出 POST 請求。

創建新聯繫人

創建自定義字段後，我們通過向/v3/contactdb/recipients端點發出 POST 請求來創建新聯繫人，並將自定義字段作為請求正文傳遞。然後，我們檢查 SendGrid 客戶是否選擇將用戶添加到給定的列表段，並將他們添加到給定的段中，如果是這樣的話。對聯繫人創建 API 請求的響應包括新創建的聯繫人的聯繫人 ID，作為名為persisted_recipients的數組。使用響應中提供的聯繫人 ID 和 SendGrid 客戶提供的列表 ID，我們然後向/v3/contactdb/lists/{listId}/recipients/{contactID}端點發出 POST 請求。