使用 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 请求。