استخدام إضافة Trigger Email

تتيح لك إضافة "إرسال رسالة إلكترونية عند حدوث إجراء" (firestore-send-email) إرسال رسائل إلكترونية تلقائيًا استنادًا إلى المستندات في مجموعة Cloud Firestore. تؤدي إضافة مستند إلى المجموعة إلى تفعيل هذه الإضافة لإرسال رسالة إلكترونية تم إنشاؤها من حقول المستند. تحدّد الحقول ذات المستوى الأعلى في المستند مرسِل الرسالة الإلكترونية و المستلِمين، بما في ذلك الخيارات to وcc وbcc (يدعم كل منها أرقام تعريف المستخدمين). يحدّد حقل 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. إعداد خدمة البريد الصادر

    عند تثبيت إضافة "إرسال رسالة إلكترونية عند حدوث إجراء"، عليك تحديد تفاصيل الاتصال والمصادقة لخادم SMTP الذي تستخدمه الإضافة لإرسال الرسائل الإلكترونية. عادةً ما يتم توفير هذه التفاصيل من خلال خدمة إرسال الرسائل الإلكترونية، مثل Sendgrid أو Mailgun أو Mailchimp Transactional Email، ولكن يمكن أن يكون أيضًا خادمًا تديره بنفسك.

  2. إنشاء مجموعة مستندات للرسائل الإلكترونية

    تستمع إضافة "إرسال رسالة إلكترونية عند حدوث إجراء" إلى المستندات الجديدة في مجموعة Cloud Firestore التي تحدّدها. عند العثور على مستند جديد، ترسل الإضافة رسالة إلكترونية استنادًا إلى حقول المستند. يمكنك استخدام أي Cloud Firestore مجموعة لهذا الغرض، وتستخدِم الأمثلة الواردة في هذه الصفحة مجموعة باسم email.

  3. إعداد قواعد الأمان لمجموعة مستندات الرسائل الإلكترونية

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

    ستختلف قواعد الأمان من تطبيق لآخر، ولكن عليك دائمًا التأكّد من إرسال الرسائل الإلكترونية إلى المستلِمين المقصودين فقط والحدّ قدر الإمكان من المحتوى الحر. يمكن أن تساعدك النماذج في ذلك، إذ يمكنك استخدام قواعد الأمان للتحقّق من أنّ البيانات التي يتم ملؤها في النموذج تتطابق مع توقعاتك بشأن ما يُسمح للمستخدم بتفعيله.

  4. اختياري: إعداد مجموعة مستخدمين

    في إطار الاستخدام الأساسي لهذه الإضافة، يمكنك تحديد مستلِمي الرسالة الإلكترونية من خلال تحديد عناوين بريدهم الإلكتروني في الحقول to وcc وbcc في مستند الرسالة. كبديل لذلك، إذا كان لديك قاعدة بيانات مستخدمين في Cloud Firestore، يمكنك تحديد المستلِمين باستخدام أرقام تعريف المستخدمين. لكي ينجح ذلك، يجب أن تستوفي مجموعة المستخدمين المعايير التالية:

    • يجب أن تستند المجموعة إلى أرقام تعريف المستخدمين. أي يجب أن يكون رقم تعريف مستند كل مستند مستخدم في المجموعة هو رقم تعريف مستخدم Firebase Authentication.
    • يجب أن يحتوي مستند كل مستخدم على حقل email يتضمّن عنوان البريد الإلكتروني للمستخدم.

  5. اختياري: إعداد مجموعة نماذج

    يمكنك عرض الرسائل الإلكترونية باستخدام نماذج Handlebars. لإجراء ذلك، ستحتاج إلى مجموعة Cloud Firestore تحتوي على نماذجك.

    يُرجى الاطّلاع على مقالة استخدام نماذج Handlebars مع إضافة "إرسال رسالة إلكترونية عند حدوث إجراء" لمزيد من التفاصيل.

تثبيت الإضافة

لتثبيت الإضافة، اتّبِع الخطوات الواردة في صفحة تثبيت Firebase Extension. باختصار، يمكنك إجراء أحد الإجراءَين التاليَين:

عند تثبيت الإضافة، سيُطلب منك تحديد معلومات اتصال 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.',
}

حقول المرسِل والمستلِم

توفّر الحقول ذات المستوى الأعلى في المستند معلومات مرسِل الرسالة الإلكترونية والمستلِم. الحقول المتاحة هي:

  • from: عنوان البريد الإلكتروني للمُرسِل إذا لم يتم تحديده في المستند، يتم استخدام المعلمة "عنوان المرسِل التلقائي" الذي تم ضبطه.
  • replyTo: عنوان البريد الإلكتروني للرد إذا لم يتم تحديده في المستند، يتم استخدام المعلمة "عنوان الرد التلقائي" الذي تم ضبطه.
  • to: عنوان بريد إلكتروني واحد للمستلِم أو صفيف يحتوي على عناوين بريد إلكتروني متعددة للمستلِمين
  • toUids: صفيف يحتوي على أرقام تعريف المستلِمين
  • cc: عنوان بريد إلكتروني واحد للمستلِم أو صفيف يحتوي على عناوين بريد إلكتروني متعددة للمستلِمين
  • ccUids: صفيف يحتوي على أرقام تعريف المستلِمين في الحقل "نسخة إلى"
  • bcc: عنوان بريد إلكتروني واحد للمستلِم أو صفيف يحتوي على عناوين بريد إلكتروني متعددة للمستلِمين
  • bccUids: صفيف يحتوي على أرقام تعريف المستلِمين في الحقل "نسخة مخفية الوجهة"
  • headers: عنصر من حقول الرأس الإضافية (على سبيل المثال، {"X-Custom-Header": "value", "X-Second-Custom-Header": "value"})

ملاحظة: يرسل الخياران toUids وccUids وbccUids رسائل إلكترونية استنادًا إلى أرقام تعريف المستخدمين المرتبطة بعناوين البريد الإلكتروني ضمن مستند Cloud Firestore. لاستخدام خيارات المستلِم هذه، عليك تحديد مجموعة Cloud Firestore لمعلمة "مجموعة المستخدمين" في الإضافة. يمكن للإضافة بعد ذلك قراءة الحقل email لكل رقم تعريف مستخدم محدّد في الحقول toUids وccUids و/أو bccUids.

حقل الرسالة

يحتوي حقل message في المستند على معلومات الإرسال الأولية للرسالة الإلكترونية. يجب عادةً أن يتم ملء هذا الحقل فقط من خلال رمز موثوق به يتم تشغيله على الخوادم الخاصة بك أو في Cloud Functions (يُرجى الرجوع إلى قسم "قواعد الأمان وإرسال الرسائل الإلكترونية" أدناه).

الخصائص المتاحة لحقل message هي:

  • messageId: رأس رقم تعريف الرسالة للرسالة الإلكترونية، إن وُجد
  • subject: موضوع الرسالة الإلكترونية
  • text: محتوى الرسالة الإلكترونية بنص عادي
  • html: محتوى الرسالة الإلكترونية بتنسيق HTML
  • amp: محتوى الرسالة الإلكترونية بتنسيق AMP4EMAIL
  • attachments: صفيف يحتوي على المرفقات، وخيارات Nodemailer المتوافقة هي: سلسلة بترميز UTF-8 ونوع محتوى مخصّص وعنوان URL وسلسلة بترميز Base64 ومعرّف موارد البيانات(URI) للبيانات وعقدة MIME تم إنشاؤها مسبقًا (يُرجى العِلم أنّه لا يمكن لرسالتك الإلكترونية الوصول إلى نظام ملفات الخادم السحابي)

الاستخدام المتقدّم

تعرَّف على المزيد من المعلومات عن الاستخدام المتقدّم لهذه الإضافة: