Node.jsを使用したサブスクリプションウィジェットの作成

公開: 2017-01-24

私は最近、SendGridのNode.jsAPIライブラリを使用して構築されたオープンソースのサブスクリプションウィジェットを開発しました。プロジェクトの動機と機能の詳細については、リポジトリのREADMEページを参照してください。これは公式にサポートされているSendGridライブラリではありませんが、目標は、SendGridの顧客が既存および潜在的な顧客の電子メールアドレスやその他の有用な情報を収集してマーケティングキャンペーンの連絡先に保存できるHTMLページに簡単に展開できる柔軟なウィジェットを作成することでした。。顧客がフォームに情報を入力すると、電子メールアドレスを確認するためのリンクが記載された電子メールが送信されます。リンクをクリックすると、受信者は指定されたSendGrid顧客の連絡先リストに追加されます。

その基本的な機能に加えて、ウィジェットは次のこともできます。

指定されている場合は、特定のリストセグメントにユーザーを追加します
フォームにカスタムフィールドを含めます。その入力は、特定の連絡先とともに保存されます。
指定されている場合は、既存の電子メールテンプレートを使用して確認電子メールを送信します

これは、次のようなさまざまなSendGridの機能とAPIエンドポイントを利用した興味深いプロジェクトでした。

メール送信API
連絡先API
イベントWebhook
トランザクションテンプレート

この投稿では、ウィジェットを作成するプロセスと、ウィジェットの実装と設計に使用されたいくつかの思考プロセスについて説明します。

ウィジェットデザインの概要

サブスクリプションウィジェットは、SendGridの顧客がHerokuのデプロイボタンを使用してHerokuにアプリをデプロイできるようにすることで機能します。デプロイボタンを使用してウィジェットを作成するには、SendGridのお客様はHerokuアカウントが必要です（ここで無料のアカウントを作成できます）。ただし、ウィジェットは理論的には任意のホスティングプロバイダーにデプロイできます。 SendGridの顧客は、カスタムフォームがPOSTリクエストを行うエンドポイントを新しくデプロイされたHerokuアプリのURLに変更できます。ユーザーがフォームを送信すると、Herokuでホストされているアプリによってリクエストが処理されます。

アプリ自体は、サインアッププロセスを処理する2つのルートを持つ基本的なNode/Expressアプリケーションです。 ConfirmEmailルートは、ユーザーの電子メールアドレスを確認するためのリンクを含む電子メールをユーザーに送信し、カスタムトランザクションテンプレート（指定されている場合）を使用します。 サインアップルートは、SendGrid顧客の連絡先リストにユーザーを追加し、指定されている場合は、カスタムリストセグメントにもユーザーを追加します。 サインアップルートは、SendGridの顧客がカスタムフォームに含めることを選択したカスタムフィールドも処理します。

メールルートの確認

ConfirmEmailルートは、SendGridのNode.jsヘルパーライブラリを使用したv3 / mail /sendPOSTエンドポイントへの単なるPOSTリクエストです。応答が成功すると、ユーザーは受信トレイで確認メールを確認するように求めるページにリダイレクトされます。応答が失敗すると、ユーザーは自分の電子メールアドレスを再入力するように求めるページにリダイレクトされます。たとえば、これは、ユーザーが無効な電子メールアドレスを入力した場合に発生する可能性があります。

prepareEmail関数は、APIリクエストの本文として機能するJSONオブジェクトを返します。

基本的なオブジェクト作成プロセスはかなり単純です。その中に、受信者の電子メールアドレスがフォーム送信から挿入されます。ただし、オブジェクトの作成プロセスで発生する興味深いことがいくつかあります。

基本的なカスタム引数

2つのカスタム引数がパーソナライズに含まれています。1）「opt-in」に設定されているtypeと、2）現在の時刻に設定されているtime_sentです。これらのカスタム引数は電子メールヘッダーで渡され、確認プロセスでユーザーをリストに追加する必要があるかどうかを判断するために使用されます。

テンプレートID

最初のオブジェクト作成後、SendGridのお客様が設定ファイルでカスタムテンプレートを利用することを選択したかどうかを確認し、その場合はオブジェクトに追加します（nullがデフォルト値です）。カスタムテンプレートは本文に含まれるメールテキストよりも優先されるため、テンプレートIDをnull値のままにすると、メッセージはデフォルトで提供されたメールテキストになります。

リンク置換を挿入

insert_linkという用語の代わりに使用します。これは、SendGridの顧客がトランザクションテンプレートの使用を選択した場合にのみ関係します。その場合、 insert_link用語は、ユーザーの電子メールを確認して適切な成功ページにリダイレクトするために使用される実際のリンクに置き換えられます。

フォーム入力をカスタム引数として送信する

最後に、エンドユーザーが電子メール本文に送信した値をカスタム引数として追加します。エンドユーザーの送信は、リクエストの本文として最初のconfirmEmailルートに渡され、次にパラメーターとしてprepareEmail関数に渡されます。リクエストの本文には、キーのセット、入力の名前を表す値のペア、およびユーザーが送信した値を持つオブジェクトが含まれています。次に、オブジェクトキーをループして、キーと値のペアごとにカスタム引数を電子メールに追加します。これらの値は、連絡先の作成プロセスでエンドユーザーの連絡先情報に追加されます。

サインアップルート

サインアップルートは、ユーザーが受信した確認メールに記載されているリンクをクリックするたびにPOSTリクエストを行うイベントWebhookによってトリガーされます。このルートでは、連絡先の作成プロセスでいくつかの項目を処理する必要があります。次のことを行う必要があります。

フォームにカスタムフィールドが含まれているかどうかを確認します
SendGridの顧客のアカウントにカスタムフィールドが存在するかどうかを確認し、フィールドが存在しない場合は作成します
これが、電子メール作成プロセスのタイプで指定されたオプトイン電子メールであることを確認してください
リンクが24時間以内にクリックされたことを確認します
SendGridの顧客のアカウントに連絡先を作成します
連絡先が提供されている場合は、特定のリストセグメントに新しい連絡先を追加します

カスタムフィールドの処理

サインアップルートは、関数addUserToListを呼び出します。この関数はルート内で呼び出されるため、コールバック内でプロセスが完了した後にステータスを送信できます。この関数内で最初に行うことは、フォームに含まれるすべてのカスタムフィールドを含むオブジェクトと、すべての連絡先（email、first_name、last_name）にデフォルトで提供されないカスタムフィールドを含む配列を作成することです。

イベントwebhookによってトリガーされるPOSTリクエストには、メールのヘッダー、件名、テキストなど、メールに関連するすべての情報が含まれます。気になるのは、最初の要素内のオブジェクトとして含まれている、提供されたカスタム引数だけです。リクエスト本文の。ただし、オブジェクトには、 ignoreFieldsという配列に配置するカスタムフィールドを処理するプロセスに必要のないさまざまなフィールドも含まれています。

次に、カスタム引数をループして、前述のカスタムフィールドを使用してオブジェクトと配列を作成します。連絡先の作成プロセスで完全なカスタムフィールドオブジェクトを本文に渡しますが、前のステップで必要に応じてカスタムフィールドを追加するまでは渡しません。

次に、カスタムフィールド配列とコールバックの2つのパラメーターを使用して、関数checkAndAddCustomFieldsを呼び出します。このパラメーターで、連絡先の作成を行います。存在しないカスタムフィールドを使用して連絡先を作成しようとすると、エンドポイントがエラーをスローするため、最初にカスタムフィールドを確認して追加することが重要です。

checkAndAddCustomFields関数は、最初に/ v3 / contactdb / custom_fieldsエンドポイントに対してGET要求を行い、連絡先データベースの既存のフィールドを取得します。次に、既存のカスタムフィールドのリストを、パラメーターとして渡された送信済みフィールドのリストと比較し、既存のカスタムフィールドのリストに含まれていない送信済みフィールドがある場合、それらの新しいフィールドがfieldsToCreate配列に追加されます。。作成するフィールドがない場合は、コールバック関数が呼び出されます。ただし、作成するフィールドがある場合は、作成される新しいカスタムフィールドごとに、 / v3 / contactdb/custom_fieldsエンドポイントにPOSTリクエストを送信します。

新しい連絡先の作成

カスタムフィールドが作成されたら、 / v3 / contactdb / receiveiesエンドポイントにPOSTリクエストを送信し、リクエストの本文としてカスタムフィールドを渡して、新しい連絡先を作成します。次に、SendGridの顧客がユーザーを特定のリストセグメントに追加し、その場合は特定のセグメントにユーザーを追加することを選択したかどうかを確認します。連絡先作成APIリクエストへの応答には、 persisted_recipientsという配列として新しく作成された連絡先の連絡先IDが含まれます。次に、SendGridの顧客から提供された応答とリストIDで提供された連絡先IDを使用して、 / v3 / contactdb / lists / {listId} / receiveiers/{contactID}エンドポイントにPOSTリクエストを送信します。