Node.js로 구독 위젯 만들기

게시 됨: 2017-01-24

저는 최근에 SendGrid의 Node.js API 라이브러리를 사용하여 빌드된 오픈 소스 구독 위젯을 개발했습니다. 리포지토리의 README 페이지에서 프로젝트의 동기와 기능에 대한 자세한 정보를 찾을 수 있습니다. 이것은 공식적으로 지원되는 SendGrid 라이브러리는 아니지만 목표는 모든 SendGrid 고객이 마케팅 캠페인 연락처에 저장할 기존 및 잠재 고객의 이메일 주소 및 기타 유용한 정보를 수집하는 HTML 페이지에 통합할 수 있는 쉽게 배포할 수 있고 유연한 위젯을 만드는 것이었습니다. . 고객이 양식에 정보를 입력하면 이메일 주소를 확인할 수 있는 링크가 포함된 이메일이 수신되며 링크를 클릭하면 수신자가 지정된 SendGrid 고객의 연락처 목록에 추가됩니다.

기본 기능 외에도 위젯은 다음을 수행할 수 있습니다.

  • 지정된 경우 특정 목록 세그먼트에 사용자 추가
  • 양식에 사용자 정의 필드를 포함하고 입력은 지정된 연락처와 함께 저장됩니다.
  • 지정된 경우 기존 이메일 템플릿과 함께 확인 이메일을 보냅니다.

이것은 다음을 포함하여 다양한 SendGrid의 기능과 API 엔드포인트를 활용했기 때문에 흥미로운 프로젝트였습니다.

  • 메일 보내기 API
  • 연락처 API
  • 이벤트 웹훅
  • 트랜잭션 템플릿

이 게시물에서는 위젯을 만드는 과정과 구현 및 디자인에 들어간 몇 가지 사고 과정에 대해 설명합니다.

위젯 디자인 개요

구독 위젯은 SendGrid 고객이 Heroku의 배포 버튼을 사용하여 Heroku에 앱을 배포할 수 있도록 함으로써 작동합니다. 배포 버튼을 사용하여 위젯을 만들려면 SendGrid 고객은 Heroku 계정이 필요합니다(여기에서 무료 계정을 만들 수 있음). 그러나 위젯은 이론적으로 모든 호스팅 제공업체에 배포할 수 있습니다. 그런 다음 SendGrid 고객은 사용자 지정 양식이 새로 배포된 Heroku 앱의 URL에 대한 POST 요청을 수행하는 끝점을 변경할 수 있습니다. 사용자가 양식을 제출하면 Heroku에서 호스팅되는 앱에서 요청을 처리합니다.

앱 자체는 등록 프로세스를 처리하는 두 가지 경로가 있는 기본 Node/Express 애플리케이션입니다. ConfirmEmail 경로는 이메일 주소를 확인하는 링크가 포함된 이메일을 사용자에게 보내고 사용자 지정 트랜잭션 템플릿(지정된 경우)을 사용합니다. 가입 경로는 SendGrid 고객의 연락처 목록에 사용자를 추가하고 지정된 경우 사용자 지정 목록 세그먼트에도 사용자를 추가합니다. 가입 경로는 SendGrid 고객이 사용자 정의 양식에 포함하기로 선택한 모든 사용자 정의 필드도 처리합니다.

이메일 경로 확인

ConfirmEmail 경로는 단순히 SendGrid의 Node.js 도우미 라이브러리를 사용하여 v3/mail/send POST 끝점에 대한 게시 요청입니다. 응답이 성공하면 사용자는 받은 편지함에서 확인 이메일을 확인하도록 요청하는 페이지로 리디렉션됩니다. 응답이 실패하면 사용자는 이메일 주소를 다시 입력하도록 요청하는 페이지로 리디렉션됩니다. 예를 들어, 사용자가 잘못된 이메일 주소를 입력한 경우 이러한 일이 발생할 수 있습니다.

