إنشاء أداة اشتراك باستخدام Node.js

لقد قمت مؤخرًا بتطوير أداة اشتراك مفتوحة المصدر تم إنشاؤها باستخدام مكتبة SendGrid's Node.js API. يمكنك العثور على مزيد من المعلومات حول دوافع وقدرات المشروع على صفحة README الخاصة بالمستودع. على الرغم من أن هذه ليست مكتبة SendGrid مدعومة رسميًا ، فقد كان الهدف هو إنشاء عنصر واجهة مستخدم مرن وقابل للنشر بسهولة يمكن لأي عميل SendGrid تضمينه في صفحة HTML التي تجمع عناوين البريد الإلكتروني للعملاء الحاليين والمحتملين ومعلومات مفيدة أخرى لتخزينها ضمن جهات اتصال حملات التسويق الخاصة بهم . بعد قيام العملاء بإدخال المعلومات في النموذج ، يتلقون بريدًا إلكترونيًا يحتوي على رابط لتأكيد عنوان بريدهم الإلكتروني ، وعند النقر فوق الارتباط ، سيتم إضافة المستلم إلى قائمة جهات اتصال عميل SendGrid المحددة.

بالإضافة إلى هذه الوظيفة الأساسية ، يمكن للأداة أيضًا:

• أضف مستخدمًا إلى مقطع قائمة محدد ، إذا تم تحديده
• قم بتضمين الحقول المخصصة في النموذج ، والتي سيتم تخزين مدخلاتها مع جهة اتصال معينة
• أرسل رسالة التأكيد بالبريد الإلكتروني مع قالب بريد إلكتروني موجود ، إذا تم تحديده

كان هذا مشروعًا مثيرًا للاهتمام لأنه استخدم مجموعة من إمكانيات SendGrid ونقاط نهاية API ، بما في ذلك:

• واجهة برمجة تطبيقات إرسال البريد
• API جهات الاتصال
• حدث Webhook
• قوالب المعاملات

سيناقش هذا المنشور عملية إنشاء الأداة وبعض عمليات التفكير التي دخلت في تنفيذها وتصميمها.

نظرة عامة على تصميم القطعة

تعمل أداة الاشتراك من خلال السماح لعملاء SendGrid بنشر تطبيق على Heroku باستخدام زر نشر Heroku. لإنشاء الأداة باستخدام زر النشر ، سيحتاج عملاء SendGrid إلى حساب Heroku (يمكنك إنشاء حساب مجاني هنا). ومع ذلك ، يمكن نظريًا نشر الأداة على أي مزود استضافة. يمكن لعميل SendGrid بعد ذلك تغيير نقطة النهاية التي يقوم النموذج المخصص بتقديم طلب POST إليها إلى عنوان URL لتطبيق Heroku الذي تم نشره حديثًا. عندما يرسل المستخدم النموذج ، ستتم معالجة الطلب بعد ذلك بواسطة التطبيق المستضاف على Heroku.

التطبيق نفسه هو تطبيق Node / Express أساسي مع مسارين يتعاملان مع عملية التسجيل. يرسل مسار ConfirmEmail بريدًا إلكترونيًا إلى المستخدمين به رابط لتأكيد عنوان بريدهم الإلكتروني ويستخدم نموذجًا مخصصًا للمعاملات (إذا تم تحديد واحد). يضيف مسار التسجيل مستخدمًا إلى قائمة جهات اتصال عميل SendGrid ، وإذا تم تحديده ، فإنه يضيف أيضًا المستخدم إلى مقطع قائمة مخصص. يعالج مسار التسجيل أيضًا أي حقول مخصصة يختارها عميل SendGrid لتضمينها في النموذج المخصص الخاص به.

تأكيد مسار البريد الإلكتروني

مسار ConfirmEmail هو ببساطة طلب نشر إلى نقطة نهاية v3 / mail / send POST باستخدام مكتبة مساعد SendGrid Node.js. عند الرد بنجاح ، سيتم إعادة توجيه المستخدم إلى صفحة تطلب منه التحقق من صندوق الوارد الخاص به بحثًا عن رسالة التأكيد الإلكترونية. في حالة الرد غير الناجح ، ستتم إعادة توجيه المستخدم إلى صفحة تطلب منه إعادة إدخال عنوان بريده الإلكتروني. على سبيل المثال ، قد يحدث هذا إذا قام المستخدم بإدخال عنوان بريد إلكتروني غير صالح.

ترجع وظيفة PreparEmail كائن JSON الذي سيكون بمثابة نص طلب واجهة برمجة التطبيقات.

عملية إنشاء الكائن الأساسية بسيطة إلى حد ما. في ذلك ، يتم إدخال عنوان البريد الإلكتروني للمستلم من إرسال النموذج. ومع ذلك ، هناك بعض الأشياء المثيرة للاهتمام التي تحدث في عملية إنشاء الكائن.

الحجج الأساسية المخصصة

يتم تضمين وسيطتين مخصصتين في عمليات التخصيص: 1) النوع ، الذي تم تعيينه على "الاشتراك" ، و 2) إرسال الوقت ، والذي تم تعيينه على الوقت الحالي. يتم تمرير هذه الوسائط المخصصة في رأس البريد الإلكتروني وسيتم استخدامها في تحديد ما إذا كان يجب إضافة مستخدم إلى قائمة في عملية التأكيد.

معرف النموذج

بعد إنشاء الكائن الأولي ، نتحقق مما إذا كان عميل SendGrid قد اختار استخدام قالب مخصص في ملف الإعدادات وإضافته إلى الكائن إذا كانت هذه هي الحالة (القيمة الفارغة هي القيمة الافتراضية). سيكون للقالب المخصص الأولوية على نص البريد المضمن في النص الأساسي ، لذلك إذا تم ترك معرف القالب كقيمة فارغة ، فستتحول الرسالة افتراضيًا إلى نص البريد المقدم.

أدخل استبدال الارتباط

نقوم بتضمين بديل للمصطلح insert_link . سيكون هذا مناسبًا فقط إذا اختار عميل SendGrid استخدام قالب المعاملات. إذا كانت هذه هي الحالة ، فسيتم استبدال مصطلح insert_link بالرابط الفعلي المستخدم لتأكيد البريد الإلكتروني للمستخدم وإعادة توجيهه إلى صفحة النجاح المناسبة.

إرسال مدخلات النموذج كوسائط مخصصة

أخيرًا ، نضيف القيم التي أرسلها المستخدم النهائي إلى نص البريد الإلكتروني كوسائط مخصصة. يتم تمرير إرسال المستخدم النهائي إلى مسار البريد الإلكتروني ConfirmEmail الأولي باعتباره نص الطلب ، والذي نمرره بعد ذلك إلى وظيفة PreparEmail كمعامل . يحتوي نص الطلب على كائن بمجموعة من المفاتيح ، وأزواج قيم تمثل اسم الإدخال والقيمة التي أرسلها المستخدم. ثم نقوم بعمل حلقة عبر مفاتيح الكائنات مضيفين وسيطة مخصصة إلى البريد الإلكتروني لكل زوج من المفاتيح والقيمة. ستتم إضافة هذه القيم إلى معلومات الاتصال الخاصة بالمستخدم النهائي في عملية إنشاء جهة الاتصال.

مسار التسجيل

يتم تشغيل مسار التسجيل بواسطة خطاف ويب لحدث يقوم بإجراء طلب POST في كل مرة ينقر فيها المستخدم على الرابط المقدم في رسالة التأكيد الإلكترونية التي يتلقونها. يحتاج هذا المسار إلى الاهتمام ببعض العناصر في عملية إنشاء جهة الاتصال. يجب أن نقوم بما يلي:

• تحقق مما إذا كان النموذج يحتوي على أي حقول مخصصة
• تحقق مما إذا كانت الحقول المخصصة موجودة في حساب عميل SendGrid وقم بإنشائها إذا لم تكن الحقول موجودة
• تأكد من أن هذا بريد إلكتروني قابل للاشتراك كما هو محدد بواسطة النوع في عملية إنشاء البريد الإلكتروني
• تأكد من النقر على الرابط في غضون 24 ساعة
• قم بإنشاء جهة الاتصال في حساب عميل SendGrid
• أضف جهة الاتصال الجديدة إلى شريحة قائمة محددة إذا تم توفيرها

التعامل مع الحقول المخصصة

يستدعي مسار التسجيل الوظيفة addUserToList . تسمى هذه الوظيفة داخل المسار حتى نتمكن من إرسال الحالة بعد اكتمال العملية داخل رد الاتصال. أول شيء نقوم به داخل هذه الوظيفة هو إنشاء كائن يحتوي على جميع الحقول المخصصة التي يحتوي عليها النموذج ومصفوفة تحتوي على الحقول المخصصة التي لم يتم توفيرها افتراضيًا لجميع جهات الاتصال (البريد الإلكتروني ، الاسم_الأول ، الاسم_الأخير).

يحتوي طلب POST الذي يتم تشغيله بواسطة خطافات الويب الخاصة بالحدث على جميع المعلومات المتعلقة بالبريد الإلكتروني ، بما في ذلك رؤوس البريد الإلكتروني والموضوع والنص وما إلى ذلك. كل ما يهمنا هو الوسائط المخصصة التي تم توفيرها ، والتي تم تضمينها ككائن داخل العنصر الأول من نص الطلب. ومع ذلك ، يحتوي الكائن أيضًا على مجموعة متنوعة من الحقول التي لا نحتاجها لعملية معالجة الحقول المخصصة ، والتي نضعها في مصفوفة تسمى ignoreFields .

ثم نقوم بعمل حلقة من خلال الوسيطات المخصصة لإنشاء الكائن والمصفوفة مع الحقول المخصصة المذكورة سابقًا. سنقوم بتمرير كائن الحقول المخصصة بالكامل إلى الجسم في عملية إنشاء جهة الاتصال ، ولكن ليس حتى نضيف حقولًا مخصصة ، حسب الضرورة ، في خطوة سابقة.

ثم نسمي الدالة checkAndAddCustomFields مع معلمتين ، مصفوفة الحقول المخصصة واستدعاء ، حيث سنهتم بإنشاء جهة الاتصال. من المهم التحقق أولاً من أي حقول مخصصة وإضافتها لأن نقطة النهاية ستظهر خطأ إذا حاولت إنشاء جهة اتصال بحقل مخصص غير موجود.

تقوم وظيفة checkAndAddCustomFields أولاً بتقديم طلب GET إلى نقطة النهاية / v3 / contactdb / custom_fields لاسترداد الحقول الموجودة لقاعدة بيانات جهات الاتصال. ثم يقارن قائمة الحقول المخصصة الموجودة بقائمة الحقول المرسلة التي تم تمريرها كمعامل ، وإذا كان هناك أي حقول مرسلة غير مضمنة في قائمة الحقول المخصصة الحالية ، تتم إضافة هذه الحقول الجديدة إلى مجموعة الحقول لإنشاء مصفوفة . إذا لم تكن هناك أي حقول لإنشاءها ، فسيتم استدعاء وظيفة رد الاتصال. ومع ذلك ، إذا كان هناك أي حقول يتم إنشاؤها ، فإننا نقدم طلب POST إلى / v3 / contactdb / custom_fields نقطة النهاية لكل حقل مخصص جديد سيتم إنشاؤه.

إنشاء جهة اتصال جديدة

بمجرد إنشاء الحقول المخصصة ، نقوم بإنشاء جهة اتصال جديدة عن طريق تقديم طلب POST إلى نقطة النهاية / v3 / contactdb / المستلمين ، وتمرير الحقول المخصصة كهيئة للطلب. ثم نتحقق مما إذا كان عميل SendGrid قد اختار إضافة مستخدمين إلى شريحة قائمة معينة وإضافتهم إلى المقطع المحدد ، إذا كان هذا هو الحال. تتضمن الاستجابة لطلب واجهة برمجة التطبيقات لإنشاء جهة اتصال معرّف (معرّفات) جهة الاتصال لجهة (جهات) اتصال تم إنشاؤها حديثًا كمصفوفة تسمى persisted_recipients . باستخدام معرف جهة الاتصال المقدم في الاستجابة ومعرف القائمة المقدم من عميل SendGrid ، نقوم بعد ذلك بتقديم طلب POST إلى نقطة النهاية / v3 / contactdb / list / {listId} / المستلمون / {contactID} .