استخدام إضافة 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. أنشئ مجموعة مستندات عبر البريد الإلكتروني.

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

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

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

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

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

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

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

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

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

    راجِع استخدام نماذج Handlebars مع إضافة Trigger Email للحصول على التفاصيل.

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

لتثبيت الإضافة، اتّبِع الخطوات الواردة في صفحة تثبيت الإضافة 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.',
}

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

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

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

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

حقل الرسالة

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

في ما يلي السمات المتاحة لحقل message:

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

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

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