prepareEmail 함수는 API 요청의 본문으로 사용할 JSON 객체를 반환합니다.

기본 개체 생성 프로세스는 매우 간단합니다. 여기에는 양식 제출에서 받는 사람 이메일 주소가 삽입됩니다. 그러나 객체 생성 과정에서 몇 가지 흥미로운 일이 발생합니다.

기본 사용자 지정 인수

개인화에는 두 가지 사용자 정의 인수가 포함됩니다. 1) 'opt-in'으로 설정된 유형 및 2) 현재 시간으로 설정된 time_sent. 이러한 사용자 정의 인수는 이메일 헤더에 전달되며 확인 프로세스에서 사용자를 목록에 추가해야 하는지 여부를 결정하는 데 사용됩니다.

템플릿 ID

초기 개체 생성 후 SendGrid 고객이 설정 파일에서 사용자 지정 템플릿을 사용하도록 선택했는지 확인하고 해당하는 경우 개체에 추가합니다(기본값은 null임). 사용자 정의 템플릿은 본문에 포함된 메일 ​​텍스트보다 우선하므로 템플릿 ID를 null 값으로 남겨두면 메시지는 기본적으로 제공된 메일 텍스트로 설정됩니다.

링크 대체 삽입

insert_link 라는 용어에 대한 대체 항목을 포함합니다. 이것은 SendGrid 고객이 트랜잭션 템플릿을 사용하기로 선택한 경우에만 관련이 있습니다. 이 경우 insert_link 용어는 사용자의 이메일을 확인하고 적절한 성공 페이지로 리디렉션하는 데 사용되는 실제 링크로 대체됩니다.

양식 입력을 사용자 정의 인수로 보내기

마지막으로 최종 사용자가 이메일 본문에 사용자 정의 인수로 제출한 값을 추가합니다. 최종 사용자의 제출은 요청 본문으로 초기 ConfirmEmail 경로에 전달된 다음 prepareEmail 함수에 매개변수로 전달합니다. 요청 본문에는 키 세트, 입력 이름을 나타내는 값 쌍 및 사용자가 제출한 값이 있는 객체가 포함됩니다. 그런 다음 각 키, 값 쌍에 대해 이메일에 사용자 정의 인수를 추가하는 객체 키를 반복합니다. 이 값은 연락처 생성 프로세스에서 최종 사용자의 연락처 정보에 추가됩니다.

가입 경로

가입 경로는 사용자가 수신 확인 이메일에 제공된 링크를 클릭할 때마다 POST 요청을 생성하는 이벤트 웹훅에 의해 트리거됩니다. 이 경로는 연락처 생성 프로세스에서 몇 가지 항목을 처리해야 합니다. 다음을 수행해야 합니다.

  • 양식에 사용자 정의 필드가 포함되어 있는지 확인
  • SendGrid 고객의 계정에 사용자 정의 필드가 있는지 확인하고 필드가 없으면 생성하십시오.
  • 이메일 생성 프로세스에서 유형에 따라 지정된 수신 동의 이메일인지 확인합니다.
  • 24시간 이내에 링크를 클릭했는지 확인
  • SendGrid 고객 계정에 연락처 만들기
  • 새 연락처가 제공된 경우 특정 목록 세그먼트에 새 연락처 추가

사용자 정의 필드 처리

가입 경로는 addUserToList 함수를 호출합니다. 이 함수는 프로세스가 완료된 후 콜백 내에서 상태를 보낼 수 있도록 경로 내에서 호출됩니다. 이 함수 내에서 가장 먼저 하는 일은 양식에 포함된 모든 사용자 정의 필드를 포함하는 객체와 모든 연락처(이메일, first_name, last_name)에 대해 기본적으로 제공되지 않는 사용자 정의 필드를 포함하는 배열을 만드는 것입니다.

이벤트 웹훅에 의해 트리거된 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 요청을 보냅니다.