با استفاده از پسوند Trigger Email

افزونه‌ی Trigger Email ( firestore-send-email ) به شما امکان می‌دهد تا به طور خودکار ایمیل‌هایی را بر اساس اسناد موجود در مجموعه‌ی Cloud Firestore ارسال کنید. افزودن یک سند به مجموعه، این افزونه را برای ارسال ایمیلی که از فیلدهای سند ساخته شده است، فعال می‌کند. فیلدهای سطح بالای سند، فرستنده و گیرنده‌ی ایمیل، از جمله گزینه‌های to ، cc و bcc (که هر کدام از UIDها پشتیبانی می‌کنند) را مشخص می‌کنند. فیلد message سند، سایر عناصر ایمیل، مانند موضوع و بدنه‌ی ایمیل (به صورت متن ساده یا HTML) را مشخص می‌کند.

در اینجا یک مثال ساده از نوشتن سند که این افزونه را فعال می‌کند، آورده شده است:

admin.firestore().collection('mail').add({
  to: 'someone@example.com',
  message: {
    subject: 'Hello from Firebase!',
    html: 'This is an <code>HTML</code> email body.',
  },
})

همچنین می‌توانید به صورت اختیاری این افزونه را طوری پیکربندی کنید که با استفاده از قالب‌های Handlebars ، ایمیل‌ها را رندر کند.

تنظیمات قبل از نصب

قبل از نصب افزونه، این مراحل را انجام دهید:

  1. سرویس ایمیل خروجی خود را تنظیم کنید.

    هنگام نصب افزونه Trigger Email، باید جزئیات اتصال و احراز هویت سرور SMTP را که افزونه برای ارسال ایمیل از آن استفاده می‌کند، مشخص کنید. این معمولاً توسط یک سرویس تحویل ایمیل مانند Sendgrid، Mailgun یا Mailchimp Transactional Email ارائه می‌شود، اما می‌تواند سروری باشد که خودتان آن را اجرا می‌کنید.

  2. یک مجموعه اسناد ایمیل ایجاد کنید.

    افزونه‌ی Trigger Email به دنبال اسناد جدید در مجموعه‌ی Cloud Firestore که شما مشخص می‌کنید می‌گردد. وقتی یک سند جدید پیدا می‌کند، بر اساس فیلدهای سند، ایمیلی ارسال می‌کند. می‌توانید از هر مجموعه‌ی Cloud Firestore برای این منظور استفاده کنید؛ مثال‌های این صفحه از مجموعه‌ای به نام email استفاده می‌کنند.

  3. قوانین امنیتی برای مجموعه اسناد ایمیل خود تنظیم کنید.

    این افزونه می‌تواند برای ارسال مستقیم ایمیل از برنامه‌های کلاینت استفاده شود. با این حال، شما باید دسترسی کلاینت به مجموعه را به دقت کنترل کنید تا از سوءاستفاده‌های احتمالی جلوگیری شود (شما نمی‌خواهید کاربران بتوانند ایمیل‌های دلخواه خود را از آدرس شرکت شما ارسال کنند!).

    قوانین امنیتی از یک برنامه به برنامه دیگر متفاوت است، اما همیشه باید مطمئن شوید که ایمیل‌ها فقط به گیرندگان مورد نظر ارسال می‌شوند و محتوای آزاد به حداقل می‌رسد. قالب‌ها می‌توانند در اینجا کمک کنند - می‌توانید از قوانین امنیتی برای تأیید اینکه داده‌هایی که در قالب قرار می‌گیرند با انتظارات شما از آنچه یک کاربر باید مجاز به فعال کردن آن باشد، مطابقت دارند، استفاده کنید.

  4. اختیاری: یک مجموعه کاربر راه‌اندازی کنید.

    در حالت استفاده‌ی اولیه از این افزونه، شما گیرندگان ایمیل را با مشخص کردن آدرس‌های ایمیل آنها در فیلدهای to ، cc و bcc سند پیام مشخص می‌کنید. به عنوان یک جایگزین، اگر پایگاه داده‌ی کاربری در Cloud Firestore دارید، می‌توانید گیرندگان را با استفاده از شناسه‌های کاربری (UID) کاربران مشخص کنید. برای اینکه این کار انجام شود، مجموعه‌ی کاربران شما باید این معیارها را داشته باشد:

    • این مجموعه باید روی شناسه‌های کاربری کلیدگذاری شود. یعنی شناسه سند هر سند کاربر در مجموعه باید شناسه کاربری Firebase Authentication کاربر باشد.
    • هر سند کاربر باید یک فیلد email حاوی آدرس ایمیل کاربر داشته باشد.

  5. اختیاری: یک مجموعه قالب تنظیم کنید.

    شما می‌توانید با استفاده از قالب‌های Handlebars ایمیل‌ها را رندر کنید. برای انجام این کار، به یک مجموعه Cloud Firestore نیاز دارید که قالب‌های شما را در خود جای دهد.

    برای جزئیات بیشتر به بخش «استفاده از قالب‌های Handlebars با افزونه Trigger Email» مراجعه کنید.

افزونه را نصب کنید

برای نصب افزونه، مراحل موجود در صفحه نصب Firebase Extension را دنبال کنید. به طور خلاصه، یکی از موارد زیر را انجام دهید:

  • کنسول Firebase : روی دکمه زیر کلیک کنید:

    افزونه‌ی Trigger Email را نصب کنید

  • رابط خط فرمان (CLI): دستور زیر را اجرا کنید:

    firebase ext:install firebase/firestore-send-email --project=projectId-or-alias

هنگام نصب افزونه، از شما خواسته می‌شود اطلاعات اتصال SMTP و مجموعه‌های Cloud Firestore که قبلاً تنظیم کرده‌اید را مشخص کنید.

از افزونه استفاده کنید

پس از نصب، این افزونه تمام نوشته‌های سند را در مجموعه‌ای که پیکربندی کرده‌اید، نظارت می‌کند. ایمیل بر اساس محتویات فیلدهای سند تحویل داده می‌شود. فیلدهای سطح بالا، فرستنده و گیرنده ایمیل را مشخص می‌کنند. فیلد message شامل جزئیات ایمیلی است که باید تحویل داده شود، از جمله متن ایمیل.

مثال: ارسال ایمیل

برای ارسال یک پیام ساده، یک سند به مجموعه پیام‌های خود اضافه کنید که شامل یک فیلد to و یک فیلد message با محتوای زیر باشد:

to: ['someone@example.com'],
message: {
  subject: 'Hello from Firebase!',
  text: 'This is the plaintext section of the email body.',
  html: 'This is the <code>HTML</code> section of the email body.',
}

فیلدهای فرستنده و گیرنده

فیلدهای سطح بالای سند، اطلاعات فرستنده و گیرنده ایمیل را ارائه می‌دهند. فیلدهای موجود عبارتند از:

  • از: آدرس ایمیل فرستنده. اگر در سند مشخص نشده باشد، از پارامتر پیکربندی شده "آدرس پیش‌فرض از" استفاده می‌کند.
  • replyTo: آدرس ایمیل پاسخ. اگر در سند مشخص نشده باشد، از پارامتر پیکربندی شده "آدرس پیش‌فرض پاسخ" استفاده می‌کند.
  • به: یک آدرس ایمیل گیرنده یا آرایه‌ای شامل چندین آدرس ایمیل گیرنده.
  • toUids: آرایه‌ای شامل UIDهای گیرنده.
  • cc: یک آدرس ایمیل گیرنده یا آرایه‌ای شامل چندین آدرس ایمیل گیرنده.
  • ccUids: آرایه‌ای شامل شناسه‌های کاربری گیرنده‌ی CC.
  • bcc: یک آدرس ایمیل گیرنده یا آرایه‌ای شامل چندین آدرس ایمیل گیرنده.
  • bccUids: آرایه‌ای شامل شناسه‌های کاربری گیرنده BCC.
  • هدرها: یک شیء از فیلدهای هدر اضافی (برای مثال، {"X-Custom-Header": "value", "X-Second-Custom-Header": "value"} ).

نکته: گزینه‌های toUids ، ccUids و bccUids ایمیل‌ها را بر اساس UIDهای کاربری که به آدرس‌های ایمیل درون یک سند Cloud Firestore متصل شده‌اند، ارسال می‌کنند. برای استفاده از این گزینه‌های گیرنده، باید یک مجموعه Cloud Firestore برای پارامتر "مجموعه کاربران" افزونه تعیین کنید. سپس افزونه می‌تواند فیلد email را برای هر UID مشخص شده در فیلدهای toUids ، ccUids و/یا bccUids بخواند.

فیلد پیام

فیلد message سند حاوی اطلاعات خام تحویل ایمیل است. این فیلد معمولاً فقط باید توسط کد معتبری که در سرورهای خودتان یا توابع ابری اجرا می‌شود، پر شود (به بخش «قوانین امنیتی و ارسال ایمیل» در زیر مراجعه کنید).

ویژگی‌های موجود برای فیلد message عبارتند از:

  • messageId: یک هدر شناسه پیام برای ایمیل، در صورت وجود.
  • subject: موضوع ایمیل.
  • متن: محتوای متن ساده ایمیل.
  • html: محتوای HTML ایمیل.
  • amp: محتوای AMP4EMAIL ایمیل.
  • پیوست‌ها: آرایه‌ای شامل پیوست(ها)؛ گزینه‌های پشتیبانی‌شده توسط Nodemailer : رشته utf-8، نوع محتوای سفارشی، URL، رشته کدگذاری‌شده، URI داده و گره MIME از پیش تولیدشده (توجه داشته باشید که ایمیل شما به سیستم فایل سرور ابری دسترسی ندارد).

استفاده پیشرفته

درباره کاربردهای پیشرفته‌تر این افزونه بیشتر بدانید: