استخدام إضافة 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.',
  },
})

يمكنك أيضًا اختياريًا ضبط هذه الإضافة لعرض الرسائل الإلكترونية باستخدام نماذج المقبضات:

الإعداد المسبق

قبل تثبيت الإضافة، أكمِل الخطوات التالية:

  1. إعداد خدمة البريد الصادر

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

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

    تبحث إضافة "الرسالة الإلكترونية المشغِّلة" عن مستندات جديدة في 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.',
}

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

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

  • from: عنوان البريد الإلكتروني للمُرسِل. في حال عدم تحديدها في المستند، يتم استخدام المَعلمة "عنوان المُرسِل التلقائي" التي تم ضبطها.
  • الرد على: عنوان البريد الإلكتروني للردّ. إذا لم يتم تحديد ذلك في المستند، سيتم استخدام "عنوان REPLY-TO التلقائي" الذي تم ضبطه. .
  • 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 في المستند على معلومات تسليم أولية البريد الإلكتروني. يجب عدم ملء هذا الحقل بشكل عام إلا برمز موثوق به يتم تشغيله في خوادمك الخاصة أو دوال السحابة (راجع "قواعد الأمان وإرسال بريد إلكتروني" أدناه).

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

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

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

